samagotchi 0.158.0 → 0.160.0

data/lib/samagotchi/session.rb

@@ -166,6 +166,11 @@ module Samagotchi
       # deleted folder no longer leads to its repository. nil outside a repo,
       # and in files written before the field existed (see #project_root).
       SessionField.plain("project_root", nil),
+      # The project's id (ProjectId: a marked project's `id:`), saved beside
+      # project_root at creation, else nil: its memories and project context
+      # sources are keyed by it (MemoryPaths.key_for), so a session resumed
+      # after its folder moved finds them under the id, not its dead path.
+      SessionField.plain("project_id", nil, optional: true),
       # Memories the session was started with (--memory) and memories hidden
       # from it (--mute): the worker rebuilds the same prompt on a respawn.
       # Names as given; the engine normalizes them.
@@ -271,6 +276,14 @@ module Samagotchi
       # chi web's create) can name it (`--wait --turn T ID`). nil for a
       # session created idle, and for one saved before the field existed.
       SessionField.plain("first_turn_id", nil, optional: true),
+      # Who sent that prompt when no person did (a ClientId: a delegating
+      # parent's delegate:<parent8>, a schedule's chain link
+      # system:schedule:<id>): the first turn's origin, so the command
+      # intake treats it as theirs (CommandIntake) and last_turn names
+      # them. nil for a person's prompt (chi send --new, the web, a TUI, a
+      # continue) and an idle session. Set once, by spawn_session; a
+      # continue and a fork don't carry it.
+      SessionField.plain("first_turn_client_id", nil, optional: true),
       # A Verify fresh child's requester, rules and claim (VerifyFreshOrigin),
       # nil for any other session. Set once, at spawn (VerifyFresh.start).
       # Autoloaded on the first one (the bundle test kit's load budget).
@@ -290,7 +303,7 @@ module Samagotchi
     attr_accessor :id, :metadata_version, :mode, :model_name, :model_typed, :working_directory, :messages,
                   :created_at, :updated_at, :status, :last_prompt, :first_preview, :title, :test_run,
                   :used_memory_names, :preloaded_memory_names, :muted_memory_names, :parent_id, :scratch,
-                  :continues, :first_turn_id
+                  :continues, :first_turn_id, :first_turn_client_id, :project_id
     attr_writer :project_root, :delegate
     attr_reader :appended_prompt_files, :written_by
 
@@ -572,6 +585,7 @@ module Samagotchi
                          review: nil, now: Time.now)
       own = setup.to_h
       own = own.merge(toolkit_origin: own[:toolkit_origin] || "chosen")
+      project = ProjectScope.project_for(working_directory)
       Toolkit.check_new!(own[:toolkit] || Toolkit.configured(delegate: delegate))
       now = now.iso8601(3)
       resolved_test = if test_run.nil?
@@ -591,7 +605,8 @@ module Samagotchi
         status: STATUS_IDLE,
         first_preview: "",
         test_run: resolved_test,
-        project_root: ProjectScope.root_for(working_directory),
+        project_root: project&.root,
+        project_id: project&.id,
         preloaded_memory_names: preloaded_memory_names,
         muted_memory_names: muted_memory_names,
         parent_id: parent_id,

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 project].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
 
@@ -341,7 +353,8 @@ module Samagotchi
       def context_candidates(target)
         return [] if target.project?
 
-        ContextCandidates.with_status(target.session_id, project_root: target.project_root, state_dir: @state_dir)
+        ContextCandidates.with_status(target.session_id, project_root: target.project_root, project_id: target.project_id,
+                                                         state_dir: @state_dir)
                          .map { |candidate, status| ContextCandidate.new(candidate: candidate, status: status) }
       end
 
@@ -359,7 +372,9 @@ module Samagotchi
         ContextSources.check_name!(name)
         return :removed if context_location(target).remove(name)
 
-        project = !target.project? && ContextSources.project_location_for(target.project_root, state_dir: @state_dir)
+        project = !target.project? && ContextSources.project_location_for(target.project_root,
+                                                                          project_id: target.project_id,
+                                                                          state_dir: @state_dir)
         project&.source(name) ? :project : :missing
       end
 
@@ -382,7 +397,7 @@ module Samagotchi
       # live in.
       def context_location(target)
         if target.project?
-          ContextSources.project_location_for(target.project_root, state_dir: @state_dir)
+          ContextSources.project_location_for(target.project_root, project_id: target.project_id, state_dir: @state_dir)
         else
           ContextSources.session_location(target.session_id, state_dir: @state_dir)
         end
@@ -513,9 +528,17 @@ 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)
+        ContextSources.attached(target.session_id, project_root: target.project_root, project_id: target.project_id,
+                                                   state_dir: @state_dir, shadowed: shadowed)
       end
 
       # The block's post to the session's live worker, again on a 408 (the

data/lib/samagotchi/session_access/remote.rb

@@ -809,7 +809,8 @@ module Samagotchi
         owner = json["owner"] && OwnerLock::Owner.new(pid: nil, kind: json["owner"].to_s, started_at: nil)
         SessionView.new(id: json["id"], status: json["status"], title: json["title"],
                         display_title: json["display_title"] || json["title"] || json["first_preview"].to_s,
-                        project_root: json["project_root"], working_directory: json["working_directory"],
+                        project_root: json["project_root"], project_id: json["project_id"],
+                        working_directory: json["working_directory"],
                         model_name: json["model_name"], model_typed: json["model_typed"],
                         parent_answers: json["parent_answers"], owner: owner,
                         pending_question: PendingQuestion.from_file(pending))

data/lib/samagotchi/session_access.rb

@@ -166,7 +166,10 @@ module Samagotchi
     # @!attribute owner [OwnerLock::Owner, nil] its worker or one-turn chi run
     # @!attribute pending_question [PendingQuestion, nil] the file's
     SessionView = Data.define(:id, :status, :title, :display_title, :project_root, :working_directory, :model_name,
-                              :model_typed, :parent_answers, :owner, :pending_question)
+                              :model_typed, :parent_answers, :owner, :pending_question, :project_id) do
+      def initialize(id:, status:, title:, display_title:, project_root:, working_directory:, model_name:,
+                     model_typed:, parent_answers:, owner:, pending_question:, project_id: nil) = super
+    end
 
     # What chi send --new created (Remote; Local gives the Session): its
     # id, a model warning, the session it continues, the delegates it took

data/lib/samagotchi/session_commands.rb

@@ -473,7 +473,8 @@ module Samagotchi
 
       peers = Tools::Peers.new(session_id: session.id, cwd: session.working_directory, state_dir: @engine.peer_state_dir)
       listing = Tools::ContextRead.call("", peers: peers)
-      candidates = ContextCandidates.listing(session.id, project_root: session.project_root, state_dir: @engine.peer_state_dir)
+      candidates = ContextCandidates.listing(session.id, project_root: session.project_root, project_id: session.project_id,
+                                                         state_dir: @engine.peer_state_dir)
       candidates ? "#{listing}\n\n#{candidates}" : listing
     end
 
@@ -618,9 +619,12 @@ module Samagotchi
 
     def approval_line(entry)
       what = entry["key"] ? entry["key"].tr("\n", " ") : "any call rule #{entry["rule"]} asks about"
-      where = if entry["scope"] == "session" then "session #{entry["session_id"].to_s[0, 8]}"
+      where = if entry["scope"] == "session"
+                place = entry["repo_root"] ? " in #{entry["repo_root"]}" : ""
+                "session #{entry["session_id"].to_s[0, 8]}#{place}#{" with its env:" if entry["env"]}"
               elsif entry["repo"] then "in repo #{entry["repo"]}"
-              else "in #{entry["repo_root"]}"
+              else
+                "in #{entry["repo_root"]}"
               end
       rule = entry["rule"] ? " (rule #{entry["rule"]}, #{entry["source"]})" : ""
       "#{entry["scope"]}: #{what} — #{where}#{rule}, #{entry["created_at"]}"

data/lib/samagotchi/session_continue.rb

@@ -91,6 +91,9 @@ module Samagotchi
     # @param prompt [String, nil] its first message (nil: it starts idle)
     # @param preview [String, nil] what the lists show before the first turn;
     #   by default the prompt, else the previous link's preview
+    # @param client_id [String, nil] who sends +prompt+ when no person does
+    #   (a schedule's chain firing: ClientId.schedule), the first turn's
+    #   origin (spawn_session's client_id:)
     # @return [Session] the new link (#model_warning as spawn_session's,
     #   #moved_children: the delegates it took over, #moved_context: the
     #   attached context it took (ContextMove), #opener:
@@ -99,7 +102,8 @@ module Samagotchi
     # @raise [Refused] continued already, delegates open that can't
     #   move, or its folder is gone
     # @raise [ArchiveRefused, OwnedByTUI] as archive_session
-    def self.run(id_or_ref, prompt: nil, preview: nil, model: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
+    def self.run(id_or_ref, prompt: nil, preview: nil, model: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5,
+                 client_id: nil)
       sd = state_dir || Session.default_state_dir
       TRIES.times do |try|
         id = SessionChain.resolve(id_or_ref, state_dir: sd)
@@ -108,7 +112,7 @@ module Samagotchi
           next :moved if follow && SessionChain.next_of(id, state_dir: sd)
 
           run_locked(id, prompt: prompt, preview: preview, model: model, state_dir: sd, recap_wait: recap_wait,
-                         archive_wait: archive_wait)
+                         archive_wait: archive_wait, client_id: client_id)
         end
         return result unless result == :moved
       end
@@ -123,7 +127,7 @@ module Samagotchi
       end
     end
 
-    private_class_method def self.run_locked(id, prompt:, preview:, model:, state_dir:, recap_wait:, archive_wait:)
+    private_class_method def self.run_locked(id, prompt:, preview:, model:, state_dir:, recap_wait:, archive_wait:, client_id:)
       previous = Session.load(id, state_dir: state_dir)
       checked = check!(previous, state_dir, model: model)
       plan = checked.plan
@@ -140,7 +144,7 @@ module Samagotchi
       archived = archive.archived - already
       begin
         spawn_continuation(previous, prompt: prompt, preview: preview, choice: checked.choice, state_dir: state_dir,
-                                     move: plan.move)
+                                     move: plan.move, client_id: client_id)
       rescue StandardError
         # Nothing started: the delegates go back, what this archived goes
         # back to the lists, and a new link saved before its worker failed
@@ -201,7 +205,7 @@ module Samagotchi
 
     # The new link, holding off any worker but its own (StartingMarker.fresh?)
     # while +move+ goes to it.
-    private_class_method def self.spawn_continuation(previous, prompt:, preview:, choice:, state_dir:, move:)
+    private_class_method def self.spawn_continuation(previous, prompt:, preview:, choice:, state_dir:, move:, client_id: nil)
       recap = RecapStore.read(Session.session_dir(previous.id, state_dir: state_dir))
       start = prompt.to_s.strip.empty? ? nil : prompt
       preview = previous.first_preview if preview.to_s.strip.empty? && start.nil?
@@ -218,7 +222,7 @@ module Samagotchi
         prompt: start, preview: preview, title: previous.title, working_directory: previous.working_directory,
         model_name: choice.model, setup: SessionSetup.of(previous), review: previous.review,
         continues: previous.id, note: SessionChain.note_text(previous, recap: recap, state_dir: state_dir),
-        note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn
+        note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn, client_id: client_id
       )
       link.moved_children = move
       link.moved_context = moved_context

data/lib/samagotchi/session_manager/spawn.rb

@@ -54,12 +54,16 @@ module Samagotchi
       # @param scratch [Boolean] a `chi scratch` session (its terminal's
       #   AttachLauncher): its worker runs a scratch Engine and deletes it
       #   once its last client is gone
+      # @param client_id [String, nil] who sent +prompt+ when no person did
+      #   (a ClientId: a delegating parent, a schedule's chain link): its
+      #   first turn's origin (Session#first_turn_client_id)
       # @return [Session] with #seed_images_dropped: refs whose file was gone,
       #   and #model_warning: an id its host's saved list doesn't have
       def spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
                         memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
                         preview: nil, title: nil, delegate: false, setup: SessionSetup.new, continues: nil, note: nil,
-                        note_source: "chi", before_spawn: nil, review: nil, verify_fresh: nil, scratch: false)
+                        note_source: "chi", before_spawn: nil, review: nil, verify_fresh: nil, scratch: false,
+                        client_id: nil)
         sd = state_dir || Session.default_state_dir
         # The resolved ref is stored (a resumed session keeps its model when an
         # alias is retargeted), with the name as typed beside it. A wrong host
@@ -98,7 +102,10 @@ module Samagotchi
         # for it can name it (chi send --new --wait, chi web's create): the
         # worker runs it with that origin, and its reply file and last_turn
         # carry the id.
-        session.first_turn_id = SecureRandom.uuid unless prompt.to_s.strip.empty?
+        unless prompt.to_s.strip.empty?
+          session.first_turn_id = SecureRandom.uuid
+          session.first_turn_client_id = client_id
+        end
         # The worker takes last_prompt and clears it, and messages are saved at
         # the turn's end: until then this is the only preview a list has.
         session.first_preview = Session.preview_of(preview.to_s.strip.empty? ? prompt : preview)
@@ -155,23 +162,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
 
-        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
+      # 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
+
+      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,10 +3,10 @@
 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
-    # format are read by a NEWER chi than the one writing them. Change them
-    # only additively (spec/worker_contract_spec.rb).
+    # (WorkerBoot.run_session_loop(id, state_dir:)), 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"
     # "1" in a worker spawn_options started: it traps signals (WorkerSignals).
     # WorkerBoot.run_session_loop deletes it from ENV as it reads it.
@@ -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), which the boot command loads directly.
+    # 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,18 +94,6 @@ 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
-      # 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).
-      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, **)
-      end
-
       # The worker's command line. Run from an installed gem, the worker
       # activates the newest installed samagotchi (`>= 0.a`, prereleases
       # count), whoever spawns it: an old chi web, chi send or --attach then
@@ -118,8 +106,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 +134,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/state_format.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A versioned JSON state-file schema. Missing members must be required or
+  # declare the format version and default that introduced them.
+  class StateFormat
+    REQUIRED = Object.new.freeze
+
+    Member = Data.define(:name, :introduced_in, :default, :persisted) do
+      def required? = introduced_in.nil?
+      def defaulted? = !required?
+      def persisted? = persisted
+    end
+
+    Record = Data.define(:attributes, :extra, :raw, :missing) do
+      def readable? = missing.empty?
+
+      def to_h
+        return raw unless readable?
+
+        extra.transform_keys(&:to_s).merge(attributes.transform_keys(&:to_s))
+      end
+    end
+
+    Document = Data.define(:version, :extra, :entries)
+
+    class InvalidDocument < StandardError; end
+
+    def self.required(name)
+      Member.new(name: name.to_sym, introduced_in: nil, default: REQUIRED, persisted: true)
+    end
+
+    def self.added(name, in_version:, default:)
+      Member.new(name: name.to_sym, introduced_in: in_version, default: default, persisted: true)
+    end
+
+    def self.extra(name, in_version:)
+      Member.new(name: name.to_sym, introduced_in: in_version, default: ->(_attributes) { {} }, persisted: false)
+    end
+
+    attr_reader :members
+
+    def initialize(version:, members:)
+      @version = version
+      @members = members.freeze
+      @extra_member = members.find { |member| !member.persisted? }
+      raise ArgumentError, "a state format can declare only one extra member" if members.count { |member| !member.persisted? } > 1
+      raise ArgumentError, "duplicate state format members" unless members.map(&:name).uniq == members.map(&:name)
+
+      members.each do |member|
+        required = member.required? && member.default.equal?(REQUIRED)
+        defaulted = member.defaulted? && member.introduced_in.is_a?(Integer) &&
+                    member.introduced_in.positive? && member.introduced_in <= version &&
+                    !member.default.equal?(REQUIRED)
+        next if required || defaulted
+
+        raise ArgumentError, "#{member.name} must be required or have an introduction version and default"
+      end
+    end
+
+    def read(data, collection:)
+      raise InvalidDocument, "the state file must contain a JSON object" unless data.is_a?(Hash)
+
+      collection = collection.to_s
+      entries = Array(data[collection]).map { |raw| read_record(raw) }
+      known = %w[version updated_at] + [collection]
+      stored_version = data["version"]
+      stored_version = 0 unless stored_version.is_a?(Integer) && stored_version >= 0
+
+      Document.new(version: [@version, stored_version].max,
+                   extra: data.reject { |key, _value| known.include?(key.to_s) },
+                   entries: entries)
+    end
+
+    def write(document, collection:, updated_at:)
+      document.extra.transform_keys(&:to_s).merge(
+        "version" => [document.version, @version].max,
+        "updated_at" => updated_at,
+        collection.to_s => document.entries.map(&:to_h)
+      )
+    end
+
+    private
+
+    def read_record(raw)
+      unless raw.is_a?(Hash)
+        missing = members.select(&:required?).map(&:name)
+        return Record.new(attributes: {}, extra: {}, raw: raw, missing: missing)
+      end
+
+      attributes = {}
+      missing = []
+      members.each do |member|
+        next unless member.persisted?
+
+        key = member.name.to_s
+        if raw.key?(key)
+          attributes[member.name] = raw[key]
+        elsif member.required?
+          missing << member.name
+        else
+          attributes[member.name] = default_value(member.default, attributes)
+        end
+      end
+
+      known = members.select(&:persisted?).map { |member| member.name.to_s }
+      extra = raw.reject { |key, _value| known.include?(key.to_s) }
+      extra = default_value(@extra_member.default, attributes).merge(extra) if @extra_member
+      Record.new(attributes: attributes, extra: extra, raw: raw, missing: missing)
+    end
+
+    def default_value(default, attributes)
+      value = default.respond_to?(:call) ? default.call(attributes) : default
+      value = value.dup if value.is_a?(Hash) || value.is_a?(Array)
+      value
+    end
+  end
+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/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.",

data/lib/samagotchi/tools/builtin_calls.rb

@@ -47,6 +47,8 @@ module Samagotchi
         "web_fetch" => { content: "url", fallback: :prefix_or_raw },
         "register_reminder" => { content: "name", fallback: :prefix_or_raw },
         "cancel_reminder" => { content: "name", fallback: :prefix_or_raw },
+        "schedule_task" => { content: "prompt", fallback: :prefix_or_raw },
+        "cancel_schedule" => { content: "name", fallback: :prefix_or_raw },
         "list_sessions" => { fallback: :prefix, fallback_key: "cwd" },
         "send_note" => { content: "text" },
         "context_read" => { content: "name", fallback: :prefix_or_raw },

data/lib/samagotchi/tools/builtins.rb

@@ -18,6 +18,9 @@ require_relative "web_fetch"
 require_relative "register_reminder"
 require_relative "cancel_reminder"
 require_relative "list_reminders"
+require_relative "schedule_task"
+require_relative "list_schedules"
+require_relative "cancel_schedule"
 require_relative "list_sessions"
 require_relative "send_note"
 require_relative "context_read"
@@ -54,6 +57,9 @@ module Samagotchi
         RegisterReminder,
         CancelReminder,
         ListReminders,
+        ScheduleTask,
+        ListSchedules,
+        CancelSchedule,
         ListSessions,
         SendNote,
         ContextRead,
@@ -103,6 +109,17 @@ module Samagotchi
         end,
         CancelReminder::NAME => ->(call, kctx) { CancelReminder.call(call[:content], reminder_store: kctx.reminder_store) },
         ListReminders::NAME => ->(call, kctx) { ListReminders.call(call[:content], reminder_store: kctx.reminder_store) },
+        ScheduleTask::NAME => lambda do |call, kctx|
+          ScheduleTask.call(call[:content], title: call[:title], prompt: call[:prompt], every: call[:every],
+                            weekday: call[:weekday], time: call[:time], date: call[:date], mode: call[:mode],
+                            keep_links: call[:keep_links], peers: kctx.peers)
+        end,
+        ListSchedules::NAME => lambda do |call, kctx|
+          ListSchedules.call(call[:content], include_disabled: call[:include_disabled], all: call[:all], peers: kctx.peers)
+        end,
+        CancelSchedule::NAME => lambda do |call, kctx|
+          CancelSchedule.call(call[:content], all: call[:all], peers: kctx.peers)
+        end,
         ListSessions::NAME => ->(call, kctx) { ListSessions.call(call[:content], peers: kctx.peers, cwd: call[:cwd]) },
         SendNote::NAME => ->(call, kctx) { SendNote.call(call[:content], session: call[:session], peers: kctx.peers) },
         ContextRead::NAME => lambda do |call, kctx|