samagotchi 0.88.0 → 0.89.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f395ab65a9e00861ae1dda52090efbbe363946df8098702f14c41cdc665f7bb3
-  data.tar.gz: 9f22902c72237fd51481b78f1cc91197fdc474e7f5b816e0a4429d354eb5c0aa
+  metadata.gz: f7e58a54e40f49c1617636172def63d9e6a3eaa3384ac33e26c0b55c75332555
+  data.tar.gz: 063a36d57a613a117e62b2882883c22e1ce413044c1e6d18e66aa1c8af0d6d83
 SHA512:
-  metadata.gz: 2db614ca70a821eb84905eef2d8a8fead4ac4c95b9521cb32417e034fd9f6c923dd97974f25aa2a401d3131fa479ac1911bc8e8f41aa1f383b4e34f925c51078
-  data.tar.gz: 0a2625e7ce2e7022628f5a1e14c6277eeab21caf21ae4968e908cfe68735be5c39dea2f638137f96b63a0d0ed0796f60bc7c1d3a4e71db87dc453716012957cc
+  metadata.gz: 879572f97fd05fdff6f15d4c91c3f3ce30d480ff0022b1ad3fb0220423c124004c67908f97e85ad6309302720671938cc90da80c6315de0134c9240a9b477feb
+  data.tar.gz: 0faf651033f823e4eadc87926d4c370e3e8eb714a4f8106d735110bfe7c8517972a70a4e960448ccda3b8ac1679c796e93b587070255803eb57e24e8c984a2b1

data/CHANGELOG.md

@@ -8,6 +8,24 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.89.0] - 2026-10-19
+
+### Added
+
+- `chi bundle try PATH -p TEXT` runs one real model turn in an isolated sandbox with the bundle and shipped
+  `guardrails` installed and a $1 cost cap; `--json` exposes an experimental machine-readable trace.
+- `chi bundle install --dev PATH` installs a bundle you are writing as a link to its folder: edits to its plugin,
+  hooks, rules and scripts apply at the next session with no re-install, and their sha256 isn't checked (that
+  bundle only). Memories are copied; re-install with `--force` to pick up memory edits. A re-install from the same
+  PATH prunes dropped hooks. It refuses chi-shipped bundles and profiles and warns when a linked script needs
+  `chmod +x`. `upgrade` refuses it; `uninstall` never touches PATH. `chi bundle status` shows `dev → PATH (missing)`
+  if the source is gone.
+
+### Changed
+
+- minitest is now a dependency of the gem, so `chi bundle test` runs a bundle's Minitest tests (and the one
+  `chi bundle new` writes) on a slim or vendored install without `gem install minitest`.
+
 ## [0.88.0] - 2026-10-19
 
 ### Added
@@ -3495,7 +3513,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.88.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.89.0...HEAD
+[0.89.0]: https://github.com/dm1try/samagotchi/compare/v0.88.0...v0.89.0
 [0.88.0]: https://github.com/dm1try/samagotchi/compare/v0.87.0...v0.88.0
 [0.87.0]: https://github.com/dm1try/samagotchi/compare/v0.86.0...v0.87.0
 [0.86.0]: https://github.com/dm1try/samagotchi/compare/v0.85.0...v0.86.0

data/docs/bundle-authoring.md

@@ -11,14 +11,33 @@ chi bundle new my-bundle     # ./my-bundle: manifest.yml, plugin.rb, test/my_bun
 cd my-bundle                 # edit plugin.rb and the test
 chi bundle test              # the tests, on chi's own Ruby and lib (exit status: the tests')
 chi bundle check --fix       # manifest, files, shas (--fix rewrites them), requires_chi, install + load in a sandbox
+chi bundle try . -p "Say hello"  # one real model turn; trace the bundle in an isolated install sandbox
 chi bundle install .         # into the user's chi; a NEW session loads it (a running one doesn't)
+chi bundle install --dev .   # or as a link to this folder: edits apply at the next session, no re-install
 ```
 
+While you write it, `install --dev .` (once; `uninstall NAME` leaves dev mode) then try it in chi: a new session
+loads the plugin and hooks from the folder as they are, with no sha check (that bundle only; memories are copied).
+Re-install with `--force` from the same PATH to pick up memory edits.
+Dev-linked scripts aren't chmodded, since that would change the source. Chi warns with a `chmod +x PATH/scripts/x`
+hint when a listed script isn't executable; set that bit on the source script.
+
 `check` prints one finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, and exits 1 on any
 error. Run it after every edit: an install takes exactly what it checks. It installs into a temp sandbox, not
 the user's config or state, but `check` and `test` run the bundle's plugin and hooks in their own process, as
 written: run them on code you'd install.
 
+## Trying a bundle
+
+After `chi bundle check --fix`, run `chi bundle try . -p "Say hello"` for one real model call using the user's
+configured hosts and keys. It installs the bundle plus chi's shipped guardrails and a default $1 cost cap, then
+prints tool calls, hook notices, cards, questions, the answer, token totals and cost.
+
+The child uses a temporary config, state and working directory; the user's other bundles and memories aren't loaded,
+nor are the current project's `AGENTS.md` / `CLAUDE.md` files. This is not a security sandbox: the bundle and tools
+run with the user's real HOME and account, and can access files and services available there. Use `try` only with
+code you trust. See [CLI: Trying a bundle](cli.md#trying-a-bundle) for flags, `--json`, `--keep` and exit statuses.
+
 ## The files
 
 ```yaml

data/docs/cli.md

@@ -26,6 +26,9 @@
 - `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
+- `chi bundle try PATH -p TEXT [options]` — install a bundle in a temporary, filtered sandbox, run one real model turn,
+  and print its trace (see [Trying a bundle](#trying-a-bundle)).
+
 ### First setup
 
 `chi bootstrap TARGET` names the model server and writes the config for it:
@@ -100,8 +103,16 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   Bundler env: `test/**/*_test.rb` on Minitest (`-r samagotchi/testing/minitest`), or else `spec/` on RSpec with
   the kit (`--options /dev/null -r samagotchi/testing/rspec`, as `rake bundles:specs`). `ARGS` go to the runner
   (`-- -n /name/`). Exit status: the tests'; 1 with no tests; 2 for usage, or when minitest / rspec doesn't load on
-  chi's Ruby. The tests run the bundle's code as written, with your environment (the kit sandboxes each
-  test's HOME and XDG dirs, not the process).
+  chi's Ruby (minitest is one of chi's gems; rspec is optional). The tests run the bundle's code as written, with
+  your environment (the kit sandboxes each test's HOME and XDG dirs, not the process).
+- `chi bundle install --dev PATH` installs the bundle in the local directory `PATH` (not a git URL, archive or name:
+  exit 2) as a link to it: its plugin, hooks, rules and scripts are `PATH`'s own files, so an edit applies at the
+  next worker or `chi web` restart with no re-install, and their sha256 isn't checked, for this bundle only (the
+  record says `dev`; every other bundle is checked as before). Its memories are copied at install. `chi bundle
+  status` shows `NAME vX dev → /abs/path`. `chi bundle upgrade NAME` refuses it (it follows its source already; to
+  leave dev mode: `chi bundle uninstall NAME`, then `chi bundle install` without `--dev`), as does a plain install
+  over it, and `--dev` over a normal install. `uninstall` removes the links and the record, never `PATH`'s files.
+  `check PATH` and `test PATH` are unchanged.
 - `chi bundle check [PATH] [--fix] [--set KEY=VALUE]` (PATH defaults to `.`) checks it as an install takes it, one
   finding per line, `error|warn|info CODE file[:line]: message (fix: hint)`, then `ok|failed: N errors, N
   warnings`. Exit 1 on any error, 0 otherwise, 2 for usage. It installs and loads the bundle in a temp sandbox
@@ -120,6 +131,34 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
   exceptions aside) and `tests` (info: how to run them, or "no tests"). `--set KEY=VALUE` (repeatable, typed as
   `chi --set`) goes to `bundles: <name>:` in the sandbox's config.yml.
 
+### Trying a bundle
+
+`chi bundle try PATH -p TEXT [--model NAME] [--memory NAME] [--mute NAME] [--toolkit NAME] [--thinking LEVEL]
+[--set KEY=VALUE] [--json] [--keep] [--timeout SECONDS]` installs and runs the bundle in a temporary config, state
+and work directory, then prints a trace of tool calls, notices, questions, the answer, token totals and cost. The
+child's working directory is outside your repository, so project memories and `AGENTS.md` / `CLAUDE.md` files in
+your current directory aren't loaded. Your hosts, API-key environment variables, Keychain and other runtime
+settings are retained, but your configured bundles, hooks, guardrails, memories, appended system prompts and
+attached context sources are not copied. Chi installs its shipped `guardrails` and `cost-cap` bundles for the run;
+the default cap is $1 and `--set cost-cap.cap=N` changes it. Other `--set KEY=VALUE` entries are typed config
+values under `bundles: <tried-bundle>:`; unlike `chi --set BUNDLE.KEY=VALUE`, they are not session settings and
+aren't checked against `session_settings:`. `--memory` and `--mute` accept comma-separated names and repeat.
+`--timeout` defaults to 300 seconds. An ask that no one can answer or a guardrail denial is traced and warned
+about without changing the child's exit status; hook questions made with `ctx.ask_user` are invisible in
+non-interactive mode. `--keep` retains the temporary sandbox and prints its path and debug log. `--json` writes
+one experimental JSON object to stdout and human trace lines to stderr; its keys are `session_id`, `exit_code`,
+`answer`, `tools` (`index`, `name`, `args`, `status`, `duration_ms`), `notices`, `cards`, `questions`,
+`interactive_blocked`, `used_memories`, `tokens` (`prompt`, `completion`), `cost`, `cost_is_estimate`, `model`,
+`sandbox`, `denied` (1-based tool indexes) and `stderr_tail` (last 4,000 characters). Exit status: 2 for usage,
+1 for install/turn failure or timeout, 130 for Ctrl-C, otherwise the child's status.
+
+`try` runs the bundle's code and the model's tools with your real HOME, account and keys. Its temporary working
+directory and filtered config do not make untrusted code safe: a plugin, hook or model tool can still access files
+and services available to your account. Use it only for code you trust.
+
+Tool arguments are capped to 60 characters in the text trace and 200 in JSON; the text trace shows at most 10 answer
+lines, while JSON includes the full answer. Either may contain secrets.
+
 ### Listing the models
 
 `chi models` asks every host in `hosts:` for its models, in parallel, and prints the names `--model` (and

data/docs/internals/bundles.md

@@ -24,6 +24,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 |---|---|
 | `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check`; runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
 | `BundleCommand::Check` (bundle_command/check.rb) | `chi bundle check [PATH] [--fix] [--set K=V]`: a bundle being written, checked as an install takes it (docs/cli.md lists the codes); parses the manifest from `Shas.parseable` (a placeholder sha is a `sha` finding, not a YAML error), reads the user's installed bundles only for `clash`, and installs and loads through `Testing::Install` in a `Testing::Sandbox` with `force: true`, the log's echoes swallowed |
+| `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: filtered-config `Sandbox` installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output. `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers. |
 | `BundleCommand::Scaffold` (bundle_command/scaffold.rb) | `chi bundle new NAME`: the starting files (block-form `plugin:` entry, `requires_chi` at this chi, a kit test that passes as written); the manifest's shas are filled through `Shas.refresh` |
 | `BundleCommand::TestRun` (bundle_command/test_run.rb) | `chi bundle test`: `RbConfig.ruby -I <chi's lib>` on `test/**/*_test.rb` (Minitest) or `spec/` (RSpec, as `rake bundles:specs`), under `Bundler.with_unbundled_env` when Bundler's runtime is loaded |
 | `Shas` (shas.rb) | a manifest's `sha256:` lines: `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / hook / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |
@@ -45,6 +46,15 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
 | `IndexSize` | one scope's memory index as the prompt carries it (tokens, lines, bytes): `memory.index_warn_tokens`' crossing note after a memory write, `chi self`'s summary, the prompt's figures (`SystemPrompt`) |
 | `Placeholder` | `{{placeholder}}` patterns left in an installed memory, one line per file from `Installer#detect_placeholders`; a hint, never a gate |
 
+A dev install (`chi bundle install --dev PATH`, `Installer#initialize(dev: true)`) links instead of copying:
+`AssetInstaller#place` symlinks each hook, rule file, plugin and script into `.bundles/<name>/` to its realpath in
+the source (memories are still copied: their bases and the index are the install's), and the record gets `"dev": true`
+(`InstalledBundle#dev`, `source` the realpath) with `Provenance::DEV_SHA` (`sha256:dev`, never a hex digest) in
+place of every hook, rule, plugin and script sha256. `Provenance.sha_matches?` / `.unchecked?` read it as "not
+checked", which is how the readers below skip it for that bundle only. `Installer#refuse_dev_mismatch` keeps a dev
+and a normal install from replacing each other (this is also why `chi bundle upgrade` refuses a dev bundle);
+`Uninstaller` removes links with `rm_rf`/`rm_f`, which never follow them into the source.
+
 Readers of the installed state: `Hooks::BundleLoader` (Engine), `GuardrailWiring#bundle_rules`, `Plugin::Loader`,
 `ContextProviders` (scripts), `BundleNeeds` (index markers). Each goes through `Provenance.each_installed` / `#record`
 and checks the recorded sha256 (and `requires_chi`) before loading.

data/lib/samagotchi/bundle_command/test_run.rb

@@ -10,7 +10,7 @@ module Samagotchi
     # *_test.rb runs on Minitest with the kit's Case; a spec/ with no test/
     # on RSpec with the kit's helpers, as `rake bundles:specs` runs the
     # shipped ones. Outside any Bundler env (Bundler.with_unbundled_env, as
-    # SessionManager's unbundled_env_changes): chi's gems don't include minitest.
+    # InstalledGem.unbundled_env_changes), where chi's own gem dependency minitest loads.
     # When the framework loads only inside the Bundler env chi itself runs in
     # (a checkout or a vendored install: its gems in vendor/bundle), there.
     # The tests' exit status is #run's.
@@ -37,7 +37,7 @@ module Samagotchi
       private
 
       def minitest(tests)
-        return missing("minitest", "gem install minitest") unless loads?("minitest")
+        return missing("minitest", "it ships with chi: reinstall chi (gem install samagotchi)") unless loads?("minitest")
 
         requires = tests.map { |file| "require #{file.inspect}" }.join("; ")
         say("#{tests.size} test file#{"s" unless tests.size == 1}")

data/lib/samagotchi/bundle_command/try/run.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+
+module Samagotchi
+  class BundleCommand
+    module Try
+      class Run
+        Result = Data.define(:exit_status, :stdout, :stderr, :session_id, :timed_out)
+        INTERRUPT_GRACE = 5
+        READER_GRACE = 2
+        GROUP_TERM_GRACE = 0.1
+        POLL_INTERVAL = 0.05
+
+        def initialize(sandbox)
+          @sandbox = sandbox
+        end
+
+        def run(prompt:, options:, timeout:)
+          command = [RbConfig.ruby, "-I", Sandbox::LIB_DIR, Sandbox::CHI,
+                     "--no-shared", "--non-interactive", "-p", prompt, *child_options(options)]
+          trap_state, old_traps = trap_forwarding
+          pid = nil
+          streams = []
+          readers = []
+          begin
+            Open3.popen3(@sandbox.child_env, *command, chdir: @sandbox.work_dir, pgroup: true, in: File::NULL) do |stdin, stdout, stderr, wait|
+              pid = wait.pid
+              streams = [stdout, stderr]
+              stdin.close
+              readers = streams.map { |stream| Thread.new { read_stream(stream) } }
+              attach_child(trap_state, pid)
+              timed_out = false
+              status = wait_for(wait, timeout)
+              if status == :timeout
+                timed_out = true
+                signal_group(pid, "INT")
+                status = wait_for(wait, INTERRUPT_GRACE)
+                if status == :timeout
+                  terminate_group(pid)
+                  status = wait.value
+                end
+              end
+              out, err = finish_readers(readers, streams)
+              code = timed_out ? CLI::Exit::FAILED : process_exit_status(status)
+              Result.new(exit_status: code, stdout: out, stderr: err, session_id: err[/^Session: (\S+)/, 1],
+                         timed_out: timed_out)
+            end
+          rescue SystemCallError => e
+            raise Sandbox::Error, "chi bundle try: couldn't run chi: #{e.message}"
+          ensure
+            terminate_group(pid) if pid
+            close_streams(streams)
+            stop_readers(readers)
+            restore_traps(old_traps)
+          end
+        end
+
+        private
+
+        def child_options(options)
+          args = []
+          %i[model toolkit thinking].each do |key|
+            args.concat(["--#{key}", options[key]]) if options[key]
+          end
+          %i[memory mute].each do |key|
+            Array(options[key]).each { |value| args.concat(["--#{key}", value]) }
+          end
+          args
+        end
+
+        def wait_for(wait, seconds)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+          loop do
+            return wait.value if wait.join(POLL_INTERVAL)
+            return :timeout if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          end
+        end
+
+        def trap_forwarding
+          state = { pid: nil, pending: nil }
+          old = {}
+          %w[INT TERM].each do |signal|
+            old[signal] = Signal.trap(signal) do
+              if state[:pid]
+                signal_group(state[:pid], signal)
+              else
+                state[:pending] ||= signal
+              end
+            end
+          end
+          [state, old]
+        end
+
+        def attach_child(state, pid)
+          state[:pid] = pid
+          pending = state[:pending]
+          state[:pending] = nil
+          signal_group(pid, pending) if pending
+        end
+
+        def restore_traps(old)
+          old.each { |signal, handler| Signal.trap(signal, handler) }
+        end
+
+        def signal_group(pid, signal)
+          Process.kill(signal, -pid)
+        rescue Errno::ESRCH
+          nil
+        end
+
+        def terminate_group(pid)
+          signal_group(pid, "TERM")
+          sleep(GROUP_TERM_GRACE)
+          signal_group(pid, "KILL")
+        end
+
+        def read_stream(stream)
+          output = +""
+          loop { output << stream.readpartial(16_384) }
+        rescue EOFError
+          output
+        rescue IOError
+          raise unless stream.closed?
+
+          output
+        end
+
+        def finish_readers(readers, streams)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + READER_GRACE
+          readers.each do |reader|
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            reader.join([remaining, 0].max)
+          end
+          close_streams(streams)
+          readers.each do |reader|
+            reader.join(0.1) if reader.alive?
+            reader.kill if reader.alive?
+          end
+          readers.map { |reader| reader.value.to_s }
+        end
+
+        def close_streams(streams)
+          streams.each { |stream| stream.close unless stream.closed? }
+        end
+
+        def stop_readers(readers)
+          readers.each do |reader|
+            reader.join(0.1)
+            reader.kill if reader.alive?
+          end
+          readers.each(&:join)
+        end
+
+        def process_exit_status(status)
+          status.exitstatus || (128 + status.termsig.to_i)
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/bundle_command/try/sandbox.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "tmpdir"
+require "yaml"
+require_relative "../../config"
+require_relative "../../cli/exit"
+require_relative "../../installed_gem"
+require_relative "../../memory_bundle"
+require_relative "../../memory_bundle/shas"
+require_relative "../../session_manager"
+
+module Samagotchi
+  class BundleCommand
+    module Try
+      class Sandbox
+        LIB_DIR = File.expand_path("../../..", __dir__)
+        CHI = File.expand_path("../../../../bin/chi", __dir__)
+        SHIPPED_DIR = MemoryBundle::SourceNormalizer::SHIPPED_DIR
+        CONFIG_DENYLIST = %w[
+          bundles hooks guardrails memories append_system_prompt recap session log web update kitty tmux broadcast
+          context_sources
+        ].freeze
+        CONFIG_DENYLIST_ENV_PREFIXES = CONFIG_DENYLIST.map do |section|
+          prefix = if section == "guardrails"
+                     SessionManager::GUARDRAILS_ENV_PREFIX.delete_suffix("_")
+                   else
+                     "SAMAGOTCHI_#{section.upcase}"
+                   end
+          prefix
+        end.freeze
+        class Error < StandardError
+          attr_reader :status
+
+          def initialize(message, status: CLI::Exit::FAILED)
+            super(message)
+            @status = status
+          end
+        end
+
+        attr_reader :root, :config_home, :state_home, :work_dir, :manifest
+
+        def initialize(path, bundle_settings: {}, cost_cap: 1, cost_cap_override: false)
+          @path = File.realpath(path)
+          @bundle_settings = bundle_settings
+          @cost_cap = cost_cap
+          @cost_cap_override = cost_cap_override
+          read_manifest
+          @root = File.realpath(Dir.mktmpdir("chi-bundle-try-"))
+          @config_home = File.join(root, "config")
+          @state_home = File.join(root, "state")
+          @work_dir = File.join(root, "work")
+          [config_home, state_home, work_dir].each { |dir| FileUtils.mkdir_p(dir) }
+          @work_dir = File.realpath(@work_dir)
+          write_config
+          @child_env = build_child_env
+        rescue StandardError
+          cleanup
+          raise
+        end
+
+        def child_env = @child_env.dup
+
+        def install
+          install_path(@path)
+          %w[guardrails cost-cap].each do |name|
+            next if @manifest.name == name
+
+            install_path(File.join(SHIPPED_DIR, name))
+          end
+          @manifest
+        end
+
+        def cleanup
+          FileUtils.rm_rf(root) if root && File.exist?(root)
+        end
+
+        private
+
+        def write_config
+          source = ConfigFile.read_yaml(env: ENV.to_h) || {}
+          data = source.to_h { |key, value| [key.to_s, value] }
+          # Drop bundles, hooks, guardrails, memories, append_system_prompt,
+          # recap, session, log, web, update, kitty, tmux, broadcast and
+          # context sources; keep model and ordinary runtime settings.
+          CONFIG_DENYLIST.each { |key| data.delete(key) }
+          data["context"] = data["context"].dup if data["context"].is_a?(Hash)
+          data["context"]&.delete("sources")
+          data["bundles"] = { "cost-cap" => { "cap" => @cost_cap } }
+          data["bundles"][@manifest.name] ||= {}
+          data["bundles"][@manifest.name].merge!(@bundle_settings)
+          data["bundles"]["cost-cap"]["cap"] = @cost_cap if @cost_cap_override
+          path = File.join(config_home, "samagotchi", "config.yml")
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, YAML.dump(data))
+        end
+
+        def read_manifest
+          file = File.join(@path, "manifest.yml")
+          raise Error.new("chi bundle try: not a bundle: #{@path} (chi bundle new NAME)", status: CLI::Exit::USAGE) unless File.file?(file)
+
+          text = File.read(file)
+          stale = MemoryBundle::Shas.stale(@path, text)
+          unless stale.empty?
+            raise Error, "chi bundle try: stale or placeholder sha256 in manifest.yml; run chi bundle check --fix"
+          end
+
+          @manifest = MemoryBundle::Manifest.read(dir: @path)
+          if @manifest.meta?
+            raise Error.new("chi bundle try: profile bundles cannot be tried directly", status: CLI::Exit::USAGE)
+          end
+
+          @manifest
+        rescue MemoryBundle::Manifest::ValidationError => e
+          raise Error, "chi bundle try: #{e.message}"
+        rescue MemoryBundle::Shas::Error => e
+          raise Error, "chi bundle try: #{e.message}"
+        rescue Psych::Exception => e
+          raise Error, "chi bundle try: manifest.yml is not valid YAML (#{e.message})"
+        end
+
+        def install_path(path)
+          out, err, status = Open3.capture3(child_env, RbConfig.ruby, "-I", LIB_DIR, CHI,
+                                            "bundle", "install", path, "--force", chdir: work_dir)
+          return if status.success?
+
+          message = [out, err].reject(&:empty?).join("\n").strip
+          raise Error, "chi bundle try: #{message.empty? ? "bundle install failed" : message}"
+        end
+
+        def build_child_env
+          env = ENV.to_h
+          SessionManager::SESSION_MARKER_ENV.each { |key| env.delete(key) }
+          env.delete("SAMAGOTCHI_LOG_FILE")
+          env.delete("SAMAGOTCHI_LOG_DISABLE")
+          env.delete("SAMAGOTCHI_SKIP_SYSTEM_BUNDLE")
+          env.delete("SAMAGOTCHI_ENV") if env["SAMAGOTCHI_ENV"] == "test"
+          env.delete("SAMAGOTCHI_INSTALLED_VERSION")
+          env.delete_if do |key, _|
+            key.start_with?(SessionManager::WORKER_ENV_PREFIX) || key == SessionManager::BOOT_FALLBACK_ENV ||
+              CONFIG_DENYLIST_ENV_PREFIXES.any? { |prefix| key == prefix || key.start_with?("#{prefix}_") }
+          end
+          env.merge!(
+            "HOME" => Dir.home,
+            "SAMAGOTCHI_KEYCHAIN" => "on",
+            "XDG_CONFIG_HOME" => config_home,
+            "XDG_STATE_HOME" => state_home,
+            "SAMAGOTCHI_RECAP_ENABLED" => "false",
+            "SAMAGOTCHI_CACHE_WARMUP" => "off"
+          )
+          env.merge!(InstalledGem.unbundled_env_changes(env)) if InstalledGem.spec
+          env
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/bundle_command/try/trace.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../analytics_file"
+require_relative "../../session_metrics"
+
+module Samagotchi
+  class BundleCommand
+    module Try
+      Trace = Data.define(
+        :session_id, :exit_code, :answer, :tools, :notices, :cards, :questions, :denied,
+        :interactive_blocked, :used_memories, :tokens, :cost, :cost_is_estimate, :model, :sandbox, :stderr_tail
+      )
+
+      class TraceReader
+        DENIAL_TEXT = "No one to approve it (non-interactive run)."
+        SESSION_ID = /\A[A-Za-z0-9_-]+\z/
+        STDERR_LIMIT = 4000
+
+        def initialize(state_home:, session_id:)
+          @state_home = state_home
+          @session_id = session_id if session_id.to_s.match?(SESSION_ID)
+        end
+
+        def read(exit_code:, answer:, stderr:, sandbox:)
+          return empty_trace(exit_code, answer, stderr, sandbox) unless @session_id
+
+          sessions_dir = File.join(@state_home, "samagotchi", "sessions")
+          session_path = File.join(sessions_dir, "#{@session_id}.json")
+          session_dir = File.join(sessions_dir, @session_id)
+          session = json_file(session_path) || {}
+          messages = Array(session["messages"]).select { |message| message.is_a?(Hash) }
+          analytics = AnalyticsFile.read(session_dir) || {}
+          entries = card_entries(session_dir)
+          tool_rows, denied = tools(messages, analytics)
+          summary = SessionMetrics.saved_summary(session_dir)
+          cost, estimate = cost_summary(summary)
+          questions = entries.select { |entry| entry["type"] == "question" }
+          notices = entries.select { |entry| entry["type"] == "hook_notice" }
+          cards = entries.select { |entry| entry["type"] == "card" }
+          blocked_count = questions.count { |question| unanswerable?(question) } + denied.size
+
+          Trace.new(
+            session_id: @session_id, exit_code: exit_code, answer: answer.to_s, tools: tool_rows, notices: notices,
+            cards: cards, questions: questions, denied: denied, interactive_blocked: blocked_count.positive?,
+            used_memories: Array(session["used_memory_names"]), tokens: {
+                                                                  prompt: summary&.prompt_sum, completion: summary&.completion_sum
+                                                                },
+            cost: cost, cost_is_estimate: estimate, model: session["model_name"], sandbox: sandbox,
+            stderr_tail: tail(stderr)
+          )
+        end
+
+        private
+
+        def empty_trace(exit_code, answer, stderr, sandbox)
+          Trace.new(session_id: nil, exit_code: exit_code, answer: answer.to_s, tools: [], notices: [], cards: [],
+                    questions: [], denied: [], interactive_blocked: false, used_memories: [], tokens: {
+                      prompt: nil, completion: nil
+                    }, cost: nil, cost_is_estimate: false, model: nil, sandbox: sandbox, stderr_tail: tail(stderr))
+        end
+
+        def tools(messages, analytics)
+          records = Array(analytics["tool_records"]).select { |record| record.is_a?(Hash) }
+                                                    .to_h do |record|
+            [[record["iteration"].to_i, record["call_index"].to_i], record]
+          end
+          tool_responses = messages.select { |message| %w[tool_response tool].include?(message["role"]) }
+          denied = []
+          index = 0
+          iteration = 0
+          rows = messages.flat_map do |message|
+            next [] unless %w[model assistant].include?(message["role"])
+
+            iteration += 1
+            Array(message["tool_calls"]).each_with_index.filter_map do |call, call_index|
+              next unless call.is_a?(Hash)
+
+              index += 1
+              record = records[[iteration, call_index + 1]]
+              id = call["id"]
+              response = tool_responses.find { |entry| entry["tool_call_id"] == id } if id
+              response ||= tool_responses[index - 1] unless id
+              is_denied = response && response["content"].to_s.include?(DENIAL_TEXT)
+              denied << index if is_denied
+              status = is_denied ? "denied" : record&.dig("status").to_s
+              status = "unknown" if status.empty?
+              {
+                index: index,
+                name: record&.[]("called_as") || record&.[]("tool") || call_name(call),
+                args: argument_text(call),
+                status: status,
+                duration_ms: record&.[]("duration_ms").to_i
+              }
+            end
+          end
+          [rows, denied]
+        end
+
+        def call_name(call)
+          function = call["function"].is_a?(Hash) ? call["function"] : {}
+          call["name"] || function["name"] || "tool"
+        end
+
+        def argument_text(call)
+          function = call["function"].is_a?(Hash) ? call["function"] : {}
+          args = call["arguments"] || function["arguments"] || {}
+          args = JSON.parse(args) if args.is_a?(String)
+          if args.is_a?(Hash)
+            preferred = %w[command content path url query].filter_map { |key| args[key] }.first
+            args = preferred || JSON.generate(args)
+          end
+          args.to_s.gsub(/\s+/, " ").strip[0, 200]
+        rescue JSON::ParserError
+          args.to_s.gsub(/\s+/, " ").strip[0, 200]
+        end
+
+        def card_entries(session_dir)
+          data = json_file(File.join(session_dir, "cards.json"))
+          entries = data.is_a?(Hash) ? data["entries"] : []
+          Array(entries).select { |entry| entry.is_a?(Hash) }
+        end
+
+        def unanswerable?(question)
+          question["cancelled"] && question["reason"] == "non_interactive"
+        end
+
+        def cost_summary(summary)
+          return [nil, false] unless summary
+
+          reported = summary.cost_sum.to_f
+          estimate = summary.cost_estimate_sum.to_f
+          return [reported, false] if reported.positive?
+          return [nil, false] unless estimate.positive?
+
+          [estimate, true]
+        end
+
+        def json_file(path)
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError, SystemCallError
+          nil
+        end
+
+        def tail(text)
+          value = text.to_s
+          value.length > STDERR_LIMIT ? value[-STDERR_LIMIT, STDERR_LIMIT] : value
+        end
+      end
+    end
+  end
+end