samagotchi 0.157.0 → 0.159.0

data/lib/samagotchi/session.rb

@@ -81,6 +81,9 @@ module Samagotchi
     LIST = ->(value) { Array(value) }
     ID = ->(value) { value&.to_s }
     MESSAGES = ->(messages) { SessionField.scrub_utf8(messages.map { |msg| SessionField.stringify_keys(msg) }) }
+    # A text the user typed or pasted (a prompt, a title): the file gets it
+    # as valid UTF-8 (nil stays nil), the session keeps what it was given.
+    SCRUBBED = ->(value) { SessionField.scrub_utf8(value) }
     VERDICTS = lambda do |records|
       records&.map do |record|
         SessionField.scrub_utf8(record.to_h do |key, entry|
@@ -92,6 +95,10 @@ module Samagotchi
       origin = value.to_s
       TOOLKIT_ORIGINS.include?(origin) ? origin : "chosen"
     end
+    TOOLKIT_ORIGIN_UNREAD = ->(value) { value if value.is_a?(String) && !TOOLKIT_ORIGINS.include?(value) }
+    # The kept value while there is one: the written one is the cast
+    # (never nil), so it can't come first as a level's does.
+    KEPT_FIRST = ->(written, kept) { kept || written }
     PARENT_ANSWERS = lambda do |value|
       case (level = Guardrails::ParentPolicy.parse_level(value))
       when :unset then nil
@@ -99,7 +106,8 @@ module Samagotchi
       else level
       end
     end
-    private_constant :BOOLEAN, :NAMES, :LIST, :ID, :MESSAGES, :VERDICTS, :TOOLKIT_ORIGIN, :PARENT_ANSWERS
+    private_constant :BOOLEAN, :NAMES, :LIST, :ID, :MESSAGES, :SCRUBBED, :VERDICTS, :TOOLKIT_ORIGIN, :TOOLKIT_ORIGIN_UNREAD, :KEPT_FIRST,
+                     :PARENT_ANSWERS
 
     # The fields of <id>.json, in the order #save writes them: key => its
     # SessionField (the value for a file without it, REQUIRED for the ones
@@ -141,12 +149,12 @@ module Samagotchi
       SessionField.plain("created_at", REQUIRED),
       SessionField.plain("updated_at", REQUIRED),
       SessionField.plain("status", STATUS_IDLE),
-      SessionField.plain("last_prompt", ""),
-      SessionField.plain("first_preview", ""),
+      SessionField.plain("last_prompt", "", write: SCRUBBED),
+      SessionField.plain("first_preview", "", write: SCRUBBED),
       # The name the user gave the session (/title, TitleCommand), else nil:
       # every list, card and tab shows it in place of #first_preview (see
       # #display_title). A continue's new link inherits it.
-      SessionField.plain("title", nil),
+      SessionField.plain("title", nil, write: SCRUBBED),
       SessionField.plain("test_run", false, cast: BOOLEAN, write: BOOLEAN),
       # The question this session waits on (PendingQuestion), saved as
       # session.json's "pending_question"; nil with none. A Hash (a saved
@@ -225,7 +233,11 @@ module Samagotchi
       # Why this session is on its toolkit (TOOLKIT_ORIGINS; anything else
       # reads as chosen). Files from before the field read as chosen, so an
       # old default session is never newly suggested. Cast on every set too.
-      SessionField.plain("toolkit_origin", "chosen", cast: TOOLKIT_ORIGIN),
+      # An unknown String (a newer chi's origin) is written back as it was
+      # (the Unread rule), until the session sets its own: the kept value
+      # wins over the cast chosen.
+      SessionField.plain("toolkit_origin", "chosen", cast: TOOLKIT_ORIGIN, unread: TOOLKIT_ORIGIN_UNREAD,
+                                                     keep: KEPT_FIRST),
       # The two parts of #settings (Session.new's settings:, .from_h composes
       # them): its bundles part, then its core part.
       SessionField.file_only("bundle_settings", {}, from: :settings, write: ->(settings) { settings.bundles }),
@@ -272,16 +284,6 @@ module Samagotchi
     # Session.new's keywords: every FIELDS row's attr.
     ATTRS = FIELDS.values.filter_map(&:attr).freeze
 
-    # @raise [ArgumentError] a keyword Session.new doesn't take, or a
-    #   required one missing (Ruby's own wording)
-    def self.check_attrs!(attrs)
-      unknown = attrs.keys - ATTRS
-      raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
-
-      missing = FIELDS.values.select(&:fresh_required?).map(&:attr) - attrs.keys
-      raise ArgumentError, "missing keyword#{"s" if missing.size > 1}: #{missing.map(&:inspect).join(", ")}" unless missing.empty?
-    end
-
     # The plain fields' readers and writers (each one's meaning is at its
     # FIELDS row): a writer takes the value as given (Session.new and
     # .from_h cast it), except the ones defined below.
@@ -362,6 +364,18 @@ module Samagotchi
       @toolkit_origin = load_field("toolkit_origin", value)
     end
 
+    # The user chose the toolkit (/toolkit, the toolkit binding's use): the
+    # origin is chosen. Whether that changes what the file holds, so the
+    # caller saves only then: a kept unknown origin (the Unread rule) reads
+    # as chosen but is written as it was, so it counts as a change.
+    # @return [Boolean]
+    def choose_toolkit_origin!
+      field = FIELDS.fetch("toolkit_origin")
+      was = field.dump(@toolkit_origin, @unread["toolkit_origin"])
+      self.toolkit_origin = "chosen"
+      was != field.dump(@toolkit_origin, @unread["toolkit_origin"])
+    end
+
     def parent_answers=(value)
       @parent_answers = load_field("parent_answers", value)
     end
@@ -446,7 +460,7 @@ module Samagotchi
     # (cast by its row, as the writers cast); +settings+ is the
     # settings pair's one value, +extra_fields+ the file's unknown keys.
     def initialize(extra_fields: {}, settings: nil, **attrs)
-      self.class.check_attrs!(attrs)
+      check_attrs!(attrs)
       # What the level fields couldn't read, by key (SessionField.level).
       @unread = {}
       FIELDS.each_value do |field|
@@ -793,10 +807,21 @@ module Samagotchi
     def load_field(key, value)
       field = FIELDS.fetch(key)
       @unread[key] = field.unread.call(value) if field.unread
-      field.load(value)
+      field.cast_value(value)
     end
     private :load_field
 
+    # @raise [ArgumentError] a keyword Session.new doesn't take, or a
+    #   required one missing (Ruby's own wording)
+    def check_attrs!(attrs)
+      unknown = attrs.keys - ATTRS
+      raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+
+      missing = FIELDS.values.select(&:fresh_required?).map(&:attr) - attrs.keys
+      raise ArgumentError, "missing keyword#{"s" if missing.size > 1}: #{missing.map(&:inspect).join(", ")}" unless missing.empty?
+    end
+    private :check_attrs!
+
     # The running turn's checkpoint, while the turn runs (#turn_checkpoint).
     def checkpointed
       checkpoint = @turn_checkpoint
@@ -884,8 +909,9 @@ module Samagotchi
     # A prompt as a one-line preview: whitespace collapsed, cut at 80 chars.
     # A quoted or annotated message previews by what was typed under the
     # quote; a quote alone by its words, without the "> " markers or label.
+    # Bytes that aren't UTF-8 preview as ?, as the file saves them.
     def self.preview_of(text)
-      norm = preview_words(text.to_s).gsub(/\s+/, " ").strip
+      norm = preview_words(SessionField.scrub_utf8(text.to_s)).gsub(/\s+/, " ").strip
       norm.length > 80 ? "#{norm[0, 80]}…" : norm
     end
 

data/lib/samagotchi/session_access/contract.rb

@@ -26,7 +26,7 @@ module Samagotchi
       # bin/chi subcommands that act on this machine: never sessions. chi
       # remote (this machine's list of remotes) runs here under a remote too
       # (Dispatch); the others are refused there.
-      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit judgments remote home].freeze
+      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit judgments remote home project schedule].freeze
 
       # "command", "command sub" or either with a flag (its long name) →
       # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists

data/lib/samagotchi/session_access/local.rb

@@ -11,6 +11,7 @@ require_relative "../parent_report"
 require_relative "../note_delivery"
 require_relative "../image_store"
 require_relative "../context_candidates"
+require_relative "../worker_inbound"
 require_relative "../context_sources"
 require_relative "../archive_store"
 require_relative "../session_chain"
@@ -24,6 +25,7 @@ require_relative "../participants"
 require_relative "../config"
 require_relative "../live_versions"
 require_relative "../grants"
+require_relative "../log"
 require_relative "../web/info_probe"
 require_relative "../web/public_url"
 require_relative "../web/link_codes"
@@ -314,6 +316,16 @@ module Samagotchi
         before, written = attached.location.locked(name) do
           [attached.location.snapshot(name).revision, attached.location.record_text(name, fetched)]
         end
+        if fetched.wake && before != written.revision && !target.project? && attached.location.session? &&
+           attached.source.scope == "session"
+          begin
+            subscription = attached.location.subscription(name)
+            recent_wake = context_wake_recent?(subscription)
+            SessionManager.wake_for_context(target.session_id, **dir) unless recent_wake || Config.get("context.wake") == false
+          rescue StandardError => e
+            Log.exception(:context, "context_push_wake_failed", e, sid: target.session_id, source: name)
+          end
+        end
         ContextPush.new(status: :pushed, before: before, revision: written.revision)
       end
 
@@ -513,6 +525,14 @@ module Samagotchi
       def state_dir! = @state_dir || Session.default_state_dir
       def session_dir(id) = Session.session_dir(id, state_dir: state_dir!)
 
+      def context_wake_recent?(subscription)
+        return false unless subscription.wakes_at
+
+        Time.now - Time.iso8601(subscription.wakes_at) < WorkerInbound::CONTEXT_WAKE_WINDOW
+      rescue ArgumentError
+        false
+      end
+
       def attached_to(target, shadowed: false)
         ContextSources.attached(target.session_id, project_root: target.project_root, state_dir: @state_dir,
                                                    shadowed: shadowed)

data/lib/samagotchi/session_field.rb

@@ -15,10 +15,11 @@ module Samagotchi
   # block its lambdas call (`type.call`, not `yield`: never while the
   # constructor runs, so Performance/RedundantBlockCall is off for them).
   SessionField = Data.define(:key, :attr, :from, :default, :fresh, :optional, :cast, :write, :unread, :keep) do
-    # A field read as given, or through +cast+.
-    def self.plain(key, default, cast: nil, write: nil, fresh: default, optional: false)
+    # A field read as given, or through +cast+; +unread+ and +keep+ give
+    # it the Unread rule (see .level).
+    def self.plain(key, default, cast: nil, write: nil, fresh: default, optional: false, unread: nil, keep: nil)
       new(key: key, attr: key.to_sym, from: nil, default: default, fresh: fresh, optional: optional, cast: cast,
-          write: write, unread: nil, keep: nil)
+          write: write, unread: unread, keep: keep)
     end
 
     # rubocop:disable Performance/RedundantBlockCall
@@ -98,7 +99,7 @@ module Samagotchi
     def ivar = :"@#{attr || from}"
 
     # +value+ as the attribute holds it.
-    def load(value) = cast ? cast.call(value) : value
+    def cast_value(value) = cast ? cast.call(value) : value
 
     # The attribute's +value+ as the file holds it, with what the session
     # kept of a value it couldn't read (+kept+, .level's).

data/lib/samagotchi/session_manager/spawn.rb

@@ -155,23 +155,37 @@ module Samagotchi
       # @return [Symbol] :woken, or why not (:gone, :stopped, :archived,
       #   :scratch, :owned, :starting)
       def wake_for_report(session_id, state_dir: nil, forward: true)
-        sd = state_dir || Session.default_state_dir
-        return :gone unless Session.exist?(session_id, state_dir: sd)
-        return :owned if session_owner(session_id, state_dir: sd)
-        return :stopped if Session.stopped_marker?(session_id, state_dir: sd)
+        wake_existing_session(session_id, state_dir: state_dir || Session.default_state_dir, forward: forward,
+                              event: :delegate_woke_parent)
+      end
+
+      # A pushed context source asked for a wake: start an idle-exited
+      # session, but never clear a stop or forward an archived link.
+      # @return [Symbol] :woken, or why not (:gone, :stopped, :archived,
+      #   :scratch, :owned, :starting)
+      def wake_for_context(session_id, state_dir: nil)
+        wake_existing_session(session_id, state_dir: state_dir || Session.default_state_dir, forward: false,
+                              event: :context_woke_session)
+      end
 
-        if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: sd))
-          following = forward && SessionChain.next_of(session_id, state_dir: sd)
-          return following ? wake_for_report(following, state_dir: sd, forward: false) : :archived
+      private def wake_existing_session(session_id, state_dir:, forward:, event:)
+        return :gone unless Session.exist?(session_id, state_dir: state_dir)
+        return :owned if session_owner(session_id, state_dir: state_dir)
+        return :stopped if Session.stopped_marker?(session_id, state_dir: state_dir)
+
+        if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: state_dir))
+          following = forward && SessionChain.next_of(session_id, state_dir: state_dir)
+          return following ? wake_existing_session(following, state_dir: state_dir, forward: false, event: event) : :archived
         end
-        return :starting if StartingMarker.fresh?(session_id, state_dir: sd)
+        return :starting if StartingMarker.fresh?(session_id, state_dir: state_dir)
 
-        session = Session.load(session_id, state_dir: sd)
+        session = Session.load(session_id, state_dir: state_dir)
         return :stopped if session.status == Session::STATUS_STOPPED
         return :scratch if session.scratch
 
-        resume_session(session_id, state_dir: sd)
-        Log.info(:worker, "delegate_woke_parent", parent: session_id[0, 8])
+        resume_session(session_id, state_dir: state_dir)
+        details = event == :delegate_woke_parent ? { parent: session_id[0, 8] } : { sid: session_id[0, 8] }
+        Log.info(:worker, event, **details)
         :woken
       rescue OwnedByTUI
         :owned

data/lib/samagotchi/session_manager/worker_command.rb

@@ -3,8 +3,8 @@
 module Samagotchi
   class SessionManager
     # CROSS-VERSION CONTRACT: this boot string, the entry it names
-    # (run_session_loop(id, state_dir:), the forwarder below), the env keys
-    # spawn_options sets and the input/ file
+    # (WorkerBoot.run_session_loop(id, state_dir:)), the legacy forwarder
+    # below, the env keys spawn_options sets and the input/ file
     # format are read by a NEWER chi than the one writing them. Change them
     # only additively (spec/worker_contract_spec.rb).
     BOOT_FALLBACK_ENV = "SAMAGOTCHI_BOOT_FALLBACK"
@@ -28,9 +28,9 @@ module Samagotchi
 
     # WorkerCommand: the worker's command line and env (CROSS-VERSION
     # CONTRACT: spec/worker_contract_spec.rb); the worker process itself is
-    # WorkerBoot (worker_boot.rb), which only the forwarder (run_session_loop)
-    # loads, as a worker boots. Calls no other part. Meant to be loaded
-    # through samagotchi/session_manager.
+    # WorkerBoot (worker_boot.rb). The boot command loads it directly; the
+    # forwarder (run_session_loop) remains for older boot strings. Calls no
+    # other part. Meant to be loaded through samagotchi/session_manager.
     module WorkerCommandPart
       # Build the opts hash passed to Process.spawn for a forked worker. The
       # child inherits this process's ENV and reads config.yml itself (as it
@@ -94,13 +94,13 @@ module Samagotchi
         opts
       end
 
-      # The worker's entry, the one every boot string names (CROSS-VERSION
-      # CONTRACT: spec/worker_contract_spec.rb): it only forwards to
+      # The worker's legacy entry for boot strings written by older chi
+      # (CROSS-VERSION CONTRACT: spec/worker_contract_spec.rb): it forwards to
       # WorkerBoot.run_session_loop, which runs the worker process. Looked up
       # by name on purpose: a constant reference here would put SessionManager
       # back into one cycle with Worker, Engine and Bridge (the class map).
-      # REMOVE one release after the boot string switches (see
-      # ~/.claude/plans/arch-worker-boot.md).
+      # REMOVE in the next release: boot strings name WorkerBoot since this
+      # one (see ~/.claude/plans/arch-worker-boot.md).
       def run_session_loop(session_id, state_dir: nil, **)
         require_relative "../worker_boot"
         Samagotchi.const_get(:WorkerBoot).run_session_loop(session_id, state_dir: state_dir, **)
@@ -118,8 +118,8 @@ module Samagotchi
       # there) keeps the plain -I lib: a worktree's bin/chi spawns its own code.
       def worker_command(session_id, state_dir:, gem_spec: InstalledGem.spec,
                          home: ChiHome.current(gem_spec: gem_spec))
-        boot = "require 'samagotchi/session_manager'; " \
-               "Samagotchi::SessionManager.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})"
+        boot = "require 'samagotchi/worker_boot'; " \
+               "Samagotchi::WorkerBoot.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})"
         return [RbConfig.ruby, "-I", File.expand_path("../..", __dir__), "-e", boot] unless gem_spec
         return home_worker_command(session_id, state_dir: state_dir, gem_spec: gem_spec, home: home) if home
 
@@ -146,9 +146,9 @@ module Samagotchi
                    else
                      "gem 'samagotchi', '>= 0.a'"
                    end
-        home.boot_argv(run: "begin; #{activate}; require 'samagotchi/session_manager'; " \
+        home.boot_argv(run: "begin; #{activate}; require 'samagotchi/worker_boot'; " \
                              "#{HOME_BOOT_FAILED.sub("SID", session_id)}; end; " \
-                             "Samagotchi::SessionManager.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})")
+                             "Samagotchi::WorkerBoot.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})")
       end
     end
 

data/lib/samagotchi/steer.rb

@@ -364,6 +364,16 @@ module Samagotchi
       turn_prompt?(message) && !shell_line?(message)
     end
 
+    # An opening's stamp: its turn_id (a prompt's, a wake note's), else its
+    # own opening_id (/continue no's reason line); nil for neither (a line
+    # an older chi wrote). Where a card (Bridge::CardPlaces) and the recap
+    # (RecapPlace) sit.
+    # @return [String, nil]
+    def opening_stamp(message)
+      id = message[:turn_id] || message["turn_id"] || message[:opening_id] || message["opening_id"]
+      id.is_a?(String) && !id.empty? ? id : nil
+    end
+
     # Call a loop's drain: +at_answer+ goes only to a drain that takes it
     # (the Engine's); a caller's own drain (a queue's #drain) is called bare.
     # A failing drain drains nothing (the loop keeps going).

data/lib/samagotchi/system_prompt.rb

@@ -291,7 +291,7 @@ module Samagotchi
           6. Use write for full-file rewrites or creating new files.
 
         Memory convention:
-          Project scope: one folder per git repository, shared by its worktrees and subdirectories (its path is on the "Project memories folder" line below)
+          Project scope: one folder per project (a git repository, shared by its worktrees and subdirectories, or a folder marked by `chi project init` and its subfolders; its path is on the "Project memories folder" line below)
           System scope:  ~/.config/samagotchi/memories/ (cross-project)
           memory_read accepts optional scope (project|system).
           memory_write requires explicit scope and entry name.
@@ -623,10 +623,20 @@ module Samagotchi
       File.expand_path(path)
     end
 
+    # The project_location line over its top, for a checkout (git) or a
+    # marked project: [below the top, at the top].
+    TOP_LINES = {
+      git: ["Top of this checkout (where the project's commands run from; stay inside it):",
+            "This checkout (the project's files; its commands run here):"],
+      marker: ["Top of this project (where its commands run from; stay inside it):",
+               "This project (its files; its commands run here):"]
+    }.freeze
+
     # Where the session runs and which project memory folder it uses. Only
-    # this checkout is named: its top (at its root too, so a model doesn't
-    # take the memories folder for the project and cd there, Qwen
-    # 2026-10-06), and in a linked worktree a line that work stays in it. The repository's main
+    # this checkout (or marked project, MemoryPaths.lookup) is named: its
+    # top (at its root too, so a model doesn't take the memories folder for
+    # the project and cd there, Qwen 2026-10-06), and in a linked worktree
+    # a line that work stays in it. The repository's main
     # checkout (MemoryPaths.project_root, which scopes memories and session
     # lists) is never shown: a model told its path went to work there
     # (a worktree child committed onto main, 2026-10-03 and 2026-10-06).
@@ -635,16 +645,15 @@ module Samagotchi
     def project_location
       Degrade.call(:prompt, "location_failed") do
         cwd = Dir.pwd
-        top = MemoryPaths.work_tree_root(cwd)
+        found = MemoryPaths.lookup(cwd)
+        top = found.top
         lines = ["Current working directory:", cwd]
-        if top && top != cwd
-          lines << "Top of this checkout (where the project's commands run from; stay inside it):"
-          lines << top
-        elsif top
-          lines << "This checkout (the project's files; its commands run here):"
+        if top
+          below, at = TOP_LINES.fetch(found.kind)
+          lines << (top == cwd ? at : below)
           lines << top
         end
-        if top && MemoryPaths.project_root(cwd) != top
+        if found.git? && found.root != top
           lines << "This checkout is a linked git worktree: read, edit, run and commit only in it, never in the " \
                    "repository's other checkouts."
         end

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -242,6 +242,8 @@ module Samagotchi
         when "task"
           task = id.delete_prefix(ClientId::TASK_PREFIX)
           return "task #{Tools::TaskRecord.short_id(task)} finished" unless task.empty?
+        when "schedule"
+          return "schedule"
         end
 
         prefix = id[/\A[^:]*:/]

data/lib/samagotchi/terminal_ui/join_replay.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../bridge/turn_accumulator"
+require_relative "../bridge/turn_drawings"
 require_relative "../context_note"
 require_relative "../image_store"
 require_relative "../log"
@@ -163,13 +164,17 @@ module Samagotchi
 
       # The snapshot's drawing as [turn, end event] when it is +prompt+'s
       # turn (a Continue's or a reminder's drawing isn't the prompt's: the
-      # rows are rebuilt), else nil.
+      # rows are rebuilt), else nil; nil too for one whose parts aren't a
+      # list of rows.
       def drawn_turn(drawing, prompt)
         return nil unless drawing.is_a?(Hash) && drawing[:drawing].is_a?(Hash) && drawing[:end].is_a?(Hash)
 
         turn = Bridge::TurnAccumulator.from_wire(drawing[:drawing])
         id = prompt[:turn_id] || prompt["turn_id"]
         return nil unless id && turn[:turn_id].to_s == id.to_s
+        # An older worker sends a line its parse didn't check (the unfold
+        # would raise after the prompt line is drawn).
+        return nil unless Bridge::TurnDrawings.rows?(turn[:parts])
 
         [turn, EventRenderer.symbolize(Bridge::TurnAccumulator.from_wire(drawing[:end]))]
       end

data/lib/samagotchi/testing/bundle.rb

@@ -25,7 +25,7 @@ require_relative "recording_api"
 
 module Samagotchi
   module Testing
-    # A hook (a plugin's chi.on block or a hook file) raised while the kit
+    # A hook (a plugin's chi.on block) raised while the kit
     # fired it: chi would log it and go on, a test fails with it.
     class HookFailed < StandardError
       # @return [Hooks::Failure]
@@ -53,8 +53,7 @@ module Samagotchi
 
     # One bundle loaded for a test through chi's own seams: its plugin
     # through Plugin::Loader.register_file (Plugin::Api, a real
-    # Plugin::Context) and its hook files through
-    # Hooks::BundleLoader.load_hook_file, into real registries (commands
+    # Plugin::Context), into real registries (commands
     # and tools with chi's built-ins in them, so a name clash fails as in
     # chi). Only the edges are recorded: the Host and hook Runtime
     # (Recorder), ctx.sessions (Testing::Sessions), chi.init tasks and
@@ -130,8 +129,6 @@ module Samagotchi
       # @return [Module, nil] the module the plugin was evaluated in
       #   (bundle.namespace::ThinkingWatch)
       attr_reader :namespace
-      # @return [Module] the module the hook files were evaluated in
-      attr_reader :hooks_namespace
       # @return [Array<Init>]
       attr_reader :inits
       # @return [Array<StagedTools>]
@@ -152,6 +149,9 @@ module Samagotchi
         @session_moves = 1
         own = session_settings.nil? || session_settings.empty? ? {} : { setup: setup_with(session_settings, host[:setup]) }
         @own_sandbox = sandbox.nil? && Sandbox.current.nil?
+        # With no active sandbox, this one saves ENV at construction and
+        # restores that copy at shutdown; don't lazily build it inside a block
+        # that sets ENV for one example (your own helper, or ClimateControl).
         @sandbox = sandbox || Sandbox.current || Sandbox.enter
         build(host, own)
       rescue Exception # rubocop:disable Lint/RescueException -- leave the sandbox it entered, whatever failed
@@ -184,13 +184,6 @@ module Samagotchi
             @plugin = built
           end
         end
-        @hooks_namespace = Module.new
-        @manifest.hooks.each do |basename, hook|
-          next if hook.events.empty?
-
-          Hooks::BundleLoader.load_hook_file(@name, basename, File.join(@dir, "hooks", basename), hook, hooks,
-                                             settings: @settings, namespace: @hooks_namespace)
-        end
         self
       rescue Exception # rubocop:disable Lint/RescueException -- leave the sandbox it entered, whatever failed
         shutdown

data/lib/samagotchi/testing/install.rb

@@ -15,7 +15,7 @@ module Samagotchi
     # A bundle as chi installs and loads it, unlike Bundle (its source as it
     # is): MemoryBundle::Installer copies it into the sandbox's state (sha256
     # and requires_chi checked), then chi's own loaders load what is
-    # installed (ExtensionLoad: the bundle hooks, then the plugins). What
+    # installed (ExtensionLoad: config hooks, then the plugins). What
     # failed names the bundle's source files, not the installed copies.
     #
     #   result = Samagotchi::Testing::Install.run("path/to/bundle", settings: { "every" => 3 })
@@ -23,8 +23,8 @@ module Samagotchi
     module Install
       # warnings: the Installer's; plugin_failures / hook_failures:
       # [Guardrails::LoadFailures::Failure] of this bundle, each location
-      # in the source dir (hook_failures: the guardrails', a required
-      # plugin's among them); registered: what it registered (#registered).
+      # in the source dir (hook_failures: the guardrails': a required
+      # plugin's load failure, a config hook's); registered: what it registered (#registered).
       Result = Data.define(:name, :warnings, :plugin_failures, :hook_failures, :registered) do
         def failures = plugin_failures + hook_failures
       end
@@ -35,7 +35,7 @@ module Samagotchi
       Registered = Data.define(:commands, :tools, :hooks, :inits, :toolkits, :tool_sources, :peer_sources, :prompt_sections)
       # A command: its mid_turn policy and its selection-bar labels (chi.annotation).
       Command = Data.define(:name, :mid_turn, :labels)
-      # A hook on an event: the bundle, the hook (its file, or the plugin's) and its priority.
+      # A hook on an event: the bundle, the hook (the plugin's label) and its priority.
       Hook = Data.define(:bundle, :hook, :priority)
 
       module_function
@@ -119,7 +119,7 @@ module Samagotchi
       # installed copy to the source dir.
       def own(failures, name, installed, dir)
         failures.list.select { |f| f.what.end_with?("(bundle #{name})") }.map do |failure|
-          # The plugin is installed into plugin/, the hooks into hooks/.
+          # The plugin is installed into plugin/.
           location = failure.location&.sub(%r{\A#{Regexp.escape(installed)}/(?:plugin/)?}, "#{dir}/")
           failure.dup.tap { |copy| copy.location = location }
         end

data/lib/samagotchi/testing/recorder.rb

@@ -9,7 +9,7 @@ require_relative "judgments"
 module Samagotchi
   module Testing
     # A line to the user (ctx.notify, event[:notify]); +hook+ is the
-    # plugin's or hook file's label ("plugin.rb (bundle x)").
+    # plugin's label ("plugin.rb (bundle x)").
     Notice = Data.define(:text, :level, :hook, :fallback_for)
     # Text put into the running turn (ctx.steer, event[:steer]).
     Steer = Data.define(:text, :hook)

data/lib/samagotchi/testing.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # The bundle test kit (docs/plugins.md, "Testing a bundle"): load a bundle's
-# plugin and hook files through chi's own loaders, registries, Context and
+# plugin through chi's own loaders, registries, Context and
 # guardrail Gate, with only the edges recorded (the session's Host, the hook
 # runtime, ctx.sessions, init tasks), in a sandboxed environment.
 #

data/lib/samagotchi/tool_declarations.rb

@@ -303,6 +303,49 @@ module Samagotchi
           properties: {}
         }
       },
+      {
+        name: "schedule_task",
+        description: "Register a durable schedule for this session: a prompt that runs on a clock outside the worker " \
+                     "(chi schedule tick, run by cron, systemd or chi web's hub). Unlike register_reminder it needs no " \
+                     "live worker and never holds one up. Give exactly one of every, weekday+time or date.",
+        parameters: {
+          type: "object",
+          properties: {
+            title: { type: "string", description: "A short name for the schedule" },
+            prompt: { type: "string", description: "What each firing does (non-empty, at most 16 KiB)" },
+            every: { type: "string", description: "Interval: \"30m\", \"2h\", \"1d\" (UTC math: drifts an hour across a DST change)" },
+            weekday: { type: "integer", description: "1=Mon … 7=Sun, used with time" },
+            time: { type: "string", description: "HH:MM in the machine's local zone (with weekday)" },
+            date: { type: "string", description: "One local moment: 2026-11-20T09:00" },
+            mode: { type: "string", description: "chain (default): the next link of this session's chain. same: a queued turn in this session" },
+            keep_links: { type: "integer", description: "Chain links to keep (default 5; 0 keeps all)" }
+          },
+          required: ["prompt"]
+        }
+      },
+      {
+        name: "list_schedules",
+        description: "List the durable schedules of this chain (all: true for every schedule on this machine): id, mode, recurrence, next due and target.",
+        parameters: {
+          type: "object",
+          properties: {
+            include_disabled: { type: "boolean", description: "Include the disabled schedules and the fired one-offs" },
+            all: { type: "boolean", description: "Every schedule on this machine, not just this chain" }
+          }
+        }
+      },
+      {
+        name: "cancel_schedule",
+        description: "Cancel a durable schedule of this chain by its id, a unique prefix of it, or its title (all: true for one from another chain).",
+        parameters: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "The schedule's id or title" },
+            all: { type: "boolean", description: "Allow cancelling a schedule of another session's chain" }
+          },
+          required: ["name"]
+        }
+      },
       {
         name: "list_sessions",
         description: "List the other chi sessions of this project (newest first, up to 20): id, whether a worker runs it, its folder and last prompt; other projects: cwd \"/\". Use it to find the session send_note should go to.",
@@ -375,7 +418,7 @@ module Samagotchi
             },
             cwd: {
               type: "string",
-              description: "The new child's working folder: a worktree or subfolder of this session's repository (create a worktree with execute `git worktree add ../<repo>-<name> -b <branch>` first). Default: this session's folder"
+              description: "The new child's working folder: a worktree or subfolder of this session's project (a repository, or a `chi project init` folder; create a worktree with execute `git worktree add ../<repo>-<name> -b <branch>` first). Default: this session's folder"
             },
             toolkit: {
               type: "string",

data/lib/samagotchi/toolkit_binding.rb

@@ -139,10 +139,7 @@ module Samagotchi
 
       toolkit = Toolkit.new(name: name)
       if session.toolkit == toolkit
-        if session.toolkit_origin != "chosen"
-          session.toolkit_origin = "chosen"
-          session.save(state_dir: @state_dir.call)
-        end
+        session.save(state_dir: @state_dir.call) if session.choose_toolkit_origin!
         return true
       end
 

data/lib/samagotchi/toolkit_command.rb

@@ -47,10 +47,7 @@ module Samagotchi
       # Nothing the prompt carries changes (full +delegate on full): only
       # the origin is saved, so a no-op choice still counts as user-selected.
       if after.prompt_key == before.prompt_key
-        if session.toolkit_origin != "chosen"
-          session.toolkit_origin = "chosen"
-          @save.call(session)
-        end
+        @save.call(session) if session.choose_toolkit_origin!
         return [listing(before) + "\n(no change to what the next turn declares)", false, nil]
       end