samagotchi 0.157.0 → 0.159.0

data/lib/samagotchi/memory_bundle/system_bundle.rb

@@ -214,7 +214,11 @@ module Samagotchi
         missing = MemoryFiles.select(GEM_BUNDLE_DIR, gem_manifest).reject { |key| File.exist?(File.join(target_dir, key)) }
         missing = restored_rows(missing, target_dir) unless missing.empty?
         return result(:up_to_date, from: version, to: version) if missing.empty?
-        return result(:restored, from: version, to: version) if dry_run
+
+        if dry_run
+          warnings = missing.filter_map { |key| restore_mismatch(key, gem_manifest) }
+          return result(:restored, from: version, to: version, warnings: warnings)
+        end
 
         warnings = missing.flat_map { |key| restore_file(key, gem_manifest) }
         result(:restored, from: version, to: version, warnings: warnings)
@@ -238,7 +242,7 @@ module Samagotchi
         description = gem_manifest.file_descriptions[key]
         FileUtils.cp(source, target)
         Provenance.new(name: BUNDLE_NAME).record_restored(key, source, description: description)
-        warnings = [FileDigest.mismatch(key, target, gem_manifest.checksum_for(key))].compact
+        warnings = [restore_mismatch(key, gem_manifest)].compact
         begin
           IndexUpdater.update_index(SCOPE, key.delete_suffix(".md"), File.size(target), description, source: BUNDLE_NAME)
         rescue StandardError => e
@@ -247,6 +251,10 @@ module Samagotchi
         warnings
       end
 
+      def restore_mismatch(key, gem_manifest)
+        FileDigest.mismatch(key, File.join(GEM_BUNDLE_DIR, key), gem_manifest.checksum_for(key))
+      end
+
       # An up-to-date bundle's marked files, retried. No marks: nothing is read.
       def remerge(bundle, verified, dry_run)
         done = Remerge.new(name: BUNDLE_NAME, scope: SCOPE, target_dir: MemoryPaths.system_dir, source_dir: GEM_BUNDLE_DIR, record: bundle)
@@ -264,7 +272,10 @@ module Samagotchi
         owned = provenance.record&.files&.keys || []
         forecast = Merger::Upgrade.new(provenance: provenance, target_dir: MemoryPaths.system_dir, source_dir: GEM_BUNDLE_DIR)
                                   .forecast(gem_manifest.files.keys.map(&:to_s).sort & owned, version: to)
-        result(:updated, from: from, to: to, merged: forecast.merged, behind: forecast.behind)
+        installer = upgrade_installer(dry_run: true)
+        installer.run
+        warnings = installer.warnings.grep(/\AChecksum mismatch/)
+        result(:updated, from: from, to: to, merged: forecast.merged, behind: forecast.behind, warnings: warnings)
       end
 
       # Provenance#adopt_manifest from the shipped dir, for a record without a
@@ -276,9 +287,9 @@ module Samagotchi
         Provenance.new(name: BUNDLE_NAME).adopt_manifest(GEM_BUNDLE_DIR)
       end
 
-      def upgrade_installer
+      def upgrade_installer(dry_run: false)
         Installer.new(source: GEM_BUNDLE_DIR, name: BUNDLE_NAME, scope: SCOPE, force: false, strict: true, upgrade: true,
-                      shipped_dir: File.dirname(GEM_BUNDLE_DIR))
+                      dry_run: dry_run, shipped_dir: File.dirname(GEM_BUNDLE_DIR))
       end
       private_class_method :with_lock, :note_newer_installed, :install_fresh, :keep_manifest, :upgrade_existing, :verify_files_present, :restore_file, :remerge,
                            :upgrade_installer, :result, :planned_update

data/lib/samagotchi/memory_bundle/trash.rb

@@ -99,24 +99,19 @@ module Samagotchi
         dest
       end
 
-      # Copies the file at +path+ as +as+ before it is replaced or removed, when
-      # that would lose something: its bytes are neither what the record says
-      # was installed (no sha recorded: unknown, so it counts as edited) nor
-      # +incoming+'s. A link (a dev install's) points at its source, which
-      # nothing here touches.
-      def copy_edit(path, as:, recorded: nil, incoming: nil)
-        copy(path, as: as) if self.class.edit?(path, recorded: recorded, incoming: incoming)
-      end
-
-      # copy_edit for every file under +dir+, which is about to go, at any depth
-      # (kept as <label>/<its path in dir>). A linked dir isn't followed.
+      # Copies every file under +dir+, which is about to be replaced or
+      # removed, when that would lose something: its bytes are neither what
+      # the record says was installed (no sha recorded: unknown, so it counts
+      # as edited) nor the incoming source's, at any depth (kept as
+      # <label>/<its path in dir>). A link (a dev install's) points at its
+      # source, which nothing here touches; a linked dir isn't followed.
       # @param recorded [Hash, nil] path in dir => its recorded sha256
       # @param incoming [Hash] path in dir => the source replacing it
       def copy_edits(dir, label, recorded = nil, incoming = {})
         self.class.edited_in(dir, recorded, incoming).each { |file| copy(File.join(dir, file), as: "#{label}/#{file}") }
       end
 
-      # Whether #copy_edit would copy the file at +path+ (read-only): the rule
+      # Whether #copy_edits would copy the file at +path+ (read-only): the rule
       # ShippedUpdate's plan names its replaced files by.
       def self.edit?(path, recorded: nil, incoming: nil)
         return false if File.symlink?(path) || !File.file?(path)

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"
@@ -144,12 +145,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

@@ -19,14 +19,14 @@ module Samagotchi
 
     module_function
 
-    # The orphan candidates for +cwd+'s project, or nil: only inside a git
-    # repository (outside one the root is cwd, and every src/ or tmp/ would
-    # match), and only while the computed folder holds no *.md (a
+    # The orphan candidates for +cwd+'s project, or nil: only inside a
+    # project, a git repository or a marked folder (outside both the root is
+    # cwd, and every src/ or tmp/ would match), and only while the computed folder holds no *.md (a
     # memory_write's mkdir_p or a project-scope bundle install alone must
     # not silence it).
     # @return [Found, nil]
     def find(env: ENV, cwd: Dir.pwd)
-      return nil unless MemoryPaths.in_repo?(cwd)
+      return nil unless MemoryPaths.in_project?(cwd)
 
       projects = MemoryPaths.projects_dir(env: env)
       computed = MemoryPaths.project_dir(env: env, cwd: cwd)

data/lib/samagotchi/memory_paths.rb

@@ -2,6 +2,7 @@
 
 require "digest"
 require_relative "config"
+require_relative "guardrails/path_resolve"
 
 module Samagotchi
   # Where memories live: <config dir>/memories, i.e. $XDG_CONFIG_HOME/samagotchi/memories
@@ -9,11 +10,61 @@ module Samagotchi
   # ConfigFile.global_path, so an XDG_CONFIG_HOME set after load (specs, smoke runs,
   # a fixture chi) moves memories together with config.yml.
   #
-  # Project memories are keyed by the project root (see project_root), so every
-  # worktree and subdirectory of one git repository shares one folder.
+  # Project memories are keyed by the project root (see #lookup): one folder
+  # per project root, a git repository (every worktree and subdirectory of it
+  # shares one folder) or a folder marked by `chi project init` (and its
+  # subfolders).
   module MemoryPaths
+    # The file that makes a folder in no git repository a chi project
+    # (`chi project init`). The file, not the bare .chi/ dir, is the marker.
+    MARKER = File.join(".chi", "project.yml").freeze
+
+    # How a folder's project was found (#lookup): +kind+ is :git, :marker or
+    # :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
+      def project? = kind != :none
+      def git? = kind == :git
+      def marker? = kind == :marker
+    end
+
     module_function
 
+    # The project +cwd+ belongs to, looked up once: a .git above it wins
+    # (git is the identity wherever it exists); only when there is none, the
+    # nearest MARKER above it, ignoring one in $HOME or any folder above it
+    # (and /), so a marker in ~ never makes every folder under home one
+    # project. The marker walk starts from +cwd+'s real path and the marked
+    # root is a realpath, as git's root is, so every spelling of a folder
+    # (/tmp, /var on macOS, a symlink into or out of a marked tree) gets the
+    # answer the worker's physical Dir.pwd gets.
+    # @param home [String, nil] $HOME by default; nil or blank ignores only /
+    # @return [ProjectLookup]
+    def lookup(cwd = Dir.pwd, home: default_home)
+      dot_git = find_dot_git(cwd)
+      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
+
+      ProjectLookup.new(kind: :none, root: cwd, top: nil)
+    end
+
+    # Whether a marker at +dir+ is ignored: +dir+ is / or holds $HOME (both
+    # resolved; Guardrails::PathResolve.home_root?).
+    def above_home?(dir, home: default_home)
+      Guardrails::PathResolve.real(dir) == "/" || Guardrails::PathResolve.home_root?(dir, home)
+    end
+
+    # $HOME, or nil when it can't be found (no HOME, no passwd entry).
+    def default_home
+      Dir.home
+    rescue ArgumentError
+      nil
+    end
+
     def system_dir(env: ENV)
       File.join(ConfigFile.config_dir(env: env), "memories")
     end
@@ -28,16 +79,31 @@ module Samagotchi
     # #project_key for a root already resolved (a session's project_root).
     def key_for_root(root) = "#{File.basename(root)}_#{Digest::MD5.hexdigest(root)[0..7]}"
 
-    # The repository's 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 (a bare repo, a proj/.bare layout,
-    # --separate-git-dir, a submodule's .git/modules/<name>), so for those layouts
-    # the "project root" is a git dir, not a checkout. Outside any repository the
-    # root is cwd. No git subprocess: at most two small files are read.
-    def project_root(cwd = Dir.pwd)
-      dot_git = find_dot_git(cwd)
-      return cwd unless dot_git
+    # 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
+    # (a bare repo, a proj/.bare layout, --separate-git-dir, a submodule's
+    # .git/modules/<name>), so for those layouts the "project root" is a git
+    # dir, not a checkout. Outside any repository, the marked folder holding
+    # +cwd+, else cwd. No git subprocess: at most two small files are read.
+    def project_root(cwd = Dir.pwd) = lookup(cwd).root
+
+    # Is +cwd+ in a project: a git repository or a marked folder?
+    def in_project?(cwd = Dir.pwd) = lookup(cwd).project?
+
+    # The marked folder (realpath) +cwd+'s project is, or nil (in a git
+    # repository, or in no project).
+    def marked_root(cwd = Dir.pwd)
+      found = lookup(cwd)
+      found.marker? ? found.root : nil
+    end
+
+    # The top of +cwd+'s project: the git work tree's top (#work_tree_root) or
+    # the marked root; nil in no project.
+    def project_top(cwd = Dir.pwd) = lookup(cwd).top
 
+    # The project root of the checkout whose .git is +dot_git+ (#project_root).
+    def git_root(dot_git)
       holder = File.dirname(dot_git)
       gitdir = File.directory?(dot_git) ? dot_git : gitdir_from_file(dot_git)
       return holder unless gitdir
@@ -78,7 +144,8 @@ module Samagotchi
       File.directory?(dot_git) ? dot_git : gitdir_from_file(dot_git)
     end
 
-    # Is +cwd+ inside a git repository (a .git somewhere above it)?
+    # Is +cwd+ inside a git repository (a .git somewhere above it)? Git only:
+    # a marked folder is not a repository (#in_project?).
     def in_repo?(cwd = Dir.pwd)
       !find_dot_git(cwd).nil?
     end
@@ -96,6 +163,28 @@ module Samagotchi
       end
     end
 
+    # The realpath of the nearest folder at or above +start+ holding MARKER,
+    # git or not (#lookup asks only outside a repository; `chi project` tells
+    # of one a repository makes ignored), or nil. A marker at or above +home+
+    # (#above_home?) ends the walk with nil: every folder above it is above
+    # home too.
+    def nearest_marker(start, home: default_home)
+      dir = Guardrails::PathResolve.real(start)
+      loop do
+        if File.file?(File.join(dir, MARKER))
+          return nil if above_home?(dir, home: home)
+
+          return File.realpath(dir)
+        end
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+    rescue SystemCallError
+      nil
+    end
+
     # A ".git" file holds "gitdir: <path>", relative to the file's directory.
     def gitdir_from_file(path)
       line = File.read(path, 4096).to_s[/\Agitdir:\s*(.+)$/, 1]&.strip
@@ -115,7 +204,7 @@ module Samagotchi
     rescue SystemCallError
       gitdir
     end
-    private_class_method :find_dot_git, :gitdir_from_file, :common_dir
+    private_class_method :find_dot_git, :git_root, :gitdir_from_file, :common_dir
 
     def project_dir(env: ENV, cwd: Dir.pwd)
       File.join(projects_dir(env: env), project_key(cwd))

data/lib/samagotchi/plugin/api.rb

@@ -32,10 +32,7 @@ module Samagotchi
       # plugin writes it (ApiCalls#keywords: `ctx.sessions.send(…,
       # delivery:)` is seen, a `sessions = ctx.sessions` alias isn't).
       # Events aren't listed: chi.on takes any symbol and an older chi never
-      # fires one it doesn't know (harmless; chi bundle check warns on it),
-      # and a manifest hook's events: list (BundleHook) needs the bundle's
-      # requires_chi set by hand (docs/hooks.md, Bundle Hooks): no source
-      # scan covers manifest.yml.
+      # fires one it doesn't know (harmless; chi bundle check warns on it).
       SINCE = {
         "ctx.steer" => "0.3.0", "ctx.stop_turn" => "0.3.0", "ctx.stop_generation" => "0.6.0",
         "Samagotchi::AtomicFile" => "0.8.0", "ctx.model" => "0.17.0", "ctx.model_key" => "0.17.0",

data/lib/samagotchi/plugin/loader.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "digest"
 require_relative "api"
 require_relative "context"
 require_relative "../hooks"
@@ -10,6 +11,11 @@ require_relative "../memory_bundle/manifest"
 require_relative "../memory_bundle/provenance"
 
 module Samagotchi
+  # Where installed bundles' plugin code is evaluated: one module per
+  # bundle (Plugin::Loader.namespace_for), so two bundles defining the same
+  # class name can't collide on a top-level constant.
+  module Bundles; end
+
   module Plugin
     # What a plugin registers into: an Engine's own registries.
     # +context_for+ is (bundle_name, settings, label) → the Plugin::Context
@@ -36,7 +42,7 @@ module Samagotchi
     #
     # For each bundle, by name: the file must match the sha256 recorded at
     # install and chi must meet the bundle's requires_chi. The file is
-    # module_eval'd into the bundle's namespace (as its hooks are), the
+    # module_eval'd into the bundle's namespace (#namespace_for), the
     # class named like the file (plugin.rb → Plugin) is built with the
     # bundle's settings, and its #register gets a Plugin::Api. What it
     # registered takes effect only when #register returns: a plugin that
@@ -140,14 +146,45 @@ module Samagotchi
         return failure if failure
         return "the file is missing" unless file && File.file?(file)
 
-        Hooks::BundleLoader.sha_mismatch(file, bundle.plugin.sha256, required: true)
+        sha_mismatch(file, bundle.plugin.sha256)
+      end
+
+      # Why +file+ doesn't match the sha256 recorded at install (+recorded+,
+      # "sha256:<hex>" or bare hex), or nil. None recorded is a mismatch;
+      # Provenance.unchecked? (a dev install) is none.
+      def sha_mismatch(file, recorded)
+        return nil if MemoryBundle::Provenance.unchecked?(recorded)
+
+        expected = MemoryBundle::Provenance.recorded_sha(recorded)
+        return "no sha256 recorded for it (reinstall the bundle)" if expected.empty?
+
+        actual = MemoryBundle::Provenance.file_sha(file)
+        return nil if actual == expected
+
+        "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
+      end
+
+      # The (lazily created) namespace module for a bundle, under
+      # Samagotchi::Bundles. The name is sanitized and made injective by a
+      # short digest, so `my-bundle` and `my_bundle` don't collide.
+      def namespace_for(bundle_name)
+        raw = bundle_name.to_s
+        base = raw.gsub(/[^A-Za-z0-9_]/, "_")
+        base = "B_#{base}" unless base.match?(/\A[A-Z]/)
+        ns_name = :"#{base}_#{Digest::MD5.hexdigest(raw)[0, 4]}"
+        if Samagotchi::Bundles.const_defined?(ns_name, false)
+          Samagotchi::Bundles.const_get(ns_name)
+        else
+          Samagotchi::Bundles.const_set(ns_name, Module.new)
+        end
       end
 
       # module_eval the file into a fresh module in the bundle's namespace
       # (Samagotchi::Bundles::<bundle>::PluginLoad<n>: each load gets new
       # classes, not the last load's reopened) and build its class
-      # (plugin.rb → Plugin; my_plugin.rb → MyPlugin) as hooks are built:
-      # an initialize that takes an argument gets the settings.
+      # (plugin.rb → Plugin; my_plugin.rb → MyPlugin) as config hooks are
+      # built (Hooks.build_plugin): an initialize that takes an argument
+      # gets the settings.
       def instantiate(bundle_name, file, settings, namespace: nil)
         namespace ||= fresh_namespace(bundle_name)
         namespace.module_eval(File.read(file), file, 1)
@@ -163,7 +200,7 @@ module Samagotchi
       def fresh_namespace(bundle_name)
         LOADS.synchronize do
           @loads = (@loads || 0) + 1
-          Hooks::BundleLoader.namespace_for(bundle_name).const_set(:"PluginLoad#{@loads}", Module.new)
+          namespace_for(bundle_name).const_set(:"PluginLoad#{@loads}", Module.new)
         end
       end
 

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