samagotchi 0.5.1 → 0.7.0

data/bin/chi

@@ -21,878 +21,42 @@ require "samagotchi"
 # bundles (read-only, offline) — lets the agent find its own code and state.
 if ARGV[0] == "self"
   if %w[-h --help help].include?(ARGV[1])
-    puts "Usage: chi self"
+    puts "Usage: chi self [--model]"
     puts "  Print version, source dir, config/memory/session paths, model/host and bundles."
+    puts "  --model  print only the model a new session starts on (exit 1 when none is configured)"
     exit 0
   end
   require "samagotchi/self_report"
+  # The desktop helper's hint for its "New session" row: offline and quick.
+  if ARGV[1] == "--model"
+    model = Samagotchi::SelfReport.model_name
+    puts model if model
+    exit(model ? 0 : 1)
+  end
   puts Samagotchi::SelfReport.text
   exit 0
 end
 
-# Early handle `sessions` subcommand before OptionParser (has its own flags like --dry-run)
-if ARGV[0] == "sessions"
-  require "samagotchi/session"
-  require "samagotchi/session_manager"
-  require "samagotchi/project_scope"
-  sessions_args = ARGV[1..] || []
-  sub = sessions_args[0]
-  if sub.nil? || %w[-h --help help].include?(sub)
-    puts "Usage: chi sessions <list|stop|archive|unarchive|delete|prune|clean> [options]"
-    puts "  list [--sort updated_at|created_at] [--order desc|asc] [--limit N]"
-    puts "       [--live] [--cwd PATH] [--format text|json|tsv] [--archived]"
-    puts "       --live: sessions a worker runs now (the ones chi note reaches), 10 unless --limit"
-    puts "       --cwd PATH: sessions in PATH or below; json/tsv (id<TAB>description) are for scripts"
-    puts "       [--scope=all]: every project's sessions; by default only this git project's (all outside a repo)"
-    puts "       --archived: archived sessions too (marked [archived]; json: archived: true)"
-    puts "  stop ID...   # stop each session's worker (IDs or unique prefixes); chi --resume ID then starts a fresh one"
-    puts "  archive ID...   # hide sessions (and their delegates) from every list and keep them for good; unarchive ID... brings them back"
-    puts "  delete [--force] ID...   # delete sessions for good (IDs or unique prefixes); --force stops a live worker first"
-    puts "  prune [--dry-run] [--days N] [--keep N] [--keep-status running,...] [--test-only]"
-    puts "  clean [--dry-run] [--days N]   # test sessions (SAMAGOTCHI_ENV=test, CI) and leftover chi scratch ones: all of them, or those older than N days"
-    puts "Defaults: days=14 keep=500 keep_status=none (config: session.retention_days, session.max_count, session.keep_status)"
-    exit 0
-  end
-  dry_run = sessions_args.include?("--dry-run")
-  test_only = sessions_args.include?("--test-only") || sessions_args.include?("--test")
-  days = nil
-  keep = nil
-  keep_status = nil
-  sort = nil
-  order = nil
-  limit = nil
-  live = sessions_args.include?("--live")
-  include_archived = sessions_args.include?("--archived")
-  cwd = nil
-  format = nil
-  scope = nil
-  sessions_args.each_with_index do |arg, i|
-    nxt = sessions_args[i+1]
-    if arg == "--days" && nxt then days = nxt.to_i
-    elsif arg.start_with?("--days=") then days = arg.split("=",2).last.to_i
-    elsif arg == "--keep" && nxt then keep = nxt.to_i
-    elsif arg.start_with?("--keep=") then keep = arg.split("=",2).last.to_i
-    elsif arg == "--keep-status" && nxt then keep_status = nxt
-    elsif arg.start_with?("--keep-status=") then keep_status = arg.split("=",2).last
-    elsif arg == "--sort" && nxt then sort = nxt
-    elsif arg.start_with?("--sort=") then sort = arg.split("=",2).last
-    elsif arg == "--order" && nxt then order = nxt
-    elsif arg.start_with?("--order=") then order = arg.split("=",2).last
-    elsif arg == "--limit" && nxt then limit = nxt.to_i
-    elsif arg.start_with?("--limit=") then limit = arg.split("=",2).last.to_i
-    elsif arg == "--cwd" && nxt then cwd = nxt
-    elsif arg.start_with?("--cwd=") then cwd = arg.split("=",2).last
-    elsif arg == "--format" && nxt then format = nxt
-    elsif arg.start_with?("--format=") then format = arg.split("=",2).last
-    elsif arg == "--scope" && nxt then scope = nxt
-    elsif arg.start_with?("--scope=") then scope = arg.split("=",2).last
-    end
-  end
-  case sub
-  when "delete"
-    require "samagotchi/session_delete_command"
-    exit Samagotchi::SessionDeleteCommand.new(sessions_args[1..]).run
-  when "archive", "unarchive"
-    require "samagotchi/session_archive_command"
-    exit Samagotchi::SessionArchiveCommand.new(sub, sessions_args[1..]).run
-  when "list"
-    unless format.nil? || %w[text json tsv].include?(format)
-      warn "Unknown format #{format.inspect}: use --format text|json|tsv"
-      exit 1
-    end
-    unless scope.nil? || %w[project all].include?(scope)
-      warn "Unknown scope #{scope.inspect}: use --scope=project|all"
-      exit 1
-    end
-    # The current git project's sessions (Samagotchi::ProjectScope), like
-    # chi web's; --scope=all, a folder in no repo or an explicit --cwd: every
-    # project's.
-    project = scope == "all" || cwd ? nil : Samagotchi::ProjectScope.root_for(Dir.pwd)
-    scope_note = ->(count) { "#{count} session(s) in #{File.basename(project)} (--scope=all: every project)" }
-    # The picker (chi note from a script): filters apply before the limit,
-    # and test runs stay out, unless this is one (SAMAGOTCHI_ENV=test, CI):
-    # then its own sessions are what it looks for.
-    if live || cwd || (format && format != "text")
-      summaries = Samagotchi::SessionManager.session_summaries(
-        live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: Samagotchi::Session.test_session_env?,
-        project_root: project,
-        include_archived: include_archived
-      )
-      case format
-      when "json"
-        # owner: "worker", "tui" (a chi REPL: it takes no notes or messages)
-        # or nil; recap: the saved recap's first sentence, or nil; project:
-        # its git project's root, or nil
-        # parent_id: the session that delegated it (the delegate tool), or nil
-        # archived: hidden from the lists (only with --archived can it be true)
-        # scratch: a `chi scratch` session (deleted when its REPL ends, a
-        # leftover one at the next sweep)
-        # ctx_pct: how full the context was after the last turn, or nil
-        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id archived scratch ctx_pct]
-        puts JSON.generate(summaries.map { |summary| summary.slice(*keys) })
-      when "tsv"
-        summaries.each { |summary| puts "#{summary[:id]}\t#{summary[:desc]}" }
-      else
-        summaries.each do |summary|
-          state = summary[:busy] ? "running" : (summary[:live] ? "live" : summary[:status].to_s)
-          # The saved recap's first sentence says more than the last prompt
-          # (text only: tsv and json keep desc for pickers).
-          desc = summary[:desc]
-          if summary[:recap]
-            desc = [File.basename(summary[:cwd].to_s), summary[:recap]].reject(&:empty?).join(" · ")
-            desc = "#{desc[0, 59]}…" if desc.length > 60
-          end
-          # A delegated session points at its parent.
-          child = summary[:parent_short_id] ? "  ↳ #{summary[:parent_short_id]}" : ""
-          flag = summary[:scratch] ? " [scratch]" : (summary[:test_run] ? " [test]" : "")
-          flag += " [archived]" if summary[:archived]
-          ctx = Samagotchi::SessionMetrics.context_label(summary[:ctx_pct])
-          puts "#{summary[:id]}  #{state.ljust(8)}  #{ctx.ljust(8)}  #{summary[:updated_at]}  #{desc}#{flag}#{child}"
-        end
-        if project
-          puts "#{summaries.empty? ? "" : "\n"}#{scope_note.call(summaries.size)}"
-        else
-          puts summaries.empty? ? "No sessions." : "\n#{summaries.size} session(s)"
-        end
-      end
-      exit 0
-    end
-    sort ||= "updated_at"
-    order ||= "desc"
-    sessions = Samagotchi::SessionManager.list_sessions(sort: sort, order: order, limit: limit, project_root: project,
-                                                        include_archived: include_archived)
-    # The saved recap's first sentence, else the last prompt, cut as before.
-    state_dir = Samagotchi::Session.default_state_dir
-    list_text = lambda do |s|
-      recap = Samagotchi::RecapStore.preview(Samagotchi::Session.session_dir(s.id, state_dir: state_dir))
-      (recap || Samagotchi::SessionManager.one_line(s.last_prompt))[0, 60]
-    end
-    # A delegated session points at its parent: ↳ <parent's short id>.
-    row = lambda do |s|
-      flag = s.scratch ? " [scratch]" : (s.test_run ? " [test]" : "")
-      flag += " [archived]" if s.archived
-      child = s.parent_id ? "  ↳ #{s.parent_id[0, 8]}" : ""
-      # How full the context was after the last turn: "ctx 12%", blank when unknown.
-      ctx = Samagotchi::SessionMetrics.context_label(
-        Samagotchi::SessionMetrics.saved_context_pct(Samagotchi::Session.session_dir(s.id, state_dir: state_dir))
-      )
-      "#{s.id}  #{s.status.ljust(8)}  #{ctx.ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
-    end
-    if project
-      sessions.each { |s| puts row.call(s) }
-      puts "#{sessions.empty? ? "" : "\n"}#{scope_note.call(sessions.size)}"
-    elsif sessions.empty?
-      puts "No sessions."
-    else
-      sessions.each { |s| puts row.call(s) }
-      puts "\n#{sessions.size} session(s) (sort=#{sort} order=#{order})"
-    end
-    exit 0
-  when "stop"
-    ids = sessions_args[1..]
-    if ids.empty? || ids.any? { |arg| arg.start_with?("-") }
-      warn "Usage: chi sessions stop ID..."
-      exit 1
-    end
-    # Each id in turn, like chi sessions delete: stdout is flushed before an
-    # error line, so the output keeps the order of the ids given.
-    ok = ids.uniq.map do |given|
-      begin
-        id = Samagotchi::Session.resolve_id(given)
-        released = Samagotchi::SessionManager.stop_session(id, wait: 10)
-      rescue Samagotchi::SessionManager::OwnedByTUI
-        $stdout.flush
-        warn "session #{id} is open in a chi REPL; close it there first"
-        next false
-      rescue ArgumentError => e
-        $stdout.flush
-        warn e.message
-        next false
-      end
-      if released
-        puts "Stopped session #{id}. chi --resume #{id} starts a fresh worker."
-      else
-        $stdout.flush
-        warn "Stopped session #{id}, but its worker is still shutting down; try chi --resume #{id} in a moment."
-      end
-      true
-    end
-    exit(ok.all? ? 0 : 1)
-  when "prune", "clean"
-    test_only = true if sub == "clean" && !sessions_args.include?("--all")
-    # Test sessions are throwaway: clean takes them whatever their age,
-    # unless --days asks for the older ones only. Live workers and
-    # keep_status still protect a session.
-    any_age = sub == "clean" && test_only && days.nil?
-    result = Samagotchi::SessionManager.prune_sessions(days: days, max_count: keep, keep_status: keep_status, dry_run: dry_run,
-                                                       test_only: test_only, any_age: any_age)
-    mode = dry_run ? "Would delete" : "Deleted"
-    puts "#{mode} #{result[:deleted].size} sessions (kept #{result[:kept].size}, skipped #{result[:skipped].size})"
-    if result[:deleted].any?
-      result[:deleted].each { |id| puts "  #{id}" }
-    end
-    if dry_run && result[:deleted].any?
-      puts "\nRun without --dry-run to delete."
-    end
-    exit 0
-  else
-    warn "Unknown sessions subcommand: #{sub}. Use: list, stop, archive, unarchive, delete, prune, clean"
-    exit 1
-  end
-end
-
-# `chi note`: a context note for sessions, before OptionParser (-m, --source, --all are its own)
-if ARGV[0] == "note"
-  require "samagotchi/note_command"
-  exit Samagotchi::NoteCommand.new(ARGV[1..] || []).run
-end
-
-# `chi send`: a message into sessions as the user's, before OptionParser (-m is its own)
-if ARGV[0] == "send"
-  require "samagotchi/send_command"
-  exit Samagotchi::SendCommand.new(ARGV[1..] || []).run
-end
-
-# `chi bootstrap`: find a model server and write config.yml, before OptionParser (--model, --name are its own)
-if ARGV[0] == "bootstrap"
-  require "samagotchi/bootstrap_command"
-  exit Samagotchi::BootstrapCommand.new(ARGV[1..] || []).run
-end
-
-# `chi update`: bring an installed chi up to date, before OptionParser (its own flags)
-if ARGV[0] == "update"
-  require "samagotchi/update_command"
-  exit Samagotchi::UpdateCommand.new(ARGV[1..] || []).run
-end
-
-# `chi desktop`: the native "Send to chi" helper, before OptionParser (its own flags)
-if ARGV[0] == "desktop"
-  require "samagotchi/desktop_command"
-  exit Samagotchi::DesktopCommand.new(ARGV[1..] || []).run
-end
-
-# Handle `bundle` subcommand before OptionParser (has its own flags like --scope, --force)
-if ARGV[0] == "bundle"
-  require "samagotchi/memory_bundle"
-  bundle_args = ARGV[1..] || []
-  sub = bundle_args[0]
-  if sub.nil? || %w[-h --help help].include?(sub)
-    puts "Usage: chi bundle <install|upgrade|uninstall|status|diff|list|build> [options]"
-    puts ""
-    puts "  install <source> [--scope system|project] [--force]"
-    puts "    Install a memory bundle from a directory, zip, tar archive, or git URL."
-    puts "    Source is the path/URL to the bundle (dir/zip/tar.gz/git)."
-    puts "    --force overwrites existing entries; default skips them."
-    puts ""
-    puts "  upgrade <source> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]"
-    puts "    Upgrade a bundle (3-way merge: auto-merge if not edited, conflict otherwise)."
-    puts "    --dry-run shows what would change. --agent launches interactive session on conflict."
-    puts ""
-    puts "  uninstall <bundle> [--scope system|project] [--force]"
-    puts "    Remove a bundle and its index entries (--force if locally edited)."
-    puts ""
-    puts "  status [<bundle>]"
-    puts "    Show provenance + modification status for bundles."
-    puts ""
-    puts "  diff <bundle> [file]"
-    puts "    Show diffs between base/current/incoming for a bundle."
-    puts ""
-    puts "  list"
-    puts "    List installed bundles and the ones shipped with chi that aren't installed."
-    puts ""
-    puts "  build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]"
-    puts "    Build local memories and installed hooks (and plugin) into a shareable bundle (dir or zip)."
-    puts "    --scope selects source dir (default: system). --out inferred from extension; default <name>.zip."
-    puts "    FILES... optional allowlist of *.md basenames to include (default: all)."
-    exit 0
-  end
-
-  # helpers for bundle_name derivation
-  def chi_expand_source(src)
-    return src if Samagotchi::MemoryBundle::SourceNormalizer.git_url?(src)
-    Samagotchi::MemoryBundle::SourceNormalizer.shipped_bundle_dir(src) || File.expand_path(src)
-  end
-
-  def chi_bundle_name_for(expanded_src)
-    # Try to derive from manifest if possible (skip git clone for speed if possible)
-    if Samagotchi::MemoryBundle::SourceNormalizer.git_url?(expanded_src)
-      # For git URLs, avoid double clone: derive name from URL basename if no manifest yet
-      # Let Installer do the real manifest read; fallback to URL basename
-      base = expanded_src.split("/").last.to_s.split("#").first.to_s
-      base = base.sub(/\.git\z/i, "")
-      return base.empty? ? "bundle" : base
-    end
-    require "yaml"
-    nd = nil
-    owned = false
-    begin
-      nd, owned = Samagotchi::MemoryBundle::SourceNormalizer.normalize(expanded_src)
-      m = Samagotchi::MemoryBundle::Manifest.read(dir: nd)
-      return m.name
-    rescue Samagotchi::MemoryBundle::Manifest::ValidationError
-      # Fallback to source basename without archive extensions
-      src = expanded_src
-      name = File.basename(src)
-      name = name.sub(/\.tar\.gz\z/i, "").sub(/\.tgz\z/i, "").sub(/\.zip\z/i, "").sub(/\.tar\z/i, "")
-      return name.empty? ? File.basename(nd || src) : name
-    ensure
-      Samagotchi::MemoryBundle::SourceNormalizer.cleanup(nd) if owned
-    end
-  end
-
-  def chi_build_conflict_prompt(bundle_name, conflicts, expanded_source)
-    lines = []
-    lines << "Memory bundle upgrade has conflicts that need interactive resolution."
-    lines << "Bundle: #{bundle_name}"
-    lines << "Source: #{expanded_source}"
-    lines << "Conflicts (#{conflicts.size} file(s)):"
-    conflicts.each do |file_key, info|
-      lines << "  - #{file_key}"
-      lines << "    base:     #{info[:base]} (provenance snapshot)"
-      lines << "    current:  #{info[:current]} (on-disk, has local edits)"
-      lines << "    incoming: #{info[:incoming]} (new bundle version)"
-      begin
-        if File.exist?(info[:current]) && File.exist?(info[:incoming])
-          base_content = File.exist?(info[:base]) ? File.read(info[:base]) : ""
-          cur = File.read(info[:current])
-          inc = File.read(info[:incoming])
-          lines << "    --- current vs incoming preview ---"
-          # simple line diff preview (first 40 lines)
-          cur_lines = cur.lines
-          inc_lines = inc.lines
-          max = [cur_lines.size, inc_lines.size].max
-          preview = []
-          max.times do |i|
-            break if preview.size >= 30
-            c = cur_lines[i]
-            n = inc_lines[i]
-            if c != n
-              preview << "- #{c.chomp}" if c
-              preview << "+ #{n.chomp}" if n
-            end
-          end
-          lines.concat(preview)
-          lines << "    --- end preview ---"
-        end
-      rescue => _e
-      end
-    end
-    lines << ""
-    lines << "Your task: resolve each conflict by editing the file in place using the memory_write tool."
-    lines << "Use memory_read to inspect current content if needed. The correct scope for memory_write is the bundle's scope."
-    lines << "When all conflicts are resolved, type /exit to finish. If you stop early, the files stay as they are (the rest of the upgrade is already applied)."
-    lines.join("\n")
-  end
-
-  case sub
-  when "install"
-    rest = bundle_args[1..]
-    source = nil
-    scope = nil
-    force = false
-    i = 0
-    while i < rest.size
-      arg = rest[i]
-      if arg.start_with?("--")
-        nxt = rest[i + 1]
-        if %w[-h --help help].include?(arg)
-          puts "Usage: chi bundle install <source> [--scope system|project] [--force]"
-          puts ""
-          puts "  install <source> [--scope system|project] [--force]"
-          puts "    Install a memory bundle from a directory, zip, tar archive, or git URL,"
-          puts "    or a bundle shipped with chi by name (see: chi bundle list)."
-          puts "    --force overwrites existing entries; default skips them."
-          exit 0
-        elsif arg == "--scope" && nxt
-          scope = nxt
-          i += 2
-        elsif arg.start_with?("--scope=")
-          scope = arg.split("=", 2).last
-          i += 1
-        elsif arg == "--force"
-          force = true
-          i += 1
-        else
-          warn "Unknown bundle install flag: #{arg}"
-          exit 1
-        end
-      else
-        source = arg
-        i += 1
-      end
-    end
-    if source.nil? || source.empty?
-          warn "Usage: chi bundle install <source> [--scope system|project] [--force]"
-      exit 1
-    end
-    expanded_source = chi_expand_source(source)
-    bundle_name = chi_bundle_name_for(expanded_source)
-    installer = Samagotchi::MemoryBundle::Installer.new(
-      source: expanded_source,
-      name: bundle_name,
-      scope: scope,
-      force: force,
-      strict: true
-    )
-    begin
-      _nd, manifest = installer.run
-      puts installer.summary
-      if manifest && manifest.hooks && !manifest.hooks.empty?
-        hook_cnt = manifest.hooks.size
-        puts "Hooks: #{hook_cnt} hook(s) (#{manifest.hooks.keys.join(', ')})"
-      end
-      puts "Plugin: #{manifest.plugin[:file]} (loads at the next chi start)" if manifest&.plugin
-      puts "Provenance written to: #{Samagotchi::MemoryBundle::Provenance.bundles_dir}/#{bundle_name}/" if manifest
-      exit 0
-    rescue Samagotchi::MemoryBundle::Installer::InstallError => e
-      warn "Install failed: #{e.message}"
-      exit 1
-    end
-
-  when "upgrade"
-    rest = bundle_args[1..]
-    source = nil
-    scope = nil
-    force = false
-    dry_run = false
-    agent = nil
-    i = 0
-    while i < rest.size
-      arg = rest[i]
-      if arg.start_with?("--")
-        nxt = rest[i + 1]
-        if %w[-h --help help].include?(arg)
-          puts "Usage: chi bundle upgrade <source> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]"
-          exit 0
-        elsif arg == "--scope" && nxt
-          scope = nxt; i += 2
-        elsif arg.start_with?("--scope=")
-          scope = arg.split("=", 2).last; i += 1
-        elsif arg == "--force"
-          force = true; i += 1
-        elsif arg == "--dry-run"
-          dry_run = true; i += 1
-        elsif arg == "--agent"
-          agent = true; i += 1
-        elsif arg == "--no-agent"
-          agent = false; i += 1
-        else
-          warn "Unknown bundle upgrade flag: #{arg}"
-          exit 1
-        end
-      else
-        source = arg; i += 1
-      end
-    end
-    if source.nil? || source.empty?
-          warn "Usage: chi bundle upgrade <source> [--scope system|project] [--force] [--dry-run]"
-      exit 1
-    end
-    expanded_source = chi_expand_source(source)
-    bundle_name = chi_bundle_name_for(expanded_source)
-    provenance = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name)
-    unless provenance.installed?
-      warn "Bundle '#{bundle_name}' not installed — falling back to install"
-      installer = Samagotchi::MemoryBundle::Installer.new(source: expanded_source, name: bundle_name, scope: scope, force: force, strict: true)
-      begin
-        _nd, manifest = installer.run
-        puts installer.summary
-        puts "Provenance written to: #{Samagotchi::MemoryBundle::Provenance.bundles_dir}/#{bundle_name}/" if manifest
-        exit 0
-      rescue Samagotchi::MemoryBundle::Installer::InstallError => e
-        warn "Install failed: #{e.message}"; exit 1
-      end
-    end
-    installer = Samagotchi::MemoryBundle::Installer.new(
-      source: expanded_source,
-      name: bundle_name,
-      scope: scope,
-      force: force,
-      strict: true,
-      upgrade: true,
-      dry_run: dry_run
-    )
-    begin
-      _nd, manifest = installer.run
-      puts installer.summary
-      if manifest && manifest.hooks && !manifest.hooks.empty?
-        puts "Hooks: #{manifest.hooks.size} hook(s) (#{manifest.hooks.keys.join(', ')})"
-      end
-      puts "Plugin: #{manifest.plugin[:file]} (loads at the next chi start)" if manifest&.plugin && !dry_run
-      if dry_run
-        puts "(dry-run: no changes written)" 
-        exit 0
-      end
-      if installer.conflicts.any? && !force
-        puts "\n#{installer.conflicts.size} conflict(s) need resolution."
-        installer.conflicts.each { |k, _| puts "  conflict: #{k}" }
-        # Decide whether to launch agent
-        launch = false
-        if agent == false
-          launch = false
-        elsif agent == true
-          launch = true
-        elsif STDIN.tty?
-          print "Conflicts detected — launch interactive agent to resolve? [y/N] "
-          ans = begin; $stdin.gets; rescue => _e; nil; end
-          launch = ans && ans.strip.downcase.start_with?("y")
-        else
-          puts "Non-interactive terminal: kept your edits in the file(s) above; the rest is upgraded. Re-run with --force to take the bundle's version, or --agent in a TTY to merge."
-          exit 2
-        end
-        if launch
-          prompt = chi_build_conflict_prompt(bundle_name, installer.conflicts, expanded_source)
-          puts "Launching interactive session for conflict resolution… (/exit when done)"
-          require "samagotchi/terminal_ui"
-          Samagotchi::TerminalUI.new(prompt: prompt).run
-          # The installer already recorded the upgrade (conflicted files
-          # kept their old base); the resolved files now start from the
-          # bundle's version.
-          Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).resolve_conflicts(installer.conflicts)
-          puts "Provenance updated after interactive resolution."
-          puts "Upgrade resolved interactively."
-          exit 0
-        else
-          puts "Kept your edits in the file(s) above; the rest is upgraded. chi bundle diff #{bundle_name} FILE shows the base; re-run with --force to take the bundle's version."
-          exit 2
-        end
-      end
-      puts "Provenance written to: #{Samagotchi::MemoryBundle::Provenance.bundles_dir}/#{bundle_name}/" if manifest
-      exit 0
-    rescue Samagotchi::MemoryBundle::Installer::InstallError => e
-      warn "Upgrade failed: #{e.message}"; exit 1
-    end
-
-  when "uninstall"
-    rest = bundle_args[1..]
-    bundle_name = nil
-    scope = nil
-    force = false
-    i = 0
-    while i < rest.size
-      arg = rest[i]
-      if arg.start_with?("--")
-        nxt = rest[i + 1]
-        if %w[-h --help help].include?(arg)
-          puts "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
-          exit 0
-        elsif arg == "--scope" && nxt
-          scope = nxt; i += 2
-        elsif arg.start_with?("--scope=")
-          scope = arg.split("=", 2).last; i += 1
-        elsif arg == "--force"
-          force = true; i += 1
-        else
-          warn "Unknown bundle uninstall flag: #{arg}"; exit 1
-        end
-      else
-        bundle_name = arg; i += 1
-      end
-    end
-    if bundle_name.nil? || bundle_name.empty?
-          warn "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
-      exit 1
-    end
-    # Propagate overrides
-    Samagotchi::MemoryBundle::Uninstaller.system_dir_override = Samagotchi::MemoryBundle::Installer.system_dir_override
-    Samagotchi::MemoryBundle::Uninstaller.project_dir_base_override = Samagotchi::MemoryBundle::Installer.project_dir_base_override
-    uninstaller = Samagotchi::MemoryBundle::Uninstaller.new(name: bundle_name, scope: scope, force: force)
-    begin
-      uninstaller.run
-      puts "Uninstalled bundle '#{bundle_name}'"
-      puts "Removed: #{uninstaller.removed_files.join(', ')}" unless uninstaller.removed_files.empty?
-      hook_removed = uninstaller.removed_files.count { |f| f.start_with?("hooks/") }
-      puts "Hooks removed: #{hook_removed}" if hook_removed > 0
-      uninstaller.warnings.each { |w| puts w }
-      exit 0
-    rescue Samagotchi::MemoryBundle::Uninstaller::UninstallError => e
-      warn "Uninstall failed: #{e.message}"; exit 1
-    end
-
-  when "status"
-    rest = bundle_args[1..]
-    name = rest.find { |a| !a.start_with?("--") }
-    require "json"
-    if name
-      st = Samagotchi::MemoryBundle::Status.bundle_status(name)
-      unless st
-        puts "Bundle '#{name}' not installed."
-        exit 0
-      end
-      puts "Bundle: #{name} v#{st[:provenance][:version]} scope=#{st[:scope]} installed=#{st[:provenance][:installed_at]}"
-      puts "Target: #{st[:target_dir]}"
-      st[:files].each do |k, info|
-        mods = []
-        mods << "conflict (kept your edits over v#{st[:provenance][:version]}: chi bundle diff #{name} #{k})" if info[:conflict]
-        mods << "modified" if info[:modified]
-        mods << "missing" if info[:missing]
-        mods << "no-index" unless info[:index_present]
-        label = mods.empty? ? "ok" : mods.join(",")
-        puts "  #{k}: #{label}"
-      end
-      # Hooks
-      hooks = st[:provenance][:hooks] || {}
-      trust = st[:provenance][:trust_level] || "experimental"
-      commit = st[:provenance][:source_commit]
-      puts "  trust_level: #{trust}" if hooks.any? || trust
-      puts "  source_commit: #{commit}" if commit
-      if hooks.any?
-        puts "  Hooks (#{hooks.size}):"
-        hooks.each do |hk, meta|
-          m = meta.is_a?(Hash) ? meta.transform_keys(&:to_s) : {}
-          event = m["event"] || ""
-          on_error = m["on_error"] || "skip"
-          prio = m["priority"] || 100
-          hook_path = File.join(Samagotchi::MemoryBundle::Provenance.new(name: name).hooks_dir, hk.to_s)
-          exists = File.exist?(hook_path) ? "ok" : "missing"
-          puts "    #{hk}: event=#{event} on_error=#{on_error} priority=#{prio} [#{exists}]"
-        end
-      end
-      if (plugin = st[:plugin])
-        note = plugin[:state] == "modified" ? " (edited after install: not loaded; reinstall the bundle)" : ""
-        puts "  Plugin: #{plugin[:file]} [#{plugin[:state]}]#{note}"
-        puts "    requires_chi: #{plugin[:requires_chi]}" if plugin[:requires_chi]
-        puts "    not loaded: #{plugin[:requires_failure]}" if plugin[:requires_failure]
-      end
-      st[:needs].each { |need| puts "  #{Samagotchi::MemoryBundle::Status.need_line(need)}" }
-    else
-      bundles_dir = Samagotchi::MemoryBundle::Provenance.bundles_dir
-      unless File.directory?(bundles_dir)
-        puts "No installed bundles."; exit 0
-      end
-      entries = Dir.entries(bundles_dir).reject { |e| e.start_with?(".") }
-      if entries.empty?
-        puts "No installed bundles."
-      else
-        entries.sort.each do |bname|
-          st = Samagotchi::MemoryBundle::Status.bundle_status(bname)
-          next unless st
-          mods = st[:files].values.count { |v| v[:modified] || v[:missing] }
-          hooks_count = (st[:provenance][:hooks] || {}).size
-          hook_info = hooks_count > 0 ? " hooks=#{hooks_count}" : ""
-          plugin = st[:plugin]
-          mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
-          plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
-          puts "  #{bname} v#{st[:provenance][:version]} scope=#{st[:scope]} files=#{st[:files].size}#{hook_info}#{plugin_info} issues=#{mods}"
-        end
-      end
-    end
-    exit 0
-
-  when "diff"
-    rest = bundle_args[1..]
-    args = rest.reject { |a| a.start_with?("--") }
-    bname = args[0]
-    file_arg = args[1]
-    if bname.nil? || bname.empty?
-          warn "Usage: chi bundle diff <bundle> [file]"; exit 1
-    end
-    prov = Samagotchi::MemoryBundle::Provenance.new(name: bname)
-    data = prov.read
-    unless data
-      warn "Bundle '#{bname}' not installed"; exit 1
-    end
-    scope = data[:scope]&.to_s || "system"
-    target_dir = Samagotchi::MemoryBundle::Installer.new(source: ".", name: bname, scope: scope).send(:resolve_target_dir, scope)
-    files = data[:files] || {}
-    hooks = data[:hooks] || {}
-    plugin_path = prov.plugin_path(data)
-    plugin_file = plugin_path && File.basename(plugin_path)
-    show_plugin = lambda do
-      puts "=== plugin/#{plugin_file} ==="
-      puts "--- base (provenance) ---"
-      base = prov.plugin_base_path(plugin_file)
-      puts File.exist?(base) ? File.read(base) : "(no base)"
-      puts "--- current (on-disk) ---"
-      puts File.exist?(plugin_path) ? File.read(plugin_path) : "(missing)"
-      puts "--- metadata: sha256=#{data[:plugin][:sha256]}#{data[:requires_chi] ? " requires_chi=#{data[:requires_chi]}" : ""}"
-    end
-    if file_arg
-      # Try file first, then hook
-      if files.key?(file_arg.to_sym) || files.key?(file_arg)
-        base = prov.base_path(file_arg)
-        cur = File.join(target_dir, file_arg)
-        puts "=== #{file_arg} ==="
-        puts "--- base (provenance) ---"
-        puts File.exist?(base) ? File.read(base) : "(no base)"
-        puts "--- current (on-disk) ---"
-        puts File.exist?(cur) ? File.read(cur) : "(missing)"
-      elsif hooks.key?(file_arg.to_sym) || hooks.key?(file_arg)
-        base = prov.base_path(file_arg)
-        cur = File.join(prov.hooks_dir, file_arg)
-        puts "=== hooks/#{file_arg} ==="
-        puts "--- base (provenance) ---"
-        puts File.exist?(base) ? File.read(base) : "(no base)"
-        puts "--- current (on-disk) ---"
-        puts File.exist?(cur) ? File.read(cur) : "(missing)"
-        # Show hook metadata
-        meta = hooks[file_arg.to_sym] || hooks[file_arg]
-        if meta
-          m = meta.transform_keys(&:to_s)
-          puts "--- metadata: event=#{m['event']} on_error=#{m['on_error']} priority=#{m['priority']} sha256=#{m['sha256']}"
-        end
-      elsif plugin_file && [plugin_file, "plugin/#{plugin_file}"].include?(file_arg)
-        show_plugin.call
-      else
-        puts "=== #{file_arg} ==="
-        puts "(not found in bundle)"
-      end
-      puts ""
-    else
-      keys = files.keys.map(&:to_s)
-      keys.each do |k|
-        base = prov.base_path(k)
-        cur = File.join(target_dir, k)
-        puts "=== #{k} ==="
-        puts "--- base (provenance) ---"
-        puts File.exist?(base) ? File.read(base) : "(no base)"
-        puts "--- current (on-disk) ---"
-        puts File.exist?(cur) ? File.read(cur) : "(missing)"
-        puts ""
-      end
-      # Hooks diff
-      hooks.keys.map(&:to_s).each do |k|
-        base = prov.base_path(k)
-        cur = File.join(prov.hooks_dir, k)
-        puts "=== hooks/#{k} ==="
-        puts "--- base (provenance) ---"
-        puts File.exist?(base) ? File.read(base) : "(no base)"
-        puts "--- current (on-disk) ---"
-        puts File.exist?(cur) ? File.read(cur) : "(missing)"
-        meta = hooks[k.to_sym] || hooks[k]
-        if meta
-          m = meta.transform_keys(&:to_s)
-          puts "--- metadata: event=#{m['event']} on_error=#{m['on_error']} priority=#{m['priority']} sha256=#{m['sha256']}"
-        end
-        puts ""
-      end
-      if plugin_file
-        show_plugin.call
-        puts ""
-      end
-    end
-    exit 0
-
-  when "list"
-    listing = Samagotchi::MemoryBundle::Listing
-    shipped = listing.shipped
-    installed = listing.installed(shipped: shipped)
-    available = listing.available(shipped: shipped, installed: installed)
-
-    # One column width for both sections, so the names line up.
-    name_w = (installed.map { |b| b.name.length } + available.map { |s| s.source.length }).max.to_i
-    ver_w = (installed.map { |b| (b.version || "?").to_s.length } + available.map { |s| s.version.length }).max.to_i + 1
-
-    if installed.empty?
-      puts "No installed bundles."
-    else
-      puts "Installed:"
-      installed.each do |b|
-        next puts("  #{b.name.ljust(name_w)}  (#{b.error})") if b.error
-        line = "  #{b.name.ljust(name_w)}  #{"v#{b.version || "?"}".ljust(ver_w)}  scope=#{b.scope || "?"}  files=#{b.files}  installed=#{b.installed_at || "?"}"
-        line += "  (shipped v#{b.upgrade.version}: chi bundle upgrade #{b.upgrade.source})" if b.upgrade
-        puts line
-      end
-      puts "  (or all at once: chi update)" if installed.any?(&:upgrade)
-    end
-    unless available.empty?
-      puts ""
-      puts "Available (shipped with chi, install with: chi bundle install <name>):"
-      available.each do |s|
-        puts "  #{s.source.ljust(name_w)}  #{"v#{s.version}".ljust(ver_w)}  #{s.description}".rstrip
-      end
-    end
-
-  when "build"
-    rest = bundle_args[1..]
-    scope = nil
-    name = nil
-    version = nil
-    description = ""
-    out = nil
-    filter_files = []
-    i = 0
-    while i < rest.size
-      arg = rest[i]
-      if arg.start_with?("--")
-        nxt = rest[i + 1]
-        if %w[-h --help help].include?(arg)
-          puts "Usage: chi bundle build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]"
-          puts ""
-          puts "  build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]"
-          puts "    Build local memories and installed hooks into a shareable bundle (dir or zip)."
-          puts "    --scope selects source dir (default: system). --out inferred from extension; default <name>.zip."
-          puts "    FILES... optional allowlist of *.md basenames to include (default: all)."
-          puts ""
-          puts "  Examples:"
-          puts "    chi bundle build --scope system"
-          puts "    chi bundle build --scope project --name my-bundle --version 1.0.0 --out bundle.zip"
-          puts "    chi bundle build --scope system --out ./my-bundle/ identity.md work.md"
-          exit 0
-        elsif arg == "--scope" && nxt && !nxt.start_with?("--")
-          scope = nxt; i += 2
-        elsif arg.start_with?("--scope=")
-          scope = arg.split("=", 2).last; i += 1
-        elsif arg == "--name" && nxt && !nxt.start_with?("--")
-          name = nxt; i += 2
-        elsif arg.start_with?("--name=")
-          name = arg.split("=", 2).last; i += 1
-        elsif arg == "--version" && nxt && !nxt.start_with?("--")
-          version = nxt; i += 2
-        elsif arg.start_with?("--version=")
-          version = arg.split("=", 2).last; i += 1
-        elsif arg == "--description" && nxt && !nxt.start_with?("--")
-          description = nxt; i += 2
-        elsif arg.start_with?("--description=")
-          description = arg.split("=", 2).last; i += 1
-        elsif arg == "--out" && nxt && !nxt.start_with?("--")
-          out = nxt; i += 2
-        elsif arg.start_with?("--out=")
-          out = arg.split("=", 2).last; i += 1
-        else
-          warn "Unknown bundle build flag: #{arg}"
-          exit 1
-        end
-      else
-        filter_files << arg
-        i += 1
-      end
-    end
-    # Validate scope if given
-    if scope && !%w[system project].include?(scope.to_s.strip.downcase)
-      warn "Invalid scope '#{scope}', expected system or project"
-      exit 1
-    end
-    filter_files = nil if filter_files.empty?
-    begin
-      builder = Samagotchi::MemoryBundle::Builder.new(
-        scope: scope,
-        name: name,
-        version: version,
-        description: description,
-        out: out,
-        files: filter_files
-      )
-      result = builder.run
-      puts "Built #{result[:files].size} file(s) to #{result[:out_path]}"
-      puts "Bundle: #{result[:name]} v#{result[:version]} scope=#{result[:scope]}"
-      puts "Files: #{result[:files].join(', ')}" unless result[:files].empty?
-      unless result[:placeholder_warnings].empty?
-        puts "Placeholders:"
-        result[:placeholder_warnings].each { |w| puts "  #{w}" }
-      end
-      exit 0
-    rescue Samagotchi::MemoryBundle::Builder::BuildError => e
-      warn "Build failed: #{e.message}"
-      exit 1
-    end
-
-  else
-    warn "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build"
-    exit 1
-  end
-
-  exit 0
+# Subcommands with their own flags, dispatched before OptionParser.
+SUBCOMMANDS = {
+  # list, stop, archive/unarchive, delete, prune, clean (--dry-run, --days, …)
+  "sessions" => ["samagotchi/sessions_command", "SessionsCommand"],
+  # a context note for sessions (-m, --source, --all)
+  "note" => ["samagotchi/note_command", "NoteCommand"],
+  # a message into sessions as the user's (-m)
+  "send" => ["samagotchi/send_command", "SendCommand"],
+  # find a model server and write config.yml (--model, --name)
+  "bootstrap" => ["samagotchi/bootstrap_command", "BootstrapCommand"],
+  # bring an installed chi up to date
+  "update" => ["samagotchi/update_command", "UpdateCommand"],
+  # the native "Send to chi" helper
+  "desktop" => ["samagotchi/desktop_command", "DesktopCommand"],
+  # install, upgrade, uninstall, status, diff, list, build (--scope, --force, …)
+  "bundle" => ["samagotchi/bundle_command", "BundleCommand"]
+}.freeze
+if (path, klass = SUBCOMMANDS[ARGV[0]])
+  require path
+  exit Samagotchi.const_get(klass).new(ARGV[1..] || []).run
 end
 
 # `chi scratch`: the run options below, for a session that leaves nothing
@@ -901,7 +65,7 @@ scratch = ARGV[0] == "scratch"
 ARGV.shift if scratch
 
 # no_interrupt / no_default_input start from config.yml or the env; the flags below turn them on.
-options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt"), non_interactive: false, no_default_input: Samagotchi::Config.get("no_default_input"), web: false, web_port: nil, web_open: false, web_markdown: nil, web_view: nil }
+options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt"), non_interactive: false, no_default_input: Samagotchi::Config.get("no_default_input"), web: false, web_port: nil, web_open: false, web_markdown: nil }
 cli_overrides = {}
 
 # Strict kebab enforcement: --recap_base_url is unknown (OptionParser would otherwise accept _ as -)
@@ -1028,31 +192,8 @@ Samagotchi::Config.reload!(cli_overrides: cli_overrides) unless cli_overrides.em
 require "samagotchi/log"
 Samagotchi::Log.configure(level: options[:verbose] ? :debug : nil, mirror: options[:verbose])
 
-# Handle subcommands (support `chi web --port 4567 --open --web-markdown`)
-web_args = ARGV.dup
-case ARGV[0]
-when "web"
-  options[:web] = true
-  # consume subcommand and re-parse web-specific flags that may follow it
-  web_args.shift
-  web_args.each_with_index do |arg, i|
-    if arg == "--port" && web_args[i + 1]
-      options[:web_port] = web_args[i + 1].to_i
-    elsif arg == "--open"
-      options[:web_open] = true
-    elsif arg == "--web-markdown"
-      options[:web_markdown] = true
-    elsif arg == "--no-web-markdown"
-      options[:web_markdown] = false
-    elsif arg == "--web-view" && Samagotchi::Config::BY_KEY["web.view"].enum_values.include?(web_args[i + 1])
-      options[:web_view] = web_args[i + 1]
-    elsif arg.start_with?("--web-view=") && Samagotchi::Config::BY_KEY["web.view"].enum_values.include?(arg.split("=", 2).last)
-      options[:web_view] = arg.split("=", 2).last
-    elsif arg.start_with?("--port=")
-      options[:web_port] = arg.split("=", 2).last.to_i
-    end
-  end
-end
+# `chi web`: its flags (--port, --open, --web-view…) went through the parser above.
+options[:web] = true if web
 
 # The first interactive start of a new installed chi says what `chi update` would update.
 chi_update_hint = lambda do
@@ -1070,7 +211,7 @@ if options[:web]
   port = options[:web_port] || Samagotchi::Config.get("web.port")
   markdown = options[:web_markdown]
   markdown = Samagotchi::Config.get("web.markdown") if markdown.nil?
-  view = options[:web_view] || Samagotchi::Config.get("web.view")
+  view = Samagotchi::Config.get("web.view")
   exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
                                       markdown: markdown, view: view, new_token: options[:new_token],
                                       annotate_presets: Samagotchi::Config.get("web.annotate_presets"))