samagotchi 0.157.0 → 0.158.0

data/lib/samagotchi/project_command.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "guardrails/path_resolve"
+require_relative "memory_paths"
+require_relative "paths"
+require_relative "project_init"
+
+module Samagotchi
+  # `chi project`: which project this folder is in (MemoryPaths.lookup: a
+  # git repository, a folder marked with `.chi/project.yml`, or none) and
+  # its project memories folder; `chi project init [DIR]` marks a folder in
+  # no git repository as a project. Git wins: a repository is already the
+  # project, so init writes nothing there. Machine-local
+  # (SessionAccess::Contract::MACHINE).
+  class ProjectCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi project [init [DIR]]
+        (none)       this folder's project: how it was found (git, marker or none), its root, its
+                     top and its project memories folder
+        init [DIR]   make DIR (default: this folder; created when missing) a chi project: writes
+                     DIR/#{MemoryPaths::MARKER}, so DIR and every subfolder share one project memories
+                     folder and group their sessions. Not in a git repository (it already is the
+                     project), nor $HOME or a folder above it
+    TEXT
+
+    SUBCOMMANDS = %w[init].freeze
+    FLAGS = {
+      nil => CLI::Flags.new(help: HELP_WORDS, args: false),
+      "init" => CLI::Flags.new(help: HELP_WORDS)
+    }.freeze
+
+    # @param cwd [String] the folder asked about (Dir.pwd)
+    # @param home [String, nil] $HOME (markers at or above it are ignored)
+    # @param sessions [#call, nil] () → this machine's SessionRows (for
+    #   init's restart note; SessionManager.session_rows by default)
+    def initialize(argv, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd, env: ENV, home: MemoryPaths.default_home,
+                   sessions: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @cwd = cwd
+      @env = env
+      @home = home
+      @sessions = sessions || lambda {
+        require_relative "session_manager"
+        SessionManager.session_rows
+      }
+    end
+
+    # @return [Integer] 0, 1 (a refusal), 2 usage
+    def run
+      @sub = SUBCOMMANDS.include?(@argv.first) ? @argv.first : nil
+      parsed = parse_flags(FLAGS.fetch(@sub), @sub ? @argv[1..] : @argv)
+      return parsed if parsed.is_a?(Integer)
+
+      return run_show unless @sub
+      return usage_error("init takes one folder") if parsed.args.size > 1
+
+      run_init(parsed.args.first || @cwd)
+    end
+
+    private
+
+    def command_name = @sub ? "chi project #{@sub}" : "chi project"
+    def usage_on_error = nil
+
+    def lookup(dir) = MemoryPaths.lookup(dir, home: @home)
+
+    def run_show
+      found = lookup(@cwd)
+      row("kind", found.kind.to_s)
+      if found.project?
+        row("root", found.root)
+        row("top", found.top)
+      end
+      row("memories", memories_line(found.root))
+      notes(found).each { |note| row("note", note) }
+      CLI::Exit::OK
+    end
+
+    def row(label, value) = @stdout.puts("#{label.ljust(9)}#{value}")
+
+    def memories_line(root)
+      dir = File.join(MemoryPaths.projects_dir(env: @env), MemoryPaths.key_for_root(root))
+      count = memory_count(dir)
+      "#{Paths.tilde(dir)}#{" (#{count} #{count == 1 ? "memory" : "memories"})" if count.positive?}"
+    end
+
+    def memory_count(dir)
+      return 0 unless File.directory?(dir)
+
+      Dir.children(dir).count { |name| name.end_with?(".md") && name != "index.md" }
+    end
+
+    def notes(found)
+      case found.kind
+      when :git
+        list = []
+        list << "#{Paths.tilde(found.top)} is $HOME, a git repository: every folder under it is in that repository" if home_repo?(found)
+        marker = MemoryPaths.nearest_marker(@cwd, home: @home)
+        list << "#{Paths.tilde(File.join(marker, MemoryPaths::MARKER))} is ignored: the git repository is the project" if marker
+        list
+      when :none then ["no git repository or chi project marker here: chi project init makes this folder a project"]
+      else []
+      end
+    end
+
+    def home_repo?(found)
+      !@home.to_s.empty? && Guardrails::PathResolve.real(found.top) == Guardrails::PathResolve.real(@home)
+    end
+
+    def run_init(dir)
+      dir = File.expand_path(dir, @cwd)
+      outcome = ProjectInit.call(dir, home: @home)
+      case outcome.kind
+      when :git
+        found = MemoryPaths::ProjectLookup.new(kind: :git, root: outcome.root, top: outcome.top)
+        note = home_repo?(found) ? " ($HOME is a git repository: every folder under it is in it)" : ""
+        @stdout.puts("#{outcome.message}#{note}")
+        CLI::Exit::OK
+      when :refused
+        error_line("#{command_name}: #{outcome.message}")
+        CLI::Exit::FAILED
+      when :already_marked
+        @stdout.puts(outcome.message)
+        CLI::Exit::OK
+      when :created
+        report_init(outcome.root, nested_in: outcome.nested_in)
+        CLI::Exit::OK
+      end
+    rescue SystemCallError => e
+      error_line("#{command_name}: couldn't write #{Paths.tilde(File.join(dir, MemoryPaths::MARKER))}: #{e.message}")
+      CLI::Exit::FAILED
+    end
+
+    def report_init(root, nested_in:)
+      nested = nested_in ? ", its own project nested in #{Paths.tilde(nested_in)}" : ""
+      @stdout.puts("#{Paths.tilde(root)} is now a chi project#{nested} (#{Paths.tilde(File.join(root, MemoryPaths::MARKER))})")
+      row("memories", memories_line(root))
+      sessions_note(root)
+    end
+
+    # Sessions in the new project (not one under DIR that a nested
+    # repository or marked folder keeps): a running one keeps its old project in its
+    # prompt (the memories folder line, the AGENTS.md chain) until it
+    # restarts; a running chi web groups the older ones after its restart
+    # (SessionHub looked their project up once).
+    def sessions_note(root)
+      rows = @sessions.call.select { |r| !r.cwd.to_s.empty? && lookup(r.cwd.to_s).root == root }
+      return if rows.empty?
+
+      live = rows.select(&:live)
+      unless live.empty?
+        @stdout.puts("running sessions in it keep the old project in their prompt until restarted " \
+                     "(chi sessions restart ID): #{live.map { |r| r.id[0, 8] }.join(", ")}")
+      end
+      @stdout.puts("#{rows.size} saved session(s) in it join the project in a running chi web after its restart")
+    rescue StandardError => e
+      error_line("#{command_name}: couldn't list this machine's sessions (#{e.message})")
+    end
+  end
+end

data/lib/samagotchi/project_init.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "guardrails/path_resolve"
+require_relative "memory_paths"
+require_relative "paths"
+
+module Samagotchi
+  # The shared decisions for `chi project init` and chi web's project picker.
+  module ProjectInit
+    Outcome = Data.define(:kind, :reason, :root, :top, :nested_in, :message)
+
+    MARKER_TEXT = "# chi project marker: this folder is a chi project (docs/memory.md)\n"
+
+    module_function
+
+    def call(dir, home:)
+      dir = File.expand_path(dir.to_s)
+      found = MemoryPaths.lookup(dir, home: home)
+      if found.git?
+        message = "#{Paths.tilde(dir)} is in the git repository #{Paths.tilde(found.top)}: the repository already is " \
+                  "the project, nothing written"
+        return Outcome.new(kind: :git, reason: nil, root: found.root, top: found.top, nested_in: nil, message: message)
+      end
+      if MemoryPaths.above_home?(dir, home: home)
+        message = "#{Paths.tilde(dir)} is $HOME, a folder above it or /: it can't be a chi project " \
+                  "(every folder under it would be one); mark a folder inside it"
+        return Outcome.new(kind: :refused, reason: :above_home, root: found.root, top: found.top, nested_in: nil,
+                           message: message)
+      end
+
+      # The marked project this folder sits in, if any: the folder itself (already marked) or its parent project.
+      enclosing = found.marker? ? found.root : nil
+      if enclosing == Guardrails::PathResolve.real(dir)
+        return Outcome.new(kind: :already_marked, reason: nil, root: enclosing, top: found.top, nested_in: nil,
+                           message: "#{Paths.tilde(enclosing)} is already a chi project")
+      end
+
+      write_marker(dir)
+      root = File.realpath(dir)
+      # No message: each surface words its own success (the CLI's report, the web's navigation).
+      Outcome.new(kind: :created, reason: nil, root: root, top: root, nested_in: enclosing, message: nil)
+    rescue SystemCallError => e
+      marker = File.join(dir, MemoryPaths::MARKER)
+      write_failed("couldn't write #{Paths.tilde(marker)}: #{e.message}")
+    end
+
+    # chi web opens a folder in a git repository without marking it, so the folder has to exist.
+    # @return [Outcome, nil] a refused (:write_failed) outcome when it can't be made, else nil
+    def ensure_folder(dir)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+      nil
+    rescue SystemCallError => e
+      write_failed("couldn't create #{Paths.tilde(dir)}: #{e.message}")
+    end
+
+    def write_failed(message)
+      Outcome.new(kind: :refused, reason: :write_failed, root: nil, top: nil, nested_in: nil, message: message)
+    end
+    private_class_method :write_failed
+
+    def write_marker(dir)
+      marker = File.join(dir, MemoryPaths::MARKER)
+      FileUtils.mkdir_p(File.dirname(marker))
+      File.write(marker, MARKER_TEXT)
+    end
+    private_class_method :write_marker
+  end
+end

data/lib/samagotchi/project_scope.rb

@@ -4,9 +4,10 @@ require_relative "memory_paths"
 
 module Samagotchi
   # Which project a folder belongs to, for scoping session lists (web and
-  # terminal alike): the project root memories use (MemoryPaths.project_root),
-  # so every worktree and subfolder of one repository is one project. A
-  # folder in no git repository has no project (nil): its scope is "all".
+  # terminal alike): the project root memories use (MemoryPaths.lookup), so
+  # every worktree and subfolder of one repository, or every subfolder of a
+  # folder marked by `chi project init`, is one project. A folder in neither
+  # has no project (nil): its scope is "all".
   module ProjectScope
     module_function
 
@@ -17,7 +18,8 @@ module Samagotchi
       return nil if dir.empty?
       return cache[dir] if cache&.key?(dir)
 
-      root = MemoryPaths.in_repo?(dir) ? MemoryPaths.project_root(File.expand_path(dir)) : nil
+      found = MemoryPaths.lookup(File.expand_path(dir))
+      root = found.project? ? found.root : nil
       cache[dir] = root if cache
       root
     end

data/lib/samagotchi/prompt_files.rb

@@ -19,9 +19,10 @@ module Samagotchi
     module_function
 
     # The AGENTS.md files a session in +cwd+ loads, as absolute paths,
-    # outermost first: inside a git work tree every one from its top (a
-    # linked worktree's own checkout) down to the cwd; outside a repository
-    # only the cwd's ([] with none).
+    # outermost first: inside a project every one from its top
+    # (MemoryPaths.project_top: a git work tree's, a linked worktree's own
+    # checkout, or a folder marked by `chi project init`) down to the cwd;
+    # outside a project only the cwd's ([] with none).
     # @param cwd [String] where the prompt is built (Dir.pwd, not the
     #   session's working directory: /tmp vs /private/tmp would change the
     #   prompt bytes)
@@ -33,10 +34,10 @@ module Samagotchi
     # The sections of the AGENTS.md chain (#agents_paths) with text: the
     # first keeps the plain header (a one-file session's prompt is as it
     # always was), each further one names its directory relative to the
-    # work tree top ("Project specific description for pkg/:").
+    # project's top ("Project specific description for pkg/:").
     # @return [Array<Section>]
     def agents_sections(cwd)
-      top = MemoryPaths.work_tree_root(cwd)
+      top = MemoryPaths.project_top(cwd)
       sections = []
       agents_paths(cwd).each do |path|
         dir = File.dirname(path)
@@ -47,10 +48,12 @@ module Samagotchi
       sections
     end
 
-    # The directories whose AGENTS.md a session in +cwd+ reads, outermost first.
+    # The directories whose AGENTS.md a session in +cwd+ reads, outermost
+    # first: from its project's top (the work tree's, or the marked root)
+    # down to +cwd+.
     def chain_dirs(cwd)
       cwd = File.expand_path(cwd)
-      top = MemoryPaths.work_tree_root(cwd)
+      top = MemoryPaths.project_top(cwd)
       return [cwd] unless top
 
       rel = relative_dir(cwd, top)

data/lib/samagotchi/recap_place.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "steer"
-require_relative "bridge/card_places"
 
 module Samagotchi
   # Where a saved recap sits among the turns a page draws: after the last
   # turn opening it covers (Steer.turn_opening?, the rule its turns_since
   # count goes by). Its stamp is that opening's id, as a card's is
-  # (Bridge::CardPlaces.stamp: a prompt's turn_id, a wake note's, a
-  # /continue no reason line's opening_id), so the page finds the bubble by
+  # (Steer.opening_stamp: a prompt's turn_id, a wake note's, a /continue no
+  # reason line's opening_id), so the page finds the bubble by
   # id, not by counting back (a rollback or a check-in could make the count
   # land a turn off). Read at read time from recap.json's `covered`: the file
   # is unchanged, an old one gets a stamp too. Pure.
@@ -21,7 +20,7 @@ module Samagotchi
     #   messages; nil for none, or one with no id (a line an older chi wrote)
     def opening_id(messages, covered)
       opening = Array(messages).first([covered.to_i, 0].max).reverse_each.find { |message| Steer.turn_opening?(message) }
-      opening && Bridge::CardPlaces.stamp(opening)
+      opening && Steer.opening_stamp(opening)
     end
   end
 end

data/lib/samagotchi/run_options.rb

@@ -213,6 +213,7 @@ module Samagotchi
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi home [set [--ruby PATH] | doctor]   the Ruby every chi launch boots
+                 chi project [init [DIR]]         this folder's project; init makes a folder in no git repository one
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME
                  chi --remote NAME <send|answer|note|context|sessions|share|review> …   those commands on that machine (or CHI_REMOTE=NAME)
                  chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]   a session on that machine, in this terminal

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].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_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/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/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