samagotchi 0.158.0 → 0.160.0

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -83,6 +83,12 @@ module Samagotchi
 
         # The source's hooks/*.rb, relative and sorted ([] for none).
         def self.files_in(dir) = Dir.glob(File.join(dir, "hooks", "*.rb")).map { |f| "hooks/#{File.basename(f)}" }.sort
+
+        # Refuse a source's class-file hooks before parsing its manifest.
+        def self.refuse_source_files(dir)
+          files = files_in(dir)
+          raise for_files(files) unless files.empty?
+        end
       end
 
       # A plugin file is a plain .rb name in the bundle's top directory.

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "asset_installer"
+require_relative "asset_state"
 require_relative "installer"
 require_relative "listing"
 require_relative "manifest"
@@ -28,10 +29,11 @@ module Samagotchi
     #
     # .md files take the Installer's 3-way merge: a clean text merge replaces
     # the file (merged), a real conflict keeps the user's (behind). Rules,
-    # the plugin and scripts are replaced, an older chi's hooks removed; an edited one (Trash.edit?: its
-    # bytes neither the recorded sha, none recorded counting as edited, nor
-    # the incoming file's) is copied to the trash first and listed in
-    # replaced (#trash_bound).
+    # the plugin and scripts are replaced, an older chi's hooks removed; an
+    # edited one (AssetState#edited?, Trash.edit?'s rule: its bytes neither
+    # the recorded sha, none recorded counting as edited, nor the incoming
+    # file's) is copied to the trash first and listed in replaced
+    # (#trash_bound).
     #
     # A profile (a shipped meta bundle) is updated through Profile: its row
     # is :would_update when the shipped version is newer or it has members
@@ -50,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
@@ -60,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
 
@@ -206,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
@@ -293,21 +297,24 @@ module Samagotchi
       end
 
       # What the upgrade from +source_dir+ copies to the trash, as
-      # hooks/F, guardrails/F, plugin/F, scripts/F: Trash.edits over the
-      # folders AssetInstaller replaces or removes, each file against the one
-      # it puts in its place. Rules, the plugin and scripts: their whole
-      # folder, which the upgrade replaces. hooks/: an older chi's, which the
-      # upgrade removes whole (AssetInstaller#retire_hooks; no incoming).
+      # hooks/F, guardrails/F, plugin/F, scripts/F. Rules, the plugin and
+      # scripts: each file of the folders AssetInstaller replaces, against the
+      # one it puts in its place, that is AssetState#edited? (the upgrade's
+      # save_first: the same files, the same rule). hooks/: an older chi's,
+      # which the upgrade removes whole (AssetInstaller#retire_hooks; no
+      # incoming): Trash.edits over it.
       def trash_bound(name, bundle, manifest, source_dir)
         provenance = Provenance.new(name: name)
         rules = Dir.glob(File.join(source_dir, "guardrails", "*.yml")).sort
                    .reject { |file| AssetInstaller.linked?(file, source_dir) }
         plugin = manifest.plugin ? { manifest.plugin[:file] => File.join(source_dir, manifest.plugin[:file]) } : {}
         scripts = manifest.scripts.keys.to_h { |file| [file, File.join(source_dir, "scripts", file)] }
+        assets = AssetState.in(provenance.guardrails_dir, kind_of_file: :rule, recorded: bundle.guardrails,
+                                                          incoming: rules.to_h { |file| [File.basename(file), file] }) +
+                 AssetState.in(provenance.plugin_dir, kind_of_file: :plugin, recorded: bundle.plugin_shas, incoming: plugin) +
+                 AssetState.in(provenance.scripts_dir, kind_of_file: :script, recorded: bundle.scripts, incoming: scripts)
         Trash.edits(provenance.hooks_dir, "hooks", bundle.hooks.transform_values(&:sha256)) +
-          Trash.edits(provenance.guardrails_dir, "guardrails", bundle.guardrails, rules.to_h { |file| [File.basename(file), file] }) +
-          Trash.edits(provenance.plugin_dir, "plugin", bundle.plugin_shas, plugin) +
-          Trash.edits(provenance.scripts_dir, "scripts", bundle.scripts, scripts)
+          assets.select(&:edited?).map(&:label)
       end
 
       # Installed rules and the plugin whose sha differs from the recorded

data/lib/samagotchi/memory_bundle/status.rb

@@ -3,6 +3,7 @@
 require_relative "file_digest"
 require_relative "provenance"
 require_relative "file_state"
+require_relative "asset_state"
 require_relative "manifest"
 require_relative "../version"
 require_relative "index_updater"
@@ -23,8 +24,10 @@ module Samagotchi
       # paths at all). An entry's behind is its FileStanding::Behind, nil for a
       # file that isn't; merge_note its FileStanding::MergeNote, nil without one;
       # unreadable: the file is there, but this chi can't read it.
+      # rules and scripts: each recorded one by name, "ok", "modified" or
+      # "missing" (asset_states).
       Report = Data.define(:provenance, :scope, :scope_error, :target_dir, :files, :plugin,
-                           :retired_hooks, :needs)
+                           :rules, :scripts, :retired_hooks, :needs)
 
       # A scope this chi can't resolve (a newer chi's, a hand edit) isn't
       # guessed: scope_error says so, target_dir is nil and each file is
@@ -70,6 +73,8 @@ module Samagotchi
         end
         Report.new(provenance: bundle, scope: scope, scope_error: target_dir ? nil : "unknown scope: #{scope}",
                    target_dir: target_dir, files: details, plugin: plugin_status(provenance, bundle),
+                   rules: asset_states(provenance.guardrails_dir, :rule, bundle.guardrails),
+                   scripts: asset_states(provenance.scripts_dir, :script, bundle.scripts),
                    retired_hooks: retired_hooks(provenance, bundle), needs: needs_status(bundle))
       end
 
@@ -79,12 +84,26 @@ 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
+
+      # Each recorded rule or script: "missing" (not there), "modified" (its
+      # AssetState is edited: the next install replaces it, a copy kept in
+      # the trash; an edited rule doesn't load) or "ok"; {} for none.
+      # @return [Hash{String => String}]
+      def self.asset_states(dir, kind_of_file, recorded)
+        recorded.keys.sort.to_h do |name|
+          asset = AssetState.of(File.join(dir, name), kind_of_file: kind_of_file, recorded: recorded[name], name: name)
+          [name, if asset.state == :missing then "missing"
+                 elsif asset.edited? then "modified"
+                 else "ok"
+                 end]
         end
       end
 

data/lib/samagotchi/memory_bundle/uninstaller.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "digest"
 require_relative "../memory_paths"
 require_relative "provenance"
+require_relative "asset_state"
 require_relative "file_actions"
 require_relative "index_updater"
 require_relative "trash"
@@ -55,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
@@ -144,12 +147,17 @@ module Samagotchi
       private
 
       # Copies each edited file of the bundle's own folder to the trash: the
-      # rm_rf below takes them, --force or not.
+      # rm_rf below takes them, --force or not. Rules, the plugin and
+      # scripts by their source-less AssetState and ASSET_UNINSTALL's
+      # save_first; an older chi's hooks/ by Trash#copy_edits.
       def save_edits(provenance, bundle)
         @trash.copy_edits(provenance.hooks_dir, "hooks", bundle.hooks.transform_values(&:sha256))
-        @trash.copy_edits(provenance.guardrails_dir, "guardrails", bundle.guardrails)
-        @trash.copy_edits(provenance.plugin_dir, "plugin", bundle.plugin_shas)
-        @trash.copy_edits(provenance.scripts_dir, "scripts", bundle.scripts)
+        { rule: [provenance.guardrails_dir, bundle.guardrails], plugin: [provenance.plugin_dir, bundle.plugin_shas],
+          script: [provenance.scripts_dir, bundle.scripts] }.each do |kind_of_file, (dir, recorded)|
+          AssetState.in(dir, kind_of_file: kind_of_file, recorded: recorded).each do |asset|
+            @trash.copy(asset.path, as: asset.label) if FileActions.for_asset(:uninstall, asset)&.save_first
+          end
+        end
       end
 
       # A kept shared file's index line names the bundle that still has it

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