samagotchi 0.159.0 → 0.160.0

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -52,7 +52,8 @@ module Samagotchi
       # mismatch warnings. merged and replaced are file
       # names, behind FileStanding::Behind; under plan they are what apply would
       # merge, replace or leave behind.
-      # adds is nil but for a profile: the members it installs.
+      # added_files is the new version's memory files the bundle didn't own
+      # before; adds is nil but for a profile: the members it installs.
       # kept_own is nil but for a profile that installed a member: its
       # Profile.kept_own_line lines.
       # trash_copy is nil but under apply when it saved edited files
@@ -62,8 +63,8 @@ module Samagotchi
       # manifest: what a row at the shipped version says of its manifest.yml
       # (ManifestStanding.keep's line: would keep or kept it, or why not and
       # the command), nil when nothing.
-      Row = Struct.new(:name, :from, :to, :status, :note, :merged, :behind, :replaced, :source_dir, :scope, :adds, :kept_own,
-                       :trash_copy, :earlier, :manifest, keyword_init: true) do
+      Row = Struct.new(:name, :from, :to, :status, :note, :merged, :behind, :replaced, :source_dir, :scope, :added_files, :adds,
+                       :kept_own, :trash_copy, :earlier, :manifest, keyword_init: true) do
         def kept = Array(behind).map(&:file)
       end
 
@@ -208,6 +209,7 @@ module Samagotchi
         return skip(row, "project scope: chi bundle upgrade #{ship.source} in the project") if row.scope == "project"
         return skip(row, "unknown scope #{row.scope}: upgrade chi or reinstall") unless MemoryPaths.scope_dir(row.scope)
 
+        row.added_files = (manifest.files.keys - bundle.files.keys).sort
         forecast = forecast(row, bundle)
         row.merged = forecast.merged
         row.behind = forecast.behind

data/lib/samagotchi/memory_bundle/status.rb

@@ -84,12 +84,12 @@ module Samagotchi
       private_class_method :digest_or_nil
 
       # The class-file hooks the record still has (a 0.157 install's; chi
-      # loads none, Manifest::HooksRetired), each "ok" or "missing" in
+      # loads none, Manifest::HooksRetired), each "present" or "missing" in
       # hooks/, by name; {} for none.
       # @return [Hash{String => String}]
       def self.retired_hooks(provenance, bundle)
         bundle.hooks.keys.sort.to_h do |file|
-          [file, File.exist?(File.join(provenance.hooks_dir, file)) ? "ok" : "missing"]
+          [file, File.exist?(File.join(provenance.hooks_dir, file)) ? "present" : "missing"]
         end
       end
 

data/lib/samagotchi/memory_bundle/uninstaller.rb

@@ -56,6 +56,8 @@ module Samagotchi
           # No file list, just remove provenance (rules, a plugin and scripts
           # live there too)
           save_edits(provenance, bundle)
+          plugin_path = provenance.plugin_path(bundle)
+          @removed_files << "plugin/#{File.basename(plugin_path)}" if plugin_path && File.exist?(plugin_path)
           FileUtils.rm_rf(provenance.bundle_dir)
           return true
         end

data/lib/samagotchi/memory_orphans.rb

@@ -6,7 +6,13 @@ module Samagotchi
   # A project memory folder left behind by a move: memories copied to a
   # machine (or a path) where the project root differs, so its key
   # (MemoryPaths.project_key: basename + MD5 of the root) differs too, and
-  # chi finds no project memories without a word about why.
+  # chi finds no project memories without a word about why. A marked
+  # project with an id is keyed by the id (`<basename>-<8 hex>`, which the
+  # pattern never takes for a path key): it is asked about only while its
+  # id folder holds no *.md, like any other (memories moved before it had
+  # an id). An id folder is a candidate itself for a project keyed by path
+  # with the same basename: a marked folder that `git init` made a
+  # repository.
   #
   # Pure: one listing of the projects dir, no git subprocess. Said at
   # session start (Engine#announce_load_events!, label "memory") and under a
@@ -33,10 +39,14 @@ module Samagotchi
       return nil if File.directory?(computed) && Dir.children(computed).any? { |name| name.end_with?(".md") }
 
       key = File.basename(computed)
-      # The root's basename, never a split of a key on "_" (a basename may hold one).
-      pattern = /\A#{Regexp.escape(File.basename(MemoryPaths.project_root(cwd)))}_\h{8}\z/
+      # The root's basename, never a split of a key on "_" (a basename may hold one): another path's key
+      # (<basename>_<8 hex>), or a marked project's id folder (<basename>-<8 hex>, ProjectId) a `git init`
+      # in the marked folder (git wins: keyed by its path again) left behind.
+      pattern = /\A#{Regexp.escape(File.basename(MemoryPaths.project_root(cwd)))}[_-]\h{8}\z/
       names = Dir.children(projects).select { |name| name != key && name.match?(pattern) }
-      candidates = names.sort.map { |name| File.join(projects, name) }.select { |path| File.directory?(path) }
+      # A link is an adopted project's old name (ProjectInit.adopt), never an orphan.
+      candidates = names.sort.map { |name| File.join(projects, name) }
+                        .select { |path| File.directory?(path) && !File.symlink?(path) }
       return nil if candidates.empty?
 
       Found.new(computed: computed, candidates: candidates, computed_exists: File.directory?(computed))

data/lib/samagotchi/memory_paths.rb

@@ -3,6 +3,7 @@
 require "digest"
 require_relative "config"
 require_relative "guardrails/path_resolve"
+require_relative "project_id"
 
 module Samagotchi
   # Where memories live: <config dir>/memories, i.e. $XDG_CONFIG_HOME/samagotchi/memories
@@ -23,8 +24,12 @@ module Samagotchi
     # :none; +root+ is what memories are keyed on (#project_root: git's
     # common-dir checkout, the marked folder's realpath, or the folder
     # itself); +top+ is the folder a session reads its AGENTS.md chain from
-    # (the work tree's top, the marked root; nil for :none).
-    ProjectLookup = Data.define(:kind, :root, :top) do
+    # (the work tree's top, the marked root; nil for :none); +id+ is the
+    # marker's id (ProjectId), set only for kind :marker with a valid one
+    # (a git repository, and a marker #lookup ignores, never give one).
+    ProjectLookup = Data.define(:kind, :root, :top, :id) do
+      def initialize(kind:, root:, top:, id: nil) = super
+
       def project? = kind != :none
       def git? = kind == :git
       def marker? = kind == :marker
@@ -47,7 +52,7 @@ module Samagotchi
       return ProjectLookup.new(kind: :git, root: git_root(dot_git), top: File.dirname(dot_git)) if dot_git
 
       marked = nearest_marker(cwd, home: home)
-      return ProjectLookup.new(kind: :marker, root: marked, top: marked) if marked
+      return ProjectLookup.new(kind: :marker, root: marked, top: marked, id: marker_id(marked)) if marked
 
       ProjectLookup.new(kind: :none, root: cwd, top: nil)
     end
@@ -73,12 +78,30 @@ module Samagotchi
       File.join(system_dir(env: env), "projects")
     end
 
-    # One folder per project root: basename + 8 hex chars of MD5(full root path).
-    def project_key(cwd = Dir.pwd) = key_for_root(project_root(cwd))
+    # One folder per project: a marked project's id (ProjectId), else its
+    # root's path key (#key_for_root).
+    def project_key(cwd = Dir.pwd)
+      found = lookup(cwd)
+      key_for(root: found.root, id: found.id)
+    end
+
+    # The key of a project already resolved: +id+ (a ProjectLookup's, a
+    # session's project_id) when there is one, else +root+'s path key. Every
+    # caller holding a root keys here, with the id that came with it.
+    def key_for(root:, id:) = id || key_for_root(root)
 
-    # #project_key for a root already resolved (a session's project_root).
+    # The path key: basename + 8 hex chars of MD5(full root path). Pure: it
+    # reads no file (#key_for adds the id).
     def key_for_root(root) = "#{File.basename(root)}_#{Digest::MD5.hexdigest(root)[0..7]}"
 
+    # The id in the marker at +root+, or nil (none, or not a valid one: one
+    # debug line says why).
+    def marker_id(root)
+      read = ProjectId.read(root)
+      ProjectId.log_problem(root, read)
+      read.id
+    end
+
     # The project root (#lookup): in a repository, its common git directory
     # identifies the project; every linked worktree shares it. Returns the
     # checkout holding it when it is named .git, otherwise the git dir itself

data/lib/samagotchi/memory_usage.rb

@@ -124,7 +124,11 @@ module Samagotchi
       # The project the report is for, as MemoryPaths keys it (a worktree
       # resolves to its repository's root; both spellings of a path, /var and
       # /private/var, mean the same project).
-      @root = expand(MemoryPaths.project_root(File.expand_path(root.to_s)))
+      found = MemoryPaths.lookup(File.expand_path(root.to_s))
+      @root = expand(found.root)
+      # A marked project's id: its sessions from before a move (another
+      # stored root, the same id) are its sessions too.
+      @project_id = found.id
       @env = env
       @chars_per_token = chars_per_token.positive? ? chars_per_token.to_f : 4.0
       @warn_limit = warn_limit.to_i
@@ -331,23 +335,30 @@ module Samagotchi
       File.expand_path(dir)
     end
 
-    # The project a session belongs to: the root its file stores, or (a file
-    # from before the field, or a folder in no repository) the root of the
-    # folder it works in.
-    def session_project_root(session)
-      root = session.project_root ||
-             (session.working_directory.to_s.empty? ? nil : MemoryPaths.project_root(File.expand_path(session.working_directory.to_s)))
-      root && expand(root)
+    # The project a session belongs to, [root, id]: the root (and id) its
+    # file stores, or (a file from before the field, or a folder in no
+    # repository) the lookup of the folder it works in; [nil, nil] for none.
+    def session_project(session)
+      if session.project_root
+        [expand(session.project_root), session.project_id]
+      elsif !session.working_directory.to_s.empty?
+        found = MemoryPaths.lookup(File.expand_path(session.working_directory.to_s))
+        [expand(found.root), found.id]
+      else
+        [nil, nil]
+      end
     end
 
     def project_dir_of(session)
-      root = session_project_root(session)
-      root ? File.join(MemoryPaths.projects_dir(env: @env), MemoryPaths.key_for_root(root)) : nil
+      root, id = session_project(session)
+      root ? File.join(MemoryPaths.projects_dir(env: @env), MemoryPaths.key_for(root: root, id: id)) : nil
     end
 
-    # A session of this folder's project (worktrees of one repository share it).
+    # A session of this folder's project (worktrees of one repository share
+    # it; a marked project's sessions from before a move share its id).
     def project_session?(session)
-      session_project_root(session) == @root
+      root, id = session_project(session)
+      root == @root || (!@project_id.nil? && id == @project_id)
     end
 
     # "system/delegated" is the memory named delegated.

data/lib/samagotchi/plugin/attached_context.rb

@@ -152,7 +152,8 @@ module Samagotchi
         return [] unless id && Session.exist?(id, state_dir: state_dir)
 
         session = Session.load(id, state_dir: state_dir)
-        ContextSources.attached(id, project_root: session.project_root, state_dir: state_dir).map do |attached|
+        ContextSources.attached(id, project_root: session.project_root, project_id: session.project_id,
+                                    state_dir: state_dir).map do |attached|
           snapshot = attached.snapshot
           { name: attached.name, scope: attached.location.scope, why: attached.source.why,
             hint: snapshot.hint || attached.source.hint, fetched_at: snapshot.fetched_at, error: snapshot.error,
@@ -192,6 +193,7 @@ module Samagotchi
 
       def attached?(candidate, session)
         ContextSources.attached(session&.id || @host.session_id.call, project_root: session&.project_root,
+                                                                      project_id: session&.project_id,
                                                                       state_dir: state_dir, shadowed: true)
                       .any? { |a| a.name == candidate.name || (candidate.url && a.source.hint == candidate.url) }
       end

data/lib/samagotchi/plugin/sessions.rb

@@ -71,7 +71,10 @@ module Samagotchi
           prompt: prompt, working_directory: @host.cwd.call || Dir.pwd, model_name: @host.model_name&.call,
           parent_id: parent_id, messages: Array(messages).map { |message| unfrozen(message) }, preview: title,
           images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir,
-          setup: @host.setup&.call || SessionSetup.new, before_spawn: before_spawn
+          setup: @host.setup&.call || SessionSetup.new, before_spawn: before_spawn,
+          # The first prompt is the plugin's, as #send's is: no command of the
+          # owner's (CommandIntake), a ! line refused.
+          client_id: ClientId::PLUGIN
         )
         child.id
       rescue *REFUSED => e

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