samagotchi 0.129.0 → 0.130.1

data/docs/sessions.md

@@ -1,12 +1,12 @@
 # Sessions
 
-Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
+Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`owner.lock`/`bridge.json` (`Session.session_dir`), and `tool_output/` once a long `execute` result was cut: its whole output, which the cut result names (`ToolOutputFiles`, the newest 50 kept; see [Tool output guardrails](internals/tool-guardrails.md#the-runners-cut-max_tool_output_chars)). Besides the messages and turn state, the JSON keeps `written_by` (the chi version that saved it last; see *Which chi a worker runs*), `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, `prompt_notes`, the model notes the system prompt carried at its last build (`[{name, scope, chars, digest}]`, see [Memory](memory.md#model-notes)), `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise), and `continues`, the session this one continues (the previous link of a chain, see *Session chains*; `null` otherwise); files from before those keys read as empty lists, no parent and no previous link. `model_name` is the resolved model ref (an alias applied, `host:id` when it names a host), so a resumed session keeps its model when an alias is retargeted; `model_typed` is the name it was given as when that differs (an alias), for the `models:` lookup after a resume (`null` otherwise).
 
 **Message times:** an entry of `messages` may carry `at`, when it happened: a local-offset ISO time with milliseconds (`2026-10-24T14:32:05.120+02:00`). User prompts, lines merged into a turn and steers, reminders, context and task notes, and the model's replies have one (a note's is its `created_at`); tool results, `!cmd` messages and chi's own turn notes don't, nor does anything saved before chi stamped messages (no backfill). It is for the UIs only (the gap dividers, a bubble's time): it never goes to the model, so it changes nothing in the requests or their prompt cache. The one time the model reads is the reminders': due reminders go into a turn as a system message headed `[SYSTEM: REMINDERS DUE 2026-10-24 14:32 local]` (the turn's local time; `ReminderQueue#inject!`), written into the saved content then, so a later request sends the same text.
 
 **Verify verdicts:** a web Verify turn stamps its opening user message with `verify: {turn_id, quote}` (the selected source turn and quote; metadata only, never added to the prompt). When that turn completes and the final assistant reply's last non-empty line is a valid `Verdict: confirmed|refuted|unclear — <reason>`, the session file appends `{anchor: {turn_id, quote}, verdict, reason, by, check_turn_id, at}` to its optional `verdicts` array. `by` is the turn's author (nil for the owner), `check_turn_id` names the Verify turn, and `at` is its timestamp. The array is append-only; older files without it have no saved verdicts. An `unclear` verdict can be checked again by **Verify fresh** (a delegate child that gets only the claim; see *Delegating*): its verdict is appended to the parent's `verdicts` with `fresh: true`, `of` (the verdict it checked again) and `child_id`, from the parent's `fresh_verdicts/` dir, which its worker takes between turns. Verdicts are display state: none enters a prompt.
 
-**Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). A session command recognized in a file runs without a turn; its outcome is kept at `input/settled/<enqueued_id>` (`completed`, `failed` for a command error, `canceled` with `cancel_reason` `busy` or `dropped` for one refused mid-turn or dropped as the worker left; `origin: command`) so `chi send --wait` ends instead of waiting for a turn that will not run, its detail saying `the command failed` or `the command was refused (busy)` rather than a turn's words. **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
+**Input files:** a message for a session's worker waits in `input/<timestamp>.json` (`SessionInbox.write_input`: `prompt`, `client_id`, `enqueued_id`, and `images`, `no_interrupt` and `delivery` when they apply; `delivery` is written only for `"queue"`). While a turn runs, the worker merges them at each step boundary in name order, except a queued one or one with images: those wait for the turn's end and run one turn each, in name order, and a file after them still merges (`Worker#pending_input_drain`). Such a file, with a prompt, from the user, `chi send` or a delegating parent, also ends a running `task_wait` (`SessionInbox.steer_waiting?`, a peek the worker's turn polls through `Engine#input_waiting?`; never in a participant's turn): the file stays for the drain. A queue is sent only to a worker whose `bridge.json` names the `delivery` feature; an older one would steer it, so `SessionManager.deliver_turn` refuses it (409 `delivery_unavailable`), and any other 4xx the Bridge answers is a refusal too, never a fallback file (except a 413, a body over its size limit: that one still goes in as a file, its `delivery` kept). A session command recognized in a file runs without a turn; its outcome is kept at `input/settled/<enqueued_id>` (`completed`, `failed` for a command error, `canceled` with `cancel_reason` `busy` or `dropped` for one refused mid-turn or dropped as the worker left; `origin: command`) so `chi send --wait` ends instead of waiting for a turn that will not run, its detail saying `the command failed` or `the command was refused (busy)` rather than a turn's words. **Reply files:** a turn that ends with visible text leaves its reply in `output/<timestamp>.txt`, or `output/<timestamp>-<enqueued_id>.txt` when the turn ran an input file with an id (`SessionInbox.write_output`), and the session's `last_turn` keeps that `enqueued_id`; so a wait for one queued message (`chi send --queue --wait`, `ReplyWait`'s `turn:`) finds its own turn's reply or end, never another turn's. The names still sort by time, and every reader takes `*.txt`.
 
 **Removing a queued message:** a message queued for after the running turn (`chi send --queue`, the web's Alt+Enter, `/queue TEXT` in a terminal), or one with images (it waits for the turn's end too), can be taken back while it still waits: the worker's Bridge (`POST /session/:id/turn/dequeue {enqueued_id}`, the `unqueue` feature) deletes its input file and every UI drops it (`:turn_dequeued`). It is a race with the turn's end, decided by the same rename the worker uses to take the file: once a turn took it the answer is `409 already_started` (it runs), and an id the worker no longer knows is `404 unknown_enqueued_id`. A plain message sent without `--queue` is not removable (`409 not_queued`): a running turn's next step may take it at any moment. A wait for its turn (`chi send --queue --wait`, a delegate follow-up's wait) ends at once with `removed` (the tombstone `input/removed/<enqueued_id>` says so), and a `chi -p` run whose queued prompt went ends with exit 1. The `200` carries the removed `prompt`: the web and the attached terminal put it back into the composer to edit (not its images). The images a removed message named stay in the session's `images/`. Not removable: a queued session command (`/queue /model x`: it waits in the worker, not in `input/`), a message in a stopped worker's inbox (the next worker runs it), and the plain REPL's (`--no-shared`) own queue.
 
@@ -29,7 +29,9 @@ A session is deleted if **expired by age OR overflow by count** (unless `keep_st
 
 **Attached by default:** plain `chi` and `chi --resume ID` run their session in a background worker and attach to it (`session.shared`, default `true`; env `SAMAGOTCHI_SESSION_SHARED`). The worker runs in the session's `working_directory`, so `!commands` and tools see the directory the session was started in. `session.shared: false` keeps the in-process REPL, `--no-shared` does for one run; a session the REPL has open can't be attached ("close it there first"). See [CLI: Sharing a session](cli.md#sharing-a-session).
 
-**Which chi a worker runs:** a new or woken worker runs the newest chi installed for this Ruby (`gem 'samagotchi', '>= 0.a'`, prereleases count), whoever starts it: a `chi web` or terminal still on an older chi starts it on the newest one, so a stale process doesn't spread old code. A worker already running keeps its version until it is restarted. Should the newest install fail to load, the worker runs the starter's own version and logs `boot_fallback` (its stdio is `/dev/null`). Under `bundle exec` the worker drops Bundler's env first, so it activates the newest gem too. Two consequences: a wrapper pin (`chi _0.17.0_ web`) pins only that process, not the workers it starts; and a source checkout (`bin/chi` in a worktree, `bundle exec`) starts its workers on its own `lib/`, but a session it made that is later woken by an installed chi (`chi web`, `chi send`) runs the installed code. The names an older starter hands a newer worker (the boot line, its env keys, `input/` files, the session JSON fields and the Bridge routes sessions use on each other) are pinned in `spec/worker_contract_spec.rb`.
+**Which chi a worker runs:** a new or woken worker runs the newest chi installed for this Ruby (`gem 'samagotchi', '>= 0.a'`, prereleases count), whoever starts it: a `chi web` or terminal still on an older chi starts it on the newest one, so a stale process doesn't spread old code. A worker already running keeps its version until it is restarted. Should the newest install fail to load, the worker runs the starter's own version and logs `boot_fallback` (its stdio is `/dev/null`). Under `bundle exec` the worker drops Bundler's env first, so it activates the newest gem too. Two consequences: a wrapper pin (`chi _0.17.0_ web`) pins only that process, not the workers it starts; and a source checkout (`bin/chi` in a worktree, `bundle exec`) starts its workers on its own `lib/`, but a session it made that is later woken by an installed chi (`chi web`, `chi send`) runs the installed code. The names an older starter hands a newer worker (the boot line, its env keys, `input/` files, the session JSON fields and the Bridge routes sessions use on each other) are pinned in `spec/worker_contract_spec.rb`. A chi newer than 0.130.0 keeps the top-level keys it doesn't know (a newer chi's fields) when it saves a session, after its own, and doesn't act on them; `written_by` names the chi that saved the file last, and a worker woken on a file a newer chi saved logs `newer_writer`. chi 0.130.0 and older drop those keys: a session a newer chi made loses its newer fields when an older chi wakes or saves it (for example `chi --attach` from a project whose Ruby has an older chi). Keep the chi in every Ruby you run it from newer than 0.130.0.
+
+A new session field (the rule in `Session::FIELDS`' comment): only top-level keys are kept (a new sub-key of `review`, `toolkit` or another value object is still dropped by an older chi), and an older chi keeps a key without honouring it, so a new field must be safe to come back unchanged after an older chi ran turns on the session.
 
 **A worker outlives whoever started it:** a spawned worker leaves its spawner's process tree (it is forked again, in a session of its own, and reparented to init), so closing the terminal of a `chi web`, or a tool tearing down a background `chi send --wait` and its children, no longer takes the worker and its turn with it.
 

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

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

data/lib/samagotchi/desktop/macos.rb

@@ -41,9 +41,11 @@ module Samagotchi
       BUILD_NAME = ".chi-helper-build"
       OLD_NAME = ".chi-helper-old"
       # Apps started by launchd get a bare env (no shell rc files), so the
-      # launch file carries what chi needs to find its gems and state. Only
-      # these, and only when set: no tokens, no runtime knobs.
+      # launch file carries what chi needs to find its gems, state and tools.
+      # Only these, and only when set: no tokens, no runtime knobs.
       ENV_ALLOWLIST = %w[XDG_CONFIG_HOME XDG_STATE_HOME GEM_HOME GEM_PATH RUBYLIB].freeze
+      # PATH is separately filtered to absolute dirs and frozen when written,
+      # so the helper's chi, workers and execute can find the shell's tools.
       # Without it Ruby reads stdin as US-ASCII and non-ASCII notes break.
       LANG = "en_US.UTF-8"
       # chi broadcast's default triage deadline, and the helper's seconds on
@@ -54,6 +56,17 @@ module Samagotchi
       # one launch-file section each, in this order.
       TERMINALS = %w[kitty tmux].freeze
 
+      # PATH dirs the helper can use from launchd's / working directory:
+      # keep absolute entries only, in order, once each.
+      def self.path_dirs(env)
+        env["PATH"].to_s.split(File::PATH_SEPARATOR).select { _1.start_with?("/") }.uniq
+      end
+
+      def self.baked_path(env)
+        dirs = path_dirs(env)
+        dirs.empty? ? nil : dirs.join(File::PATH_SEPARATOR)
+      end
+
       # Runs a command without a shell; [output, success].
       class Runner
         def run(argv)
@@ -76,7 +89,8 @@ module Samagotchi
 
       # The tmux: settings, or nil while tmux.enabled is off. The binary is
       # tmux.binary, else the tmux on +env+'s PATH ("" when there is none:
-      # see #warnings); the socket dir is where tmux puts `-L` sockets
+      # only absolute dirs are usable from launchd; see #warnings); the socket
+      # dir is where tmux puts `-L` sockets
       # ($TMUX_TMPDIR when it is a directory, else /tmp, then tmux-<uid>).
       # Both are frozen at bake time, like the rest of the launch file.
       def self.tmux_settings(get = Config.method(:get), env: ENV)
@@ -91,8 +105,7 @@ module Samagotchi
       end
 
       def self.path_tmux(env)
-        env["PATH"].to_s.split(File::PATH_SEPARATOR).reject(&:empty?).map { File.join(_1, "tmux") }
-                   .find { File.file?(_1) && File.executable?(_1) }.to_s
+        path_dirs(env).map { File.join(_1, "tmux") }.find { File.file?(_1) && File.executable?(_1) }.to_s
       end
 
       # Each switched-on terminal's settings by name ("kitty" => …).
@@ -148,10 +161,14 @@ module Samagotchi
       # `gem cleanup`), else this checkout's bin/chi. A section per terminal
       # switched on (TERMINALS order); the broadcast timeout when given.
       # The XDG dirs go in absolute (Paths): launchd starts the app in /,
-      # where a relative one would mean /<dir>.
+      # where a relative one would mean /<dir>. PATH is filtered to absolute,
+      # deduplicated dirs so chi, its workers and execute find shell tools;
+      # it is frozen at bake time.
       def launch_config
         env = { "LANG" => LANG }
         ENV_ALLOWLIST.each { |name| env[name] = @env[name] unless @env[name].to_s.empty? }
+        path = self.class.baked_path(@env)
+        env["PATH"] = path if path
         env.merge!(Paths.absolute_xdg(env: env, set: :key))
         config = { "version" => @version, "argv" => [@ruby, @chi_path], "env" => env, "sources_sha" => sources_sha }
         TERMINALS.each { |name| config[name] = @terminals[name] if @terminals[name] }
@@ -178,22 +195,55 @@ module Samagotchi
         launch["sources_sha"] != sources_sha || !launch_ok?(launch)
       end
 
-      # The launch file names another chi version or path than this one, or
-      # other terminal settings or broadcast timeout: refresh_launch_file
-      # fixes that without a rebuild.
+      # The launch file names an older chi version than this one (or none), or
+      # other terminal settings, broadcast timeout or a missing bakeable PATH:
+      # refresh_launch_file fixes that without a rebuild. A different argv or
+      # baked PATH, or a newer version, is intentional: the ruby, chi and PATH
+      # the helper runs change only with chi desktop install --force or upgrade.
       def launch_outdated?
         launch = read_launch
-        launch["version"] != @version || Array(launch["argv"]) != launch_config["argv"] ||
+        older_version?(launch["version"]) ||
           TERMINALS.map { launch[_1] } != TERMINALS.map { @terminals[_1] } ||
-          launch["broadcast_timeout"] != @broadcast_timeout
+          launch["broadcast_timeout"] != @broadcast_timeout || path_missing?(launch)
+      end
+
+      # Why chi update can't keep the launch file's ruby or chi: one of them
+      # is gone. nil when it runs, or has no usable argv (a refresh writes
+      # this chi's then).
+      def launch_problem
+        argv = usable_argv(read_launch)
+        missing = Array(argv).reject { |path| File.exist?(path) }
+        return nil if missing.empty?
+
+        "chi not found at #{missing.join(", ")}: run chi desktop install --force from the shell whose chi it should run"
+      end
+
+      # The chi version the launch file names, nil without one.
+      def launch_version = read_launch["version"]
+
+      # The launch file names a newer chi than this one: an older chi's
+      # chi update keeps the helper as it is (no rebuild from older sources).
+      def launch_newer?
+        Gem::Version.new(launch_version.to_s) > Gem::Version.new(@version)
+      rescue ArgumentError
+        false
       end
 
       # Rewrite the launch file for this chi and its settings, keeping
-      # the env it was installed with. The app reads it at each send: no restart.
+      # its argv and the env it was installed with; a PATH only when it has
+      # none (changing them takes chi desktop install --force or upgrade). A
+      # newer version stays. The app reads it at each send.
       def refresh_launch_file
         config = launch_config
-        env = read_launch["env"]
-        config["env"] = env if env.is_a?(Hash)
+        old = read_launch
+        config["argv"] = usable_argv(old) || config["argv"]
+        config["version"] = old["version"] unless older_version?(old["version"])
+        old_env = old["env"]
+        if old_env.is_a?(Hash)
+          config["env"] = old_env
+          path = self.class.baked_path(@env)
+          config["env"]["PATH"] = path if config["env"]["PATH"].to_s.empty? && path
+        end
         write_launch_file(config)
       end
 
@@ -242,7 +292,9 @@ module Samagotchi
 
       # @yield [String] progress lines
       # @param login [Boolean] also start the app at login
-      def install(force: false, login: false, &progress)
+      # @param keep_launch [Boolean] keep the launch file's ruby, chi and PATH
+      #   (chi update's rebuild) instead of baking this shell's
+      def install(force: false, login: false, keep_launch: false, &progress)
         raise Error, "already installed (#{app_version}); use chi desktop upgrade" if installed? && !force
 
         toolchain!
@@ -250,7 +302,7 @@ module Samagotchi
         progress&.call("building #{APP_NAME} #{@version} (can take a few minutes)…")
         built = build_app
         swap_in(built)
-        write_launch_file
+        write_launch_file(keep_launch: keep_launch)
         register_app
         self.login = true if login
         progress&.call("installed #{app_path}")
@@ -258,9 +310,9 @@ module Samagotchi
       end
 
       # Keeps the login item as it was.
-      def upgrade(&)
+      def upgrade(keep_launch: false, &)
         was_login = installed? && login == "enabled"
-        install(force: true, login: was_login, &)
+        install(force: true, login: was_login, keep_launch: keep_launch, &)
       end
 
       # SMAppService status as the app reports it ("enabled",
@@ -313,6 +365,7 @@ module Samagotchi
           launch_ok: launch_ok?(launch),
           stale: stale?,
           baked_dirs: env.select { |name, _| name.start_with?("XDG_") },
+          baked_path: env["PATH"],
           service: dump.include?(BUNDLE_ID),
           running: running,
           host_keys: host_keys
@@ -393,12 +446,39 @@ module Samagotchi
         {}
       end
 
+      # This chi is newer than the version the launch file names; a missing or
+      # unreadable version counts as older.
+      def older_version?(version)
+        Gem::Version.new(@version) > Gem::Version.new(version.to_s)
+      rescue ArgumentError
+        true
+      end
+
+      def usable_argv(launch)
+        argv = launch["argv"]
+        argv if argv.is_a?(Array) && !argv.empty? && argv.all? { |path| path.is_a?(String) && !path.empty? }
+      end
+
+      def path_missing?(launch)
+        return false unless self.class.baked_path(@env)
+
+        env = launch["env"]
+        !env.is_a?(Hash) || env["PATH"].to_s.empty?
+      end
+
       def launch_ok?(launch)
         argv = Array(launch["argv"])
         !argv.empty? && argv.all? { |path| File.exist?(path) }
       end
 
-      def write_launch_file(config = launch_config)
+      def write_launch_file(config = launch_config, keep_launch: false)
+        if keep_launch
+          old = read_launch
+          config["argv"] = usable_argv(old) || config["argv"]
+          old_env = old["env"]
+          old_path = old_env["PATH"] if old_env.is_a?(Hash)
+          config["env"]["PATH"] = old_path unless old_path.to_s.empty?
+        end
         FileUtils.mkdir_p(@support_dir)
         AtomicFile.write(launch_path, JSON.pretty_generate(config) + "\n")
       end

data/lib/samagotchi/desktop_command.rb

@@ -118,11 +118,12 @@ module Samagotchi
                   "#{s[:app_version] || "?"} (up to date: chi #{s[:chi_version]} changed nothing in it)"
                 end
       launch = s[:launch_argv].empty? ? "(none)" : s[:launch_argv].join(" ")
-      launch += s[:launch_ok] ? " (ok)" : " (missing: chi update)"
+      launch += s[:launch_ok] ? " (ok)" : " (missing: chi desktop install --force)"
       dirs = s[:baked_dirs].empty? ? "(defaults)" : s[:baked_dirs].map { |name, value| "#{name}=#{value}" }.join(" ")
+      path = path_row(s[:baked_path])
       service = s[:service] ? "registered" : "not registered (try chi desktop upgrade, or log out and back in)"
       running = s[:running] ? "running" : "not running (open -g \"#{s[:app_path]}\")"
-      rows = [["Chi Helper", version], ["app", s[:app_path]], ["runs chi", launch], ["state dirs", dirs],
+      rows = [["Chi Helper", version], ["app", s[:app_path]], ["runs chi", launch], ["state dirs", dirs], ["PATH", path],
               ["service", service], ["hotkey", hotkey(s[:hotkey])], ["process", running], ["at login", login(s[:login])]]
       rows << ["host keys", host_keys(s[:host_keys])] unless Array(s[:host_keys]).empty?
       @stdout.puts(format_rows(rows))
@@ -153,6 +154,10 @@ module Samagotchi
       end
     end
 
+    def path_row(path)
+      path.to_s.empty? ? "(none: macOS's default; chi update fills it, chi desktop install --force changes it)" : path
+    end
+
     def format_rows(rows)
       width = rows.map { |label, _| label.length }.max
       rows.map { |label, value| "#{label.ljust(width)}  #{value}" }.join("\n")

data/lib/samagotchi/engine.rb

@@ -664,6 +664,19 @@ module Samagotchi
       @turn_state.controller
     end
 
+    # Whether a message a person sent waits for the running turn's next
+    # boundary (run_turn's input_waiting: probe): a task_wait returns on it
+    # (PeerView#input_waiting?). False outside a turn, for a turn given no
+    # probe, and when the probe raises (warned once a turn; the tool never
+    # fails for it).
+    def input_waiting?
+      probe = @turn_state.input_waiting
+      !!probe&.call
+    rescue StandardError => e
+      Log.warn(:turn, "input_waiting_failed", error: e.class.name, msg: e.message) if @turn_state.input_waiting_failed!
+      false
+    end
+
     # Cancel the currently running turn, if any.
     # @param reason [Symbol] cancellation reason
     # @return [Boolean] whether a cancellation was triggered
@@ -2132,6 +2145,9 @@ module Samagotchi
     # @param pending_input [#call, nil] optional drain proc returning
     #   Array<String> of steering messages queued while the turn runs; drained
     #   by the agentic loop at iteration boundaries (see KernelLoop#run).
+    # @param input_waiting [#call, nil] optional probe: true while a message
+    #   a person sent waits for the next boundary (it peeks, never drains);
+    #   a running task_wait returns on it (#input_waiting?). nil: never.
     # @param continue [Boolean] resume the conversation without appending a
     #   user prompt (continue after the iteration limit, reminder turns);
     #   +prompt+ is ignored and :turn_started carries `continue: true`
@@ -2170,9 +2186,9 @@ module Samagotchi
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
     def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false,
-                 origin: TurnOrigin::NONE, images: [], id: nil, resumed: false, resume_from: nil, verify: nil)
+                 origin: TurnOrigin::NONE, images: [], id: nil, resumed: false, resume_from: nil, verify: nil, input_waiting: nil)
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
-                                         continue: continue, id: id, verify: verify)
+                                         continue: continue, id: id, verify: verify, input_waiting: input_waiting)
       if continue
         turn.resumed = resumed
         turn.resume_from = resume_from
@@ -2220,7 +2236,7 @@ module Samagotchi
     # The turn's state before anything can fail it: the session running,
     # the turn flag, its cancel controller and sink. The cross-thread state
     # is set here and cleared in #release_turn only.
-    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil, verify: nil)
+    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil, verify: nil, input_waiting: nil)
       origin = TurnOrigin.of(origin)
       # A participant's Verify fresh child: every turn is theirs (their
       # author, boundary and cap), whoever started it.
@@ -2240,7 +2256,7 @@ module Samagotchi
       # invalidated recap) while the model is working. A hook's notice goes
       # where the turn's events go (the REPL renders only its sink; a
       # worker's observers carry it to the bridge).
-      @turn_state.begin!(controller: effective_controller, sink: on_event)
+      @turn_state.begin!(controller: effective_controller, sink: on_event, input_waiting: input_waiting)
       # Drop a recap already in flight: the turn makes it stale.
       @recap&.invalidate!
       # The gate's context: who queued this turn, and git asked afresh.

data/lib/samagotchi/engine_peers.rb

@@ -8,7 +8,8 @@ module Samagotchi
     # The kernel's Tools::Peers, following the current session. cancelled?
     # is the running turn's cancel, for a tool that waits (delegate_result):
     # the controller is set from another thread and a tool gets no other
-    # way to see it.
+    # way to see it. input_waiting? is whether a person's message waits for
+    # the running turn's next boundary (task_wait returns on it).
     PeerView = Struct.new(:engine) do
       def session_id = engine.session&.id
       def cwd = engine.session&.working_directory
@@ -16,6 +17,7 @@ module Samagotchi
       def state_dir = engine.peer_state_dir
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
       def cancel_reason = engine.active_cancel_controller&.reason
+      def input_waiting? = engine.input_waiting?
       def relay = engine.relay_peer
       def model_ref = engine.effective_model_ref
       def thinking = engine.thinking_override

data/lib/samagotchi/guardrails/chi_dirs.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../paths"
+require_relative "../memory_paths"
+require_relative "../hooks/loader"
+require_relative "path_resolve"
+
+module Samagotchi
+  module Guardrails
+    # chi's own dirs, the sets the guardrails judge a path or a command's
+    # words against, as this process's environment and config.yml name them
+    # (read each call). Each surface keeps its set:
+    #   .protected     the config dir, the hooks dir, the approval store's
+    #                  dir, the installed bundles' dir, attached context: an
+    #                  ask only the user may answer (ParentApprovals.chi_files?)
+    #   .touches       .protected and the session repo's git hooks dir: a
+    #                  rule's touches: chi_dirs (Targets#touches_chi?)
+    #   .self_protect  .protected and the whole state dir, resolved: what
+    #                  System 1 never answers for (SelfProtect)
+    #   .review        the state dir, the config dir and a hooks dir
+    #                  configured outside it: what a participant's turn never
+    #                  reads (ReviewPaths)
+    # ProtectedPaths' deny/ask lists and ScratchWrites' memories dir are
+    # built by the wiring from the same places.
+    module ChiDirs
+      module_function
+
+      # chi's config dir, the hooks dir, the approval store's dir, the
+      # installed bundles' dir and attached context.
+      def protected
+        hooks = begin Hooks::Loader.hooks_dir rescue nil end
+        bundles = begin MemoryPaths.bundles_dir rescue nil end
+        [ConfigFile.config_dir, hooks, File.join(Paths.state_dir, "guardrails"), bundles, File.join(Paths.state_dir, "context")]
+          .compact.map { |dir| dir.to_s.chomp("/") }.reject(&:empty?).uniq
+      end
+
+      # .protected (as ParentApprovals.chi_dirs, the name its callers and
+      # specs know) and the git hooks dir of +base+'s repo (+context+).
+      def touches(context, base)
+        require_relative "parent_approvals"
+        ParentApprovals.chi_dirs + [context.hooks_dir(base)].compact
+      end
+
+      # .protected (as ParentApprovals.chi_dirs) and the whole state dir,
+      # resolved.
+      def self_protect
+        require_relative "parent_approvals"
+        [*ParentApprovals.chi_dirs, Paths.state_dir]
+          .map { |dir| PathResolve.real(dir.to_s.chomp("/")) }.reject(&:empty?).uniq
+      end
+
+      # chi's state dir and config dir, as Paths has them now, and the hooks
+      # dir when config.yml puts it outside the config dir (hooks run as the
+      # owner: a participant reads none of them).
+      def review
+        config = File.join(Paths.config_home, Paths::APP_DIR)
+        hooks = begin Hooks::Loader.hooks_dir rescue nil end
+        hooks = nil if hooks.to_s.empty? || PathResolve.reals(hooks).any? { |real| PathResolve.within?(real, config) }
+        [Paths.state_dir, config, hooks].compact
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/child_boundary.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "outside"
-require_relative "protected_paths"
+require_relative "path_resolve"
 require_relative "shell_lex"
 require_relative "shell_paths"
 require_relative "shared_git"
@@ -88,8 +88,8 @@ module Samagotchi
       # repository (and not into root, which may sit inside the main one),
       # under chi's env or the call's env: (Targets#shell_envs).
       def names_other_checkout?(targets, root)
-        real_root = ProtectedPaths.real(root)
-        others = [*@worktrees.call, @common_dir.call].compact.map { |dir| ProtectedPaths.real(dir) } - [real_root]
+        real_root = PathResolve.real(root)
+        others = [*@worktrees.call, @common_dir.call].compact.map { |dir| PathResolve.real(dir) } - [real_root]
         return false if others.empty?
 
         commands = ShellLex.simple_commands(ShellLex.lex(targets.command.to_s))
@@ -99,8 +99,8 @@ module Samagotchi
             walk.step(words).any? do |_word, path|
               next false unless path
 
-              ProtectedPaths.reals(path).any? do |real|
-                !ShellPaths.within?(real, real_root) && others.any? { |dir| ShellPaths.within?(real, dir) }
+              PathResolve.reals(path).any? do |real|
+                !PathResolve.under?(real, real_root) && others.any? { |dir| PathResolve.under?(real, dir) }
               end
             end
           end

data/lib/samagotchi/guardrails/outside.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
-require "tmpdir"
-require_relative "protected_paths"
+require_relative "path_resolve"
 require_relative "../memory_bundle/index_sync"
 
 module Samagotchi
@@ -20,17 +19,18 @@ module Samagotchi
     # A path whose landing place resolving can't tell (.resolve: a dangling
     # symlink, a file with another hard link) is always outside.
     module Outside
-      TMP_DIRS = %w[/tmp /var/tmp].freeze
+      TMP_DIRS = PathResolve::TMP_DIRS
 
       # @param path [String] absolute
       # @param root [String] the session's repo root (or cwd)
       def self.outside?(path, root:)
         reals = resolve(path) or return true
-        session = ProtectedPaths.real(root)
+        session = PathResolve.real(root)
+        tmp = nil
         reals.any? do |real|
           next false if within?(real, session)
           next false if MemoryBundle::IndexSync.memory_scope(path)
-          next false if tmp_roots.any? { |tmp| within?(real, tmp) && !within?(session, tmp) }
+          next false if (tmp ||= session_tmp_roots(session)).any? { |dir| within?(real, dir) }
 
           true
         end
@@ -44,7 +44,7 @@ module Samagotchi
       # @param root [String] the session's project root
       def self.inside?(path, root:)
         reals = resolve(path) or return false
-        session = ProtectedPaths.real(root)
+        session = PathResolve.real(root)
         reals.all? { |real| within?(real, session) }
       end
 
@@ -55,15 +55,16 @@ module Samagotchi
       # @param root [String] the session's repo root (or cwd)
       def self.tmp_write?(path, root:)
         reals = resolve(path) or return false
-        session = ProtectedPaths.real(root)
-        reals.all? { |real| tmp_roots.any? { |tmp| within?(real, tmp) && !within?(session, tmp) } }
+        session = PathResolve.real(root)
+        tmp = session_tmp_roots(session)
+        reals.all? { |real| tmp.any? { |dir| within?(real, dir) } }
       end
 
-      # +path+ resolved (ProtectedPaths.reals: the lexical answer and where
+      # +path+ resolved (PathResolve.reals: the lexical answer and where
       # the kernel lands, a `..` after a symlinked dir climbing out of its
       # target), or nil when that doesn't say where a write lands: the path
       # is or goes through a dangling symlink (a write would create its
-      # target; ProtectedPaths.real follows it, the lexical answer stops at
+      # target; PathResolve.real follows it, the lexical answer stops at
       # it, and either way the link's own place doesn't count as where the
       # file is), or is a file with another hard link (a write would change
       # that file too). Both outside? and tmp_write? read it, so neither
@@ -71,7 +72,7 @@ module Samagotchi
       # @param path [String] absolute
       # @return [Array<String>, nil]
       def self.resolve(path)
-        reals = ProtectedPaths.reals(path)
+        reals = PathResolve.reals(path)
         return nil if reals.any? { |real| Pathname.new(real).ascend.any?(&:symlink?) }
         return nil if reals.any? { |real| File.file?(real) && File.stat(real).nlink > 1 }
 
@@ -80,16 +81,17 @@ module Samagotchi
         nil
       end
 
-      # The tmp dirs that exist, resolved.
-      def self.tmp_roots
-        [Dir.tmpdir, *TMP_DIRS].filter_map do |dir|
-          File.realpath(dir) if File.directory?(dir)
-        rescue SystemCallError
-          nil
-        end.uniq
-      end
+      # The tmp dirs that exist, resolved (PathResolve.tmp_roots).
+      def self.tmp_roots = PathResolve.tmp_roots
+
+      # The tmp dirs +session+ (resolved) isn't in (PathResolve.tmp_roots).
+      def self.session_tmp_roots(session) = PathResolve.tmp_roots(session: session, roots: tmp_roots)
 
-      def self.within?(path, root) = path == root || path.start_with?(File.join(root, ""))
+      # Whether +path+ is +root+ or in it (PathResolve.under?): cased alike
+      # on a disk that folds case when +root+ exists (resolved, it has its
+      # on-disk case), by their exact text when it doesn't (a missing root
+      # keeps the case it was typed in).
+      def self.within?(path, root) = PathResolve.under?(path, root, fold: File.exist?(root))
     end
   end
 end

data/lib/samagotchi/guardrails/pair_boundary.rb

@@ -25,7 +25,9 @@ module Samagotchi
     #     read or written (read, write, edit, a plugin's targets: paths), and
     #     on what a command does (execute, and any call whose targets carry
     #     a command: PairCommand, which also refuses chi and chi web on a
-    #     loopback name, background and scheduled jobs, the environment and
+    #     loopback name, URL openers (open, xdg-open, a browser) and
+    #     listeners (nc -l, socat …LISTEN, a static HTTP server), background
+    #     and scheduled jobs, the environment and
     #     credential printers, git settings that run commands, home sweeps
     #     and links to them, and a program named by a $var or a glob); a
     #     write or edit of git's hooks (GIT_HOOKS);
@@ -78,8 +80,17 @@ module Samagotchi
       GIT_CONFIG = "a participant's turn can't change git's global config or set what makes git run a command " \
                    "(core.hooksPath, core.fsmonitor, core.sshCommand, core.pager, core.editor, ! aliases)"
       GIT_HOOKS = "a participant's turn can't write git's hooks (.git/hooks): git runs them in the owner's name"
-      CHI_WEB = "a participant's turn can't call chi web on this machine: on loopback it answers as the owner " \
-                "(sessions, shares, answers)"
+      # chi web on loopback asks the owner's token too (Web::App#token_gate,
+      # LAN mode); this text check stays as defense in depth: a loopback-only
+      # chi web still answers loopback as the owner.
+      CHI_WEB = "a participant's turn can't call chi web on this machine: it is the owner's (sessions, shares, answers)"
+      # A page opened in the owner's browser carries the owner's cookies
+      # (chi web's on 127.0.0.1 or the LAN address among them) to whatever
+      # it points at; a port listening here could catch them.
+      OPENER = "a participant's turn can't open a URL or a file in the owner's apps: a browser sends that page the " \
+               "owner's cookies"
+      LISTENER = "a participant's turn can't listen on a port: what it serves on this machine could catch the " \
+                 "owner's browser cookies"
       VERB = "a participant's turn runs only a program named plainly: no $, $(…) or glob in a command's name"
       UNREADABLE = "a participant's turn runs only commands chi can read: split this command, or write the file " \
                    "with the write tool"