samagotchi 0.159.0 → 0.161.0

data/lib/samagotchi/project_command.rb

@@ -19,33 +19,40 @@ module Samagotchi
     include CLI::Command
 
     USAGE = <<~TEXT
-      Usage: chi project [init [DIR]]
+      Usage: chi project [init [--new-id] [DIR]]
         (none)       this folder's project: how it was found (git, marker or none), its root, its
-                     top and its project memories folder
+                     top, its id 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
+                     DIR/#{MemoryPaths::MARKER} with an id, so DIR and every subfolder share one project
+                     memories folder (kept when DIR moves) and group their sessions. Not in a git
+                     repository (it already is the project), nor $HOME or a folder above it. On a
+                     marked folder with no id: adopts one, moving its folders to it
+        --new-id     a marked folder's own new id (a copied folder going its own way): its
+                     memories and project context copied to it
     TEXT
 
     SUBCOMMANDS = %w[init].freeze
     FLAGS = {
       nil => CLI::Flags.new(help: HELP_WORDS, args: false),
-      "init" => CLI::Flags.new(help: HELP_WORDS)
+      "init" => CLI::Flags.new(help: HELP_WORDS) { |f| f.switch "--new-id" }
     }.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)
+    #   init's restart note and its adoption's running check;
+    #   SessionManager.session_rows by default)
+    # @param state_dir [String, nil] the sessions dir (an adoption moves the
+    #   project context folders beside it)
     def initialize(argv, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd, env: ENV, home: MemoryPaths.default_home,
-                   sessions: nil)
+                   sessions: nil, state_dir: nil)
       @argv = argv.dup
       @stdout = stdout
       @stderr = stderr
       @cwd = cwd
       @env = env
       @home = home
+      @state_dir = state_dir
       @sessions = sessions || lambda {
         require_relative "session_manager"
         SessionManager.session_rows
@@ -61,7 +68,8 @@ module Samagotchi
       return run_show unless @sub
       return usage_error("init takes one folder") if parsed.args.size > 1
 
-      run_init(parsed.args.first || @cwd)
+      dir = File.expand_path(parsed.args.first || @cwd, @cwd)
+      parsed.options[:new_id] ? run_new_id(dir) : run_init(dir)
     end
 
     private
@@ -78,15 +86,17 @@ module Samagotchi
         row("root", found.root)
         row("top", found.top)
       end
-      row("memories", memories_line(found.root))
+      row("id", found.id) if found.id
+      row("memories", memories_line(found))
       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))
+    # @param found [MemoryPaths::ProjectLookup] the project (its root and id key the folder)
+    def memories_line(found)
+      dir = File.join(MemoryPaths.projects_dir(env: @env), MemoryPaths.key_for(root: found.root, id: found.id))
       count = memory_count(dir)
       "#{Paths.tilde(dir)}#{" (#{count} #{count == 1 ? "memory" : "memories"})" if count.positive?}"
     end
@@ -115,8 +125,7 @@ module Samagotchi
     end
 
     def run_init(dir)
-      dir = File.expand_path(dir, @cwd)
-      outcome = ProjectInit.call(dir, home: @home)
+      outcome = ProjectInit.adopt(dir, home: @home, env: @env, state_dir: @state_dir, sessions: adopt_rows(dir))
       case outcome.kind
       when :git
         found = MemoryPaths::ProjectLookup.new(kind: :git, root: outcome.root, top: outcome.top)
@@ -130,7 +139,10 @@ module Samagotchi
         @stdout.puts(outcome.message)
         CLI::Exit::OK
       when :created
-        report_init(outcome.root, nested_in: outcome.nested_in)
+        report_init(outcome)
+        CLI::Exit::OK
+      when :adopted
+        @stdout.puts(outcome.message)
         CLI::Exit::OK
       end
     rescue SystemCallError => e
@@ -138,10 +150,34 @@ module Samagotchi
       CLI::Exit::FAILED
     end
 
-    def report_init(root, nested_in:)
-      nested = nested_in ? ", its own project nested in #{Paths.tilde(nested_in)}" : ""
+    def run_new_id(dir)
+      outcome = ProjectInit.new_id(dir, home: @home, env: @env, state_dir: @state_dir)
+      if outcome.kind == :refused
+        error_line("#{command_name} --new-id: #{outcome.message}")
+        return CLI::Exit::FAILED
+      end
+
+      @stdout.puts(outcome.message)
+      sessions_note(outcome.root, restart: "keep the id they started with until restarted")
+      CLI::Exit::OK
+    end
+
+    # The rows an adoption checks for running sessions: only for a marked
+    # folder (a listing is a walk of every session file).
+    def adopt_rows(dir)
+      found = lookup(dir)
+      return [] if found.git? || found.id
+
+      @sessions.call
+    end
+
+    def report_init(outcome)
+      root = outcome.root
+      nested = outcome.nested_in ? ", its own project nested in #{Paths.tilde(outcome.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))
+      row("id", outcome.id) if outcome.id
+      row("memories", memories_line(lookup(root)))
+      @stdout.puts(outcome.message) if outcome.message
       sessions_note(root)
     end
 
@@ -150,15 +186,17 @@ module Samagotchi
     # 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)
+    def sessions_note(root, restart: nil)
       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 " \
+        @stdout.puts("running sessions in it #{restart || "keep the old project in their prompt until restarted"} " \
                      "(chi sessions restart ID): #{live.map { |r| r.id[0, 8] }.join(", ")}")
       end
+      return if restart
+
       @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})")

data/lib/samagotchi/project_id.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "yaml"
+require_relative "log"
+
+module Samagotchi
+  # A marked project's id: the `id:` line of its .chi/project.yml
+  # (MemoryPaths::MARKER), written by `chi project init`. A marked project
+  # with an id keys its memories and project context sources by the id
+  # (MemoryPaths.key_for), so moving or renaming the folder keeps them; one
+  # without (an older marker, a bad hand edit) keys by its path. Git
+  # repositories never have one: only MemoryPaths.lookup's :marker kind
+  # reads it.
+  #
+  # Ids are `<basename>-<8 hex>`, a hyphen where a path key has its
+  # underscore, so MemoryOrphans' "same basename, other hash" pattern never
+  # takes an id folder for a moved project's path key.
+  module ProjectId
+    # A valid id: what a folder name and a URL segment can hold.
+    PATTERN = /\A[A-Za-z0-9][A-Za-z0-9_.-]{0,63}\z/
+    # The marker is a small file; anything longer is read this far.
+    READ_LIMIT = 4096
+
+    # What a marker says: +id+ (a valid id, else nil) and +problem+ (why a
+    # present `id:` is no id: "the id line is not valid YAML" …; nil with a
+    # valid id or no id line at all). The one wording: the resolver's debug
+    # line and `chi project init`'s report both say +problem+.
+    Read = Data.define(:id, :problem) do
+      def id? = !id.nil?
+    end
+
+    NONE = Read.new(id: nil, problem: nil)
+
+    module_function
+
+    # The marker at +root+ (a marked folder), read once: never raises.
+    # @return [Read]
+    def read(root)
+      path = File.join(root, ".chi", "project.yml")
+      parse(File.open(path, "rb") { |file| file.read(READ_LIMIT) }.to_s)
+    rescue SystemCallError, IOError => e
+      Read.new(id: nil, problem: "the marker can't be read (#{e.message})")
+    end
+
+    # @return [Read]
+    def parse(text)
+      text = text.dup.force_encoding(Encoding::UTF_8)
+      return Read.new(id: nil, problem: "the marker is not UTF-8 text") unless text.valid_encoding?
+
+      data = YAML.safe_load(text)
+      return NONE if data.nil?
+      return Read.new(id: nil, problem: "the marker is not a YAML mapping") unless data.is_a?(Hash)
+      return NONE unless data.key?("id")
+
+      check(data["id"])
+    rescue Psych::Exception
+      Read.new(id: nil, problem: "the marker is not valid YAML")
+    end
+
+    # @return [Read]
+    def check(value)
+      return Read.new(id: value, problem: nil) if value.is_a?(String) && value.match?(PATTERN)
+
+      Read.new(id: nil, problem: "its id #{value.inspect[0, 80]} is not a valid id " \
+                                 "(letters, digits, '_', '.', '-'; up to 64; a letter or digit first)")
+    end
+
+    # A fresh id for a folder named +basename+: the name's id-safe part and
+    # 8 random hex digits.
+    def generate(basename)
+      name = basename.to_s.gsub(/[^A-Za-z0-9_.-]+/, "-").sub(/\A[^A-Za-z0-9]+/, "")[0, 55].sub(/[-.]+\z/, "")
+      name = "project" if name.empty?
+      "#{name}-#{SecureRandom.hex(4)}"
+    end
+
+    # The marker's text with its id line set to +id+ (replaced, or appended),
+    # every other line kept.
+    def with_id(text, id)
+      line = "id: #{id}\n"
+      lines = text.to_s.lines
+      at = lines.index { |l| l.match?(/\Aid\s*:/) }
+      return lines.tap { |all| all[at] = line }.join if at
+
+      body = lines.join
+      body += "\n" unless body.empty? || body.end_with?("\n")
+      body + line
+    end
+
+    @logged = Set.new
+    @logged_lock = Mutex.new
+
+    # One debug line per (root, problem) and process: the resolver runs on
+    # every memory call.
+    def log_problem(root, read)
+      return unless read.problem
+
+      first = @logged_lock.synchronize { @logged.add?([root, read.problem]) }
+      Log.debug(:memory, "project_id_ignored", root: root, problem: read.problem) if first
+    end
+  end
+end

data/lib/samagotchi/project_id_clash.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "atomic_file"
+require_relative "memory_paths"
+require_relative "paths"
+
+module Samagotchi
+  # Two folders with one chi project id: a marked folder copied (cp -R)
+  # keeps its marker, so the copy shares the original's memories. Told at
+  # session start (Engine#announce_load_events!, label "memory", beside
+  # MemoryOrphans), at every session start while it lasts.
+  #
+  # The claim: an id-keyed memories folder's `.root` names the folder that
+  # last started a session with it (one line; a dotfile, so no *.md glob
+  # lists it). Written only here, at session start, never by the key
+  # resolver: a read-only command or a memory call must not write.
+  ProjectIdClash = Data.define(:root, :other, :id) do
+    # The one text for the condition.
+    def message
+      "#{Paths.tilde(root)} and #{Paths.tilde(other)} share chi project id #{id} (a copied folder?): they share " \
+        "memories; `chi project init --new-id` gives this one its own."
+    end
+  end
+
+  class ProjectIdClash
+    CLAIM = ".root"
+
+    # +cwd+'s project, when a marked one with an id: a clash when the claim
+    # names another folder that still has a marker with this id; otherwise
+    # the claim is set to this root (when it changes; a moved folder just
+    # takes it over). Only once the id folder exists: nothing is made for a
+    # project with no memories yet.
+    # @return [ProjectIdClash, nil]
+    def self.check(env: ENV, cwd: Dir.pwd, home: MemoryPaths.default_home)
+      found = MemoryPaths.lookup(cwd, home: home)
+      return nil unless found.id
+
+      dir = File.join(MemoryPaths.projects_dir(env: env), found.id)
+      return nil unless File.directory?(dir)
+
+      claim = File.join(dir, CLAIM)
+      other = File.file?(claim) ? File.read(claim, 4096).to_s.lines.first.to_s.strip : ""
+      return nil if other == found.root
+      return new(root: found.root, other: other, id: found.id) if same_project?(other, found.id, home)
+
+      AtomicFile.write(claim, "#{found.root}\n")
+      nil
+    rescue SystemCallError
+      nil
+    end
+
+    # Whether +other+ still is a marked folder with +id+ (not gone, not
+    # given another id).
+    def self.same_project?(other, id, home)
+      return false if other.empty? || !File.directory?(other)
+
+      found = MemoryPaths.lookup(other, home: home)
+      found.marker? && found.root == File.realpath(other) && found.id == id
+    end
+    private_class_method :same_project?
+  end
+end

data/lib/samagotchi/project_init.rb

@@ -1,20 +1,43 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require_relative "atomic_file"
+require_relative "context_sources"
 require_relative "guardrails/path_resolve"
+require_relative "memory_orphans"
 require_relative "memory_paths"
 require_relative "paths"
+require_relative "project_id"
+require_relative "session_paths"
 
 module Samagotchi
-  # The shared decisions for `chi project init` and chi web's project picker.
+  # The shared decisions for `chi project init` and chi web's project picker,
+  # and every text they refuse or report with (the CLI prints them). A new
+  # marker gets an id (ProjectId); #adopt gives an older marker one, #new_id
+  # a copied folder its own.
   module ProjectInit
-    Outcome = Data.define(:kind, :reason, :root, :top, :nested_in, :message)
+    # +id+: the project's id (ProjectId), nil for none (a git repository, a
+    # marker without one, a refusal).
+    Outcome = Data.define(:kind, :reason, :root, :top, :nested_in, :message, :id) do
+      def initialize(kind:, reason:, root:, top:, nested_in:, message:, id: nil) = super
+    end
+
+    # A folder keyed by the project key (MemoryPaths.key_for): under +base+,
+    # named +prefix+ + the key.
+    Place = Data.define(:base, :prefix) do
+      def path(key) = File.join(base, "#{prefix}#{key}")
+    end
 
     MARKER_TEXT = "# chi project marker: this folder is a chi project (docs/memory.md)\n"
 
     module_function
 
-    def call(dir, home:)
+    # Marks +dir+ (a new marker gets an id), or says why not. A folder whose
+    # path key already names a folder (memories kept while it was no
+    # project, keyed by the same path) is marked without an id, so nothing
+    # it has goes out of reach: #adopt moves those and writes the id.
+    # @param state_dir [String, nil] the sessions dir (SessionPaths.default_state_dir)
+    def call(dir, home:, env: ENV, state_dir: nil)
       dir = File.expand_path(dir.to_s)
       found = MemoryPaths.lookup(dir, home: home)
       if found.git?
@@ -32,19 +55,94 @@ module Samagotchi
       # 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)
+        id_part = found.id ? " (id #{found.id})" : ""
         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")
+                           message: "#{Paths.tilde(enclosing)} is already a chi project#{id_part}", id: found.id)
       end
 
-      write_marker(dir)
+      id = write_marker(dir, places(env: env, state_dir: state_dir || SessionPaths.default_state_dir(env: env)))
       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)
+      Outcome.new(kind: :created, reason: nil, root: root, top: root, nested_in: enclosing, message: nil, id: id)
     rescue SystemCallError => e
       marker = File.join(dir, MemoryPaths::MARKER)
       write_failed("couldn't write #{Paths.tilde(marker)}: #{e.message}")
     end
 
+    # `chi project init` (the CLI only: chi web's New-project row calls
+    # #call, which never moves folders): #call, and for a marked folder
+    # with no valid id, its adoption of one. The folders keyed by its path
+    # key (its memories, its project context sources, the skills bundle's
+    # kept versions) move to the id, each leaving a link by its old name so
+    # an older chi, keying by path, finds the same folder; then the id is
+    # written (a crash before that leaves the path key reaching the moved
+    # folders through the links, and a rerun finishes with the same id).
+    # Refused while a running session belongs to the project: its worker
+    # could write a memory under the old name between a move and its link.
+    # @param state_dir [String, nil] the sessions dir (SessionPaths.default_state_dir)
+    # @param sessions [Array<SessionRow>] this machine's sessions (+live+, +project+, +id+)
+    # A folder #call marked without an id is adopted the same way.
+    # @param sessions [Array<SessionRow>] this machine's sessions (+live+,
+    #   +project+, +cwd+, +id+): a running one in the project (by the root it
+    #   stored, else its folder's) refuses
+    # @return [Outcome] :adopted (its message the report), :created (its
+    #   message what moved, nil when nothing did) or #call's
+    def adopt(dir, home:, env: ENV, state_dir: nil, sessions: [])
+      state_dir ||= SessionPaths.default_state_dir(env: env)
+      outcome = call(dir, home: home, env: env, state_dir: state_dir)
+      return outcome unless %i[already_marked created].include?(outcome.kind) && outcome.id.nil?
+
+      root = outcome.root
+      running = Array(sessions).select do |row|
+        row.live && (row.project ? row.project == root : MemoryPaths.lookup(row.cwd.to_s, home: home).root == root)
+      end
+      unless running.empty?
+        return refused(:running, root, "#{Paths.tilde(root)} has running sessions " \
+                                       "(#{running.map { |row| row.id[0, 8] }.join(", ")}): stop them " \
+                                       "(chi sessions stop ID) and rerun chi project init, which moves the " \
+                                       "project's folders while no session can write to them")
+      end
+
+      adopted = adopt_id(root, env: env, state_dir: state_dir)
+      return adopted unless outcome.kind == :created && adopted.kind == :adopted
+
+      # A new project: the CLI words its success; the report keeps what moved.
+      moved = adopted.message.lines.drop(1).join.chomp
+      outcome.with(id: adopted.id, message: moved.empty? ? nil : moved)
+    rescue SystemCallError => e
+      write_failed("couldn't adopt an id for #{Paths.tilde(outcome&.root || dir.to_s)}: #{e.message}")
+    end
+
+    # `chi project init --new-id`: a fresh id for a marked folder (a copied
+    # one, going its own way), its folders copied from the key it had to the
+    # new id (the copy keeps what it had; the other folder keeps its own).
+    # @return [Outcome] :new_id (its message the report) or :refused
+    def new_id(dir, home:, env: ENV, state_dir: nil)
+      dir = File.expand_path(dir.to_s)
+      found = MemoryPaths.lookup(dir, home: home)
+      unless found.marker? && found.root == Guardrails::PathResolve.real(dir)
+        return refused(:not_marked, nil, "#{Paths.tilde(dir)} is not a marked chi project folder: --new-id gives " \
+                                         "one (made with chi project init) an id of its own")
+      end
+
+      root = found.root
+      old_key = MemoryPaths.key_for(root: root, id: found.id)
+      id = ProjectId.generate(File.basename(root))
+      lines = ["#{Paths.tilde(root)} has a chi project id of its own now: #{id} (was #{found.id || "none: keyed by its path"})"]
+      places(env: env, state_dir: state_dir || SessionPaths.default_state_dir(env: env)).each do |place|
+        from = place.path(old_key)
+        next unless File.directory?(from)
+
+        to = place.path(id)
+        copy_folder(File.realpath(from), to)
+        lines << "copied #{Paths.tilde(from)} to #{Paths.tilde(to)}"
+      end
+      write_id(root, id)
+      Outcome.new(kind: :new_id, reason: nil, root: root, top: root, nested_in: nil, message: lines.join("\n"), id: id)
+    rescue SystemCallError => e
+      write_failed("couldn't give #{Paths.tilde(dir)} a new id: #{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)
@@ -54,16 +152,122 @@ module Samagotchi
       write_failed("couldn't create #{Paths.tilde(dir)}: #{e.message}")
     end
 
+    # The folders a project key names: its memories, its project context
+    # sources (where the workers keep them: ContextSources.root), and the
+    # skills bundle's kept versions of its project skills (history/
+    # project-<key>, the bundle's own data dir).
+    # @return [Array<Place>]
+    def places(env:, state_dir:)
+      [Place.new(base: MemoryPaths.projects_dir(env: env), prefix: ""),
+       Place.new(base: File.join(ContextSources.root(state_dir: state_dir), "projects"), prefix: ""),
+       Place.new(base: File.join(File.dirname(state_dir), "plugins", "skills", "history"), prefix: "project-")]
+    end
+
+    def adopt_id(root, env:, state_dir:)
+      problem = ProjectId.read(root).problem
+      path_key = MemoryPaths.key_for_root(root)
+      # Before the id: what MemoryOrphans finds for the project keyed by its path.
+      orphans = MemoryOrphans.find(env: env, cwd: root)
+      list = places(env: env, state_dir: state_dir)
+      id = resumed_id(list.first, path_key) || ProjectId.generate(File.basename(root))
+      taken = list.map { |place| [place.path(path_key), place.path(id)] }
+                  .find { |from, to| real_dir?(from) && (File.exist?(to) || File.symlink?(to)) }
+      if taken
+        return refused(:id_taken, root, "#{Paths.tilde(taken[1])} already exists: chi project init can't move " \
+                                        "#{Paths.tilde(taken[0])} there; nothing moved")
+      end
+
+      lines = ["#{Paths.tilde(root)} now has the chi project id #{id}: its memories and project context stay " \
+               "with it when the folder moves or is renamed"]
+      lines << "#{problem}: replaced" if problem
+      list.each { |place| lines.concat(move_folder(place.path(path_key), place.path(id))) }
+      write_id(root, id)
+      if orphans
+        keys = orphans.candidates.map { |candidate| "#{Paths.tilde(candidate)} (#{MemoryOrphans.key_note(candidate)})" }
+        lines << "memories with this folder's name under another key: #{keys.join(", ")}; if they are this " \
+                 "project's, move their files into #{Paths.tilde(list.first.path(id))}"
+      end
+      Outcome.new(kind: :adopted, reason: nil, root: root, top: root, nested_in: nil, message: lines.join("\n"), id: id)
+    end
+
+    # The id an adoption that crashed before writing it chose: the path
+    # key already a link to an id folder beside it.
+    def resumed_id(place, path_key)
+      link = place.path(path_key)
+      return nil unless File.symlink?(link)
+
+      target = File.readlink(link)
+      target if target.match?(ProjectId::PATTERN) && File.directory?(place.path(target))
+    end
+
+    def real_dir?(path) = File.directory?(path) && !File.symlink?(path)
+
+    # Move +from+ to +to+ and leave a link named +from+ (relative: the
+    # folder may move with its parent). Nothing to move (no folder, or a
+    # link already): no move and no link. A folder made again at +from+
+    # between the move and the link has its files moved over (none
+    # replaced), then gives way to the link; what was in both stays.
+    # @return [Array<String>] the report's lines
+    def move_folder(from, to)
+      return [] unless real_dir?(from)
+
+      File.rename(from, to)
+      begin
+        File.symlink(File.basename(to), from)
+      rescue Errno::EEXIST
+        Dir.children(from).each do |name|
+          File.rename(File.join(from, name), File.join(to, name)) unless File.exist?(File.join(to, name))
+        end
+        unless Dir.empty?(from)
+          return ["moved #{Paths.tilde(from)} to #{Paths.tilde(to)}; files written to the old folder meanwhile " \
+                  "that #{Paths.tilde(to)} has too stay in #{Paths.tilde(from)}"]
+        end
+
+        Dir.rmdir(from)
+        File.symlink(File.basename(to), from)
+      end
+      ["moved #{Paths.tilde(from)} to #{Paths.tilde(to)} (the old name links to it, for an older chi)"]
+    end
+
+    # +to+ made a copy of +from+'s files, without the copied project's
+    # claim (.root: ProjectIdClash).
+    def copy_folder(from, to)
+      FileUtils.mkdir_p(to)
+      FileUtils.cp_r(File.join(from, "."), to)
+      FileUtils.rm_f(File.join(to, ".root"))
+    end
+
+    def write_id(root, id)
+      marker = File.join(root, MemoryPaths::MARKER)
+      AtomicFile.write(marker, ProjectId.with_id(File.read(marker), id))
+    end
+
+    def refused(reason, root, message)
+      Outcome.new(kind: :refused, reason: reason, root: root, top: root, nested_in: nil, message: 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)
+    # @param places [Array<Place>] the folders a key names (#places)
+    # @return [String, nil] the new marker's id; nil when a folder already
+    #   has the path key (#call)
+    def write_marker(dir, places)
       marker = File.join(dir, MemoryPaths::MARKER)
       FileUtils.mkdir_p(File.dirname(marker))
-      File.write(marker, MARKER_TEXT)
+      root = File.realpath(dir)
+      key = MemoryPaths.key_for_root(root)
+      if places.any? { |place| File.exist?(place.path(key)) || File.symlink?(place.path(key)) }
+        File.write(marker, MARKER_TEXT)
+        return nil
+      end
+
+      id = ProjectId.generate(File.basename(root))
+      File.write(marker, ProjectId.with_id(MARKER_TEXT, id))
+      id
     end
-    private_class_method :write_marker
+    private_class_method :write_failed, :write_marker, :refused, :adopt_id, :resumed_id, :real_dir?, :move_folder,
+                         :copy_folder, :write_id
   end
 end

data/lib/samagotchi/project_scope.rb

@@ -18,10 +18,19 @@ module Samagotchi
       return nil if dir.empty?
       return cache[dir] if cache&.key?(dir)
 
-      found = MemoryPaths.lookup(File.expand_path(dir))
-      root = found.project? ? found.root : nil
+      root = project_for(dir)&.root
       cache[dir] = root if cache
       root
     end
+
+    # +dir+'s project (MemoryPaths::ProjectLookup: its root and, for a
+    # marked project, its id), or nil in none.
+    def project_for(dir)
+      dir = dir.to_s
+      return nil if dir.empty?
+
+      found = MemoryPaths.lookup(File.expand_path(dir))
+      found.project? ? found : nil
+    end
   end
 end

data/lib/samagotchi/review_start.rb

@@ -80,7 +80,8 @@ module Samagotchi
       setup = setup.with(toolkit_origin: "chosen")
       SessionManager.spawn_session(prompt: nil, preview: preview(subjects), working_directory: dir, model_name: model,
                                    setup: setup, review: SessionReview.new(subjects: subjects),
-                                   note: note(subjects: subjects), note_source: NOTE_SOURCE, state_dir: state_dir)
+                                   note: note(subjects: subjects), note_source: NOTE_SOURCE, state_dir: state_dir,
+                                   client_id: nil)
     end
 
     # A review fork of +from+ (an id, a prefix, or last:<id>): a new session
@@ -106,9 +107,10 @@ module Samagotchi
       recap = RecapStore.read(Session.session_dir(source.id, state_dir: sd))
       session = SessionManager.spawn_session(
         prompt: nil, preview: preview(subjects, source: source), working_directory: dir, model_name: choice.model,
-        setup: SessionSetup.of(source).with(toolkit_origin: "chosen"),
+        setup: SessionSetup.of(source).with(preloaded_memory_names: [], toolkit_origin: "chosen"),
         review: SessionReview.new(subjects: subjects, from: source.id),
-        note: note(subjects: subjects, source: source, recap: recap, seed: seed), note_source: NOTE_SOURCE, state_dir: sd
+        note: note(subjects: subjects, source: source, recap: recap, seed: seed), note_source: NOTE_SOURCE,
+        state_dir: sd, client_id: nil
       )
       warnings = [choice.warning, session.model_warning].compact
       session.model_warning = warnings.join("; ") unless warnings.empty?