samagotchi 0.2.0

data/bin/chi

@@ -0,0 +1,1140 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+# No locale at all (an app started from Finder or launchd, `env -i`): files
+# would read as US-ASCII, and chi's session JSON is UTF-8. Workers this
+# process spawns inherit the LANG.
+if Encoding.default_external == Encoding::US_ASCII && %w[LC_ALL LC_CTYPE LANG].none? { |key| ENV[key] }
+  ENV["LANG"] = "en_US.UTF-8"
+  Encoding.default_external = Encoding::UTF_8
+end
+
+require "optparse"
+require "samagotchi/config"
+
+Samagotchi::ConfigFile.load_global_env!
+require "samagotchi"
+
+# `chi self`: print version, source dir, config/memory/session paths, model and
+# 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 "  Print version, source dir, config/memory/session paths, model/host and bundles."
+    exit 0
+  end
+  require "samagotchi/self_report"
+  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|delete|prune|clean> [options]"
+    puts "  list [--sort updated_at|created_at] [--order desc|asc] [--limit N]"
+    puts "       [--live] [--cwd PATH] [--format text|json|tsv]"
+    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 "  stop ID...   # stop each session's worker (IDs or unique prefixes); chi --resume ID then starts a fresh one"
+    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): all of them, or those older than N days"
+    puts "Defaults: days=14 keep=500 keep_status=running (env overrides: SAMAGOTCHI_SESSION_RETENTION_DAYS etc.)"
+    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")
+  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 "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.
+    if live || cwd || (format && format != "text")
+      summaries = Samagotchi::SessionManager.session_summaries(
+        live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: false, project_root: project
+      )
+      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
+        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id]
+        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]}" : ""
+          puts "#{summary[:id]}  #{state.ljust(8)}  #{summary[:updated_at]}  #{desc}#{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)
+    # 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.test_run ? " [test]" : ""
+      child = s.parent_id ? "  ↳ #{s.parent_id[0, 8]}" : ""
+      "#{s.id}  #{s.status.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, 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 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 abort, the upgrade will not be 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 — aborting. Re-run with --force to overwrite or --agent in a TTY."
+          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
+          # After session, re-check if conflicts resolved by re-reading current files vs incoming
+          # Simple heuristic: if user edited files, current != base now but we assume resolved if file exists
+          # Re-run upgrade without conflicts? User already edited in place, so we need to write provenance now
+          # Update provenance to reflect resolved state
+          if manifest
+            # Re-collect provenance files from target dir for this bundle
+            prov_files = {}
+            target_scope = scope || provenance.read[:scope]&.to_s || "system"
+            target_dir = Samagotchi::MemoryBundle::Installer.new(source: expanded_source, name: bundle_name, scope: target_scope).send(:resolve_target_dir, target_scope)
+            # Actually reuse provenance write with current target files for bundle keys
+            bundle_files = installer.conflicts.keys + installer.results.select { |_, r| %w[installed updated].include?(r[:status]) }.keys
+            # Fallback: collect all md that exist and were in installer results
+            all_keys = installer.results.keys
+            all_keys.each do |k|
+              p = File.join(target_dir, k)
+              prov_files[k] = p if File.exist?(p)
+            end
+            if prov_files.any?
+              Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).write(
+                files: prov_files,
+                scope: target_scope,
+                version: manifest.version,
+                source_path: expanded_source
+              )
+              puts "Provenance updated after interactive resolution."
+            end
+          end
+          puts "Upgrade resolved interactively."
+          exit 0
+        else
+          puts "Upgrade aborted due to conflicts. Resolve manually or re-run with --force."
+          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 << "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
+    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
+end
+
+options = { verbose: false, no_interrupt: false, non_interactive: false, no_default_input: false, web: false, web_port: nil, web_open: false, web_markdown: nil, web_turn_view: nil }
+cli_overrides = {}
+
+if ARGV.any? { |arg| arg == "--backend" || arg.start_with?("--backend=") }
+  warn "Error: --backend was removed. A host's api: in config.yml picks the loop " \
+       "(api: openai for the chat API; see docs/configuration.md)."
+  exit 1
+end
+
+# Strict kebab enforcement: --recap_base_url is unknown (OptionParser would otherwise accept _ as -)
+ARGV.each do |arg|
+  next unless arg.start_with?("--") && arg.include?("_")
+  # Allow --no-interrupt etc. already dash; underscore is always rejected for config flags
+  # We check raw ARGV before OptionParser normalizes
+  base = arg.split("=", 2).first
+  # If dashed version is a known flag (registry or hardcoded), reject underscore variant
+  dashed = base.tr("_", "-")
+  known = %w[--prompt --resume --attach --shared --no-shared --model --memory --mute --no-interrupt --non-interactive --verbose --no-default-input --port --open] + Samagotchi::Config.cli_entries.map(&:cli_flag)
+  if known.include?(dashed) || known.include?(base)
+    warn "Unknown option: #{arg} (did you mean #{dashed}?)"
+    exit 1
+  end
+end
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    Usage: chi [options]
+           chi web [--port PORT] [--open] [--scope=all]   the web UI
+           chi sessions <list|stop|delete|prune|clean>
+           chi note [--source NAME] [-m TEXT] ID...|--all   background context for sessions
+           chi send [-m TEXT] ID...         a message into sessions, as if typed there
+           chi bundle <install|upgrade|uninstall|status|diff|list|build>
+           chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
+           chi self                         version, paths, model and bundles
+    (each subcommand takes --help)
+
+  BANNER
+  opts.on("-p", "--prompt PROMPT", "Run PROMPT as the first turn, then stay in the REPL") { |p| options[:prompt] = p }
+  opts.on("--resume SESSION_ID", "Resume a previous session by its ID (or a unique prefix of it)") { |s| options[:resume] = s }
+  opts.on("--attach SESSION_ID", "Attach to a session's worker, waking one if it has exited; ID or a unique prefix") { |s| options[:attach] = s }
+  opts.on("--[no-]shared", "Run the session in a background worker and attach to it, so `chi web` can share it (the default, config session.shared; with --resume: that session); --no-shared runs a plain in-process REPL") { |v| options[:shared] = v }
+  opts.on("--model NAME", "Model selector (runtime only, overrides --resume) [alias for --default-model]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
+  opts.on("--profile NAME", Samagotchi::ModelProfile::NAMES,
+          "Prompt profile for every model in this run (#{Samagotchi::ModelProfile::NAMES.join('|')}) [alias for --model-profile]") { |p| cli_overrides["model.profile"] = p }
+  opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
+  opts.on("--mute NAME", "Hide a memory from this session: not in the prompt, refused by memory_read (repeatable; a comma list too)") { |m| (options[:muted] ||= []) << m }
+  opts.on("--no-interrupt", "Raise the tool call limit to 1000 iterations (useful for long tasks)") { options[:no_interrupt] = true; cli_overrides["no_interrupt"] = true }
+  opts.on("--non-interactive", "Run a single prompt and exit (no REPL, implies --no-interrupt)") { options[:non_interactive] = true }
+  opts.on("-v", "--verbose", "Print raw LLM responses and tool calls/results (runs a plain REPL, not attached)") { options[:verbose] = true }
+  opts.on("--no-default-input", "Skip default REPL input prefill") { options[:no_default_input] = true; cli_overrides["no_default_input"] = true }
+  opts.on("--port PORT", "Port for `chi web` (default: 4567, env SAMAGOTCHI_WEB_PORT)") { |p| options[:web_port] = p.to_i; cli_overrides["web.port"] = p.to_s }
+  opts.on("--open", "Open browser for `chi web`") { options[:web_open] = true }
+  opts.on("--scope VALUE", %w[project all],
+          "Which sessions `chi web` and `chi sessions list` show: project (the default: this folder's git project; " \
+          "every session outside a repo) or all") { |v| options[:scope] = v }
+  # Accepted values of string entries that the registry doesn't type as enums.
+  value_hints = { "thinking.ui" => "spinner|off", "status.line" => "on|off", "status.width_mode" => "terminal_cap|fixed",
+                  "web.host" => "127.0.0.1|::1|localhost", "recap.sentences" => "N|N-M" }
+  # Universal config flags (implicit convention: ENV SAMAGOTCHI_* ↔ YAML dotted ↔ CLI --kebab)
+  # Generated from Samagotchi::Config registry — Option A: snake leaf in YAML, kebab in CLI.
+  Samagotchi::Config.cli_entries.each do |entry|
+    next if %w[no_interrupt no_default_input].include?(entry.key)
+    next if entry.key == "web.port" # already handled as --port
+    next if entry.key == "default.model" # alias --model above
+    next if %w[web.markdown web.turn_view].include?(entry.key) # handled below with explicit inverse flags
+    case entry.type
+    when :bool
+      # --[no-]: a bool that defaults to on is only useful switched off.
+      opts.on("--[no-]#{entry.cli_flag.delete_prefix('--')}", "Set #{entry.key} (bool, default #{entry.default ? 'on' : 'off'}) [env #{entry.env_key}]") { |v| cli_overrides[entry.key] = v }
+    when :integer, :float, :string, :enum
+      desc = "Set #{entry.key} [env #{entry.env_key}]"
+      desc += " (#{entry.enum_values.join('|')})" if entry.type == :enum
+      desc += " (#{value_hints[entry.key]})" if value_hints.key?(entry.key)
+      desc += "; only without a hosts: config" if %w[server.host server.port].include?(entry.key)
+      desc += "; hosts: entries without a transport use it" if entry.key == "server.transport"
+      if entry.type == :enum
+        opts.on("#{entry.cli_flag} VALUE", entry.enum_values, desc) { |v| cli_overrides[entry.key] = v }
+      else
+        opts.on("#{entry.cli_flag} VALUE", desc) { |v| cli_overrides[entry.key] = v }
+      end
+    end
+  end
+  opts.on("--web-markdown", "Render finalized LLM Markdown in `chi web` (requires optional commonmarker gem)") { options[:web_markdown] = true; cli_overrides["web.markdown"] = true }
+  opts.on("--no-web-markdown", "Disable Markdown rendering in `chi web`") { options[:web_markdown] = false; cli_overrides["web.markdown"] = false }
+  opts.on("--web-turn-view", "Show each turn in `chi web` as one block of steps (the live one at the bottom; the default); ?view=turn|chat overrides per page") { options[:web_turn_view] = true; cli_overrides["web.turn_view"] = true }
+  opts.on("--no-web-turn-view", "Show turns in `chi web` as the classic row of bubbles instead of the turn view") { options[:web_turn_view] = false; cli_overrides["web.turn_view"] = false }
+  # Strict underscore rejection: --recap_base_url etc. are not registered and will raise OptionParser::InvalidOption
+  opts.on("--version", "Print chi's version") { puts "chi #{Samagotchi::VERSION}"; exit }
+  opts.on("-h", "--help", "Show help") { puts opts; exit }
+end
+begin
+  parser.parse!
+rescue OptionParser::ParseError => e
+  warn "Error: #{e.message} (see chi --help)"
+  exit 1
+end
+
+# The subcommands with their own parsers ran above; what parse! leaves is
+# `web` or nothing. Anything else is a typo, not a prompt: refuse it rather
+# than start a session.
+stray = ARGV.first == "web" ? ARGV[1] : ARGV.first
+if stray
+  warn "Error: #{ARGV.first == "web" ? "unexpected argument" : "unknown command"} #{stray} (see chi --help)"
+  exit 1
+end
+
+# Apply CLI precedence: CLI > ENV > file
+unless cli_overrides.empty?
+  Samagotchi::Config.reload!(cli_overrides: cli_overrides)
+  # Keep ENV in sync for legacy readers still using ENV directly
+  cli_overrides.each do |k, v|
+    entry = Samagotchi::Config.find_by_key(k)
+    next unless entry&.env_exposed?
+    ENV[entry.env_key] = v.to_s
+  end
+end
+
+# The debug log (Samagotchi::LogPath, level log.level) for every command.
+# -v (the plain REPL only): debug records, each mirrored to stderr.
+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-turn-view"
+      options[:web_turn_view] = true
+    elsif arg == "--no-web-turn-view"
+      options[:web_turn_view] = false
+    elsif arg.start_with?("--port=")
+      options[:web_port] = arg.split("=", 2).last.to_i
+    end
+  end
+end
+
+if options[:web]
+  require "samagotchi/web/server"
+  port = options[:web_port] || Samagotchi::Config.get("web.port") || 4567
+  # legacy env fallback
+  port = ENV.fetch("SAMAGOTCHI_WEB_PORT", port.to_s).to_i rescue port.to_i
+  markdown = options[:web_markdown]
+  markdown = Samagotchi::Config.get("web.markdown") if markdown.nil?
+  turn_view = options[:web_turn_view]
+  turn_view = Samagotchi::Config.get("web.turn_view") if turn_view.nil?
+  exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
+                                      markdown: markdown, turn_view: turn_view)
+end
+
+# --resume and --attach take a unique id prefix too, like git.
+begin
+  %i[resume attach].each { |key| options[key] &&= Samagotchi::Session.resolve_id(options[key]) }
+rescue Samagotchi::Session::AmbiguousId => e
+  warn "Error: #{e.message}"
+  exit 1
+end
+
+# --memory and --mute names are checked here, before the launch: a worker's
+# stderr goes nowhere, so its engine's warnings would not be seen. Warnings
+# only; the session starts either way.
+if options[:memories] || options[:muted]
+  require "samagotchi/muted_memories"
+  require "samagotchi/memory_bundle/system_bundle"
+  begin
+    Samagotchi::MemoryBundle::SystemBundle.ensure!
+  rescue StandardError
+    nil
+  end
+  memory_exists = lambda do |raw|
+    scope, name = raw.split("/", 2)
+    scope, name = nil, raw unless name && Samagotchi::Tools::VALID_SCOPES.include?(scope)
+    !Samagotchi::Tools::MemoryRead.call(name, scope: scope).start_with?("Error:")
+  end
+  cli_memories = (options[:memories] || []).flat_map { |m| m.split(",") }.map(&:strip).reject(&:empty?)
+  cli_memories.each { |m| warn "Warning: --memory '#{m}' not found" unless memory_exists.call(m) }
+  muted = Samagotchi::MutedMemories.normalize_list(options[:muted] || [])
+  baseline = Samagotchi::ConfigFile.preloaded_memories
+  muted.each do |name|
+    if cli_memories.any? { |m| Samagotchi::MutedMemories.normalize(m) == name }
+      warn "Warning: '#{name}' is both --memory and --mute; muted"
+    elsif baseline.any? { |m| Samagotchi::MutedMemories.normalize(m) == name }
+      warn "Warning: '#{name}' is in config.yml memories: and --mute; muted for this session"
+    elsif !memory_exists.call(name)
+      warn "Warning: --mute '#{name}' matches no memory"
+    end
+  end
+end
+
+require "samagotchi/launch_mode"
+launch, launch_note = Samagotchi::LaunchMode.resolve(options, shared_config: Samagotchi::Config.get("session.shared"))
+warn launch_note if launch_note
+
+if launch == :attached
+  conflict = { non_interactive: "--non-interactive", verbose: "--verbose" }
+             .find { |key, _flag| options[key] }
+  error = if options[:attach] && options[:shared]
+            "use either --attach ID or --shared"
+          elsif options[:attach] && options[:resume]
+            "--attach takes the session id; --resume goes with --shared"
+          elsif conflict
+            "--attach/--shared can't be combined with #{conflict.last}"
+          end
+  if error
+    warn "Error: #{error}"
+    exit 1
+  end
+
+  require "samagotchi/terminal_ui/attach_launcher"
+  begin
+    ended = Samagotchi::TerminalUI::AttachLauncher.run(attach: options[:attach], shared: !options[:attach], resume: options[:resume],
+                                                       prompt: options[:prompt], model: options[:model],
+                                                       no_interrupt: !!options[:no_interrupt],
+                                                       default_input: !options[:no_default_input],
+                                                       memories: options[:memories] || [],
+                                                       muted_memories: options[:muted] || [])
+  rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
+    warn "Error: #{e.message}"
+    exit 1
+  end
+  exit(ended == :detached ? 0 : 1)
+end
+
+begin
+  Samagotchi::TerminalUI.new(
+    prompt: options[:prompt],
+    session_id: options[:resume],
+    no_interrupt: options[:no_interrupt] || options[:non_interactive],
+    no_default_input: options[:no_default_input],
+    memories: options[:memories] || [],
+    muted_memories: options[:muted] || [],
+    non_interactive: options[:non_interactive],
+    model_name: options[:model]
+  ).run
+rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFound, Samagotchi::ModelProfile::MissingModel => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue Samagotchi::LLM::ProviderError => e
+  # -p --non-interactive: the turn failed; its prompt is in the session.
+  warn "Error: #{e.summary}"
+  exit 1
+rescue Samagotchi::ImageStore::Error => e
+  # -p --non-interactive: an @path image that can't be used.
+  warn "Error: #{e.message}"
+  exit 1
+end