pikuri-code 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff5d50756cde495c335c697fdc272a9cb209bf650e8265da49156d3540f9c9eb
-  data.tar.gz: 81d0993c7e2780994f9410e62635319344b5f56cb8b1cc8f8c2e559c9fa7f8c8
+  metadata.gz: b7738ccd6890de1d33b779a626b5443c11bd8324711cf146cb844991c8fb8d0e
+  data.tar.gz: 9b4cf07b853e874231f5a3d86d7a67450569704cf12e091d4b9229e4ad29387a
 SHA512:
-  metadata.gz: 3b3a81cff6aeb19a0e3c88cb1383e06726520e0487f6c78ddba1268ab9a0acf2bf22de8fa435bc25304debc7313e64d8a2d3c46d4397c812ca9fe1a00632b563
-  data.tar.gz: f8fea57c6d597688a1dabe69982e8cde112f67f7474923c7bff375d77eb81679082f57258c999eaeb740801c977831c87d4cb264df40a2b8b19db5ccbaa37786
+  metadata.gz: b4c96ca2c0b85e75cbce666025cf3ea13507d9efdf260a1eae114b6090a742b295078ee8e44592218e3be1778b0bed6b3f853df48c86e2980fb6b333d68641e8
+  data.tar.gz: 56112b2b1b5cb6d0008d2cf35787a07e900532fb32e204fafc7634b9c98f34769cd9b23abfacbd8ec652b885cef7fc0b24fdce460a1d72695c7b6ac060b0941b

data/lib/pikuri/code/bash/sandbox.rb

@@ -79,37 +79,59 @@ module Pikuri
         #   own processes due to +--unshare-pid+) and +/dev+ (synthetic,
         #   +null+/+zero+/+random+/+tty+ only) round out the synthetic
         #   mounts.
-        # * +workspace.readable+ → +--ro-bind+ each path at the same
-        #   path in the sandbox, EXCEPT paths that also appear in
-        #   +ephemeral_overlay:+ (see below).
-        # * +workspace.writable+ → +--bind+ (read+write) each path. The
-        #   workspace temp's host path (under +~/.cache/pikuri+, not
-        #   under +/tmp+) is bound at its host path too — so the same
-        #   dir is reachable via both +/tmp+ (LLM reflex) and the host
-        #   path (advertised by the system prompt, used consistently
-        #   by the file tools off the host filesystem).
-        # * +ephemeral_overlay+ — per-user dependency caches the
-        #   toolchain mutates (+~/.gradle/caches+, +~/.m2/repository+,
-        #   +~/.cargo/registry+, …). Each path is mounted as a
-        #   bubblewrap overlay: the host's real dir is the lower
-        #   (read-through), and a per-session upper +
-        #   workdir under +<workspace.internal_temp>/overlay-<slug>/+
-        #   absorb writes. Result: gradle/maven/cargo see a fully
-        #   read-write view of their cache, the host's real cache is
-        #   untouched, and on process exit the umbrella (and with it
-        #   every upper layer) is removed by the workspace's
-        #   {Pikuri::Finalizers} registration. Within one pikuri-code session writes survive
-        #   across bash calls (warm cache after the first build);
-        #   across sessions they don't (so a session that gets
-        #   prompt-injected into poisoning the in-sandbox view of
-        #   gradle's cache cannot propagate the damage to the host's
-        #   normal +gradle+ invocations or to a future pikuri-code
-        #   session). Note: the overlay paths are deliberately *narrow*
-        #   subdirs (e.g. +~/.gradle/caches+, not +~/.gradle+) so
-        #   +gradle.properties+ / +init.d+ / +.credentials+ never
-        #   reach the sandbox at all — see
-        #   {Pikuri::Code::ToolchainPaths} for the credential / persistence
-        #   exclusion rationale.
+        # * +workspace.readable+ → mounted as a *read-write ephemeral
+        #   overlay* each (when the kernel supports overlayfs in a user
+        #   namespace; +--ro-bind+ fallback otherwise — see "Overlay
+        #   support" below). The host's real dir is the lower
+        #   (read-through), and a per-session upper + workdir under
+        #   +<workspace.internal_temp>/overlay-<slug>/+ absorb writes.
+        #   Result: the bash subprocess sees a fully read-write view of
+        #   +/usr+, +~/.rbenv+, +~/.gradle/caches+, +~/.m2/repository+,
+        #   …, so +gem install+ / +bundle install+ / +mvn+ / +gradle+ /
+        #   +cargo+ / +pip+ all succeed; the host's real toolchain and
+        #   caches are untouched; and on process exit the umbrella (and
+        #   with it every upper layer) is removed by the workspace's
+        #   {Pikuri::Finalizers} registration. Within one pikuri-code
+        #   session writes survive across bash calls (warm cache after
+        #   the first build — the upper is a persistent dir on disk,
+        #   re-mounted each call, *not* a tmpfs that dies with the
+        #   bwrap process); across sessions they don't (so a session
+        #   that gets prompt-injected into poisoning the in-sandbox
+        #   view of gradle's cache or a toolchain binary cannot
+        #   propagate the damage to the host's normal +gradle+
+        #   invocations or to a future pikuri-code session). Note: the
+        #   cache entries in {Pikuri::Code::ToolchainPaths} are
+        #   deliberately *narrow* subdirs (e.g. +~/.gradle/caches+, not
+        #   +~/.gradle+) so +gradle.properties+ / +init.d+ /
+        #   +.credentials+ never reach the sandbox at all — the lower
+        #   layer is the host's real file, so a narrow mount, not the
+        #   write's ephemerality, is what keeps secrets out. See
+        #   {Pikuri::Code::ToolchainPaths} for the credential /
+        #   persistence exclusion rationale.
+        # * +workspace.writable+ → +--bind+ (read+write, *persistent* —
+        #   not an overlay) each path. The workspace temp's host path
+        #   (under +~/.cache/pikuri+, not under +/tmp+) is bound at its
+        #   host path too — so the same dir is reachable via both
+        #   +/tmp+ (LLM reflex) and the host path (advertised by the
+        #   system prompt, used consistently by the file tools off the
+        #   host filesystem).
+        #
+        # == Overlay support
+        #
+        # overlayfs in a user namespace needs Linux ≥ 5.11. The
+        # constructor probes for it once and remembers the result:
+        # when supported, +workspace.readable+ dirs are overlaid (the
+        # writes-just-work path above); when not, they fall back to
+        # +--ro-bind+ and the sandbox still functions — but writes into
+        # a read-only toolchain dir (e.g. +gem install+ into
+        # +~/.rbenv+) fail with +EROFS+, surfaced to the LLM as the
+        # bash observation. The probe degrades with a logged warning
+        # rather than raising, so an old-kernel host still gets a
+        # working (if less convenient) sandbox. {SYSTEM_ROOTS} and
+        # {ETC_BASELINE} stay +--ro-bind+ regardless — nothing writes
+        # to +/lib+ or +/etc/resolv.conf+ (and overlayfs is
+        # directory-only, so the single-file +/etc+ entries can't be
+        # overlays anyway).
         #
         # == Concurrency contract
         #
@@ -174,7 +196,7 @@ module Pikuri
         # == Failures that surface at construction
         #
         # The constructor probes the workspace shape, then +bwrap+ with a
-        # no-op invocation. Four cases raise loudly:
+        # no-op invocation. Three cases raise loudly:
         #
         # * Workspace lists +/+ as writable (typically
         #   {Workspace::Filesystem::AllowAll}) — Bubblewrap exists for
@@ -190,16 +212,23 @@ module Pikuri
         #   file tools; fail at construction instead of letting that
         #   trap fire mid-conversation.
         # * +bwrap+ not on +PATH+ → +Errno::ENOENT+ wrapped as +RuntimeError+.
-        # * Kernel lacks user-namespace support (some hardened distros)
-        #   → +bwrap+ exits non-zero, surfaced as +RuntimeError+.
+        # * Kernel lacks user-namespace support entirely (some hardened
+        #   distros) → the basic +bwrap+ probe exits non-zero, surfaced
+        #   as +RuntimeError+.
         #
-        # Either way the binary should fail at boot, not on the first
-        # +bash+ tool call — matches the "errors are loud" convention.
-        # The host opts out of sandboxing via +--no-sandbox+ /
-        # +--yolo+.
+        # The constructor *also* probes overlayfs support, but a failure
+        # there does NOT raise — it degrades to read-only binds with a
+        # logged warning (see "Overlay support" above). A working
+        # sandbox on an old kernel beats no sandbox at all.
+        #
+        # The raising cases fail at boot, not on the first +bash+ tool
+        # call — matches the "errors are loud" convention. The host
+        # opts out of sandboxing entirely via +--no-sandbox+ / +--yolo+.
         class Bubblewrap
           BWRAP_BINARY = 'bwrap'
 
+          LOGGER = Pikuri.logger_for('Sandbox')
+
           # System-root dirs the subprocess needs that aren't in
           # {Workspace#readable}. Each is +--ro-bind+'d if it exists on
           # the host; missing entries are skipped silently (older or
@@ -271,13 +300,9 @@ module Pikuri
           #   per-host readable/writable roots, the +chdir+ target for
           #   the subprocess, and the parent of the per-session
           #   overlay state ({Workspace::Filesystem#internal_temp}).
-          # @param ephemeral_overlay [Array<String, Pathname>] paths
-          #   (must each be a member of +workspace.readable+) to mount
-          #   as bubblewrap overlays instead of read-only binds.
-          #   Typically wired with
-          #   +Pikuri::Code::ToolchainPaths.ephemeral_overlay+. Empty
-          #   by default — pure read-only baseline. See the class
-          #   header for the rationale.
+          #   Every +workspace.readable+ dir is mounted as a read-write
+          #   ephemeral overlay (or +--ro-bind+ if the kernel lacks
+          #   overlayfs-in-userns support); see the class header.
           # @raise [RuntimeError] if the workspace lists +/+ as writable
           #   (Bubblewrap is for filesystem containment, which is moot
           #   when the entire filesystem is the workspace — typically
@@ -285,23 +310,19 @@ module Pikuri
           #   {NONE} instead).
           # @raise [RuntimeError] if the workspace has +temp+ set but
           #   +alias_tmp_to_temp+ unset — see the class header.
-          # @raise [RuntimeError] if any +ephemeral_overlay+ path is
-          #   not also a member of +workspace.readable+ (so the LLM's
-          #   host-side file tools and the sandbox view stay
-          #   consistent on which paths are visible).
           # @raise [RuntimeError] if any workspace path equals or is
           #   an ancestor of a known container/VM control socket
           #   (+/var/run/docker.sock+, +containerd.sock+, +podman.sock+,
           #   …); see {DENIED_CONTAINER_SOCKETS}.
           # @raise [RuntimeError] if +bwrap+ isn't on +PATH+ or fails
-          #   its probe (typically: kernel without user-namespace
-          #   support).
-          def initialize(workspace:, ephemeral_overlay: [])
+          #   its basic probe (typically: kernel without user-namespace
+          #   support). A *separate* overlayfs probe failure does NOT
+          #   raise — it degrades to read-only binds (see the class
+          #   header's "Overlay support").
+          def initialize(workspace:)
             @workspace = workspace
-            @ephemeral_overlay = ephemeral_overlay.map { |p| Pathname.new(p).realpath }.uniq
             reject_unbounded_workspace!
             reject_unaliased_temp!
-            reject_overlay_outside_readable!
             reject_container_socket_exposure!
             check_bwrap!
           end
@@ -388,25 +409,14 @@ module Pikuri
                   'intend the agent to drive a container daemon.'
           end
 
-          # Every +ephemeral_overlay+ path must also be in
-          # +workspace.readable+ — otherwise the LLM's host-side file
-          # tools (Read/Grep/Glob, which read the real host
-          # filesystem, not the sandbox view) would reject the same
-          # path as outside the workspace while bash inside the
-          # sandbox could see it through the overlay. That asymmetry
-          # would burn an entire turn of LLM confusion every time. Fail
-          # at construction.
-          def reject_overlay_outside_readable!
-            readable = @workspace.readable.to_set
-            stray = @ephemeral_overlay.reject { |p| readable.include?(p) }
-            return if stray.empty?
-
-            raise 'Code::Bash::Sandbox::Bubblewrap: ephemeral_overlay paths ' \
-                  "#{stray.map(&:to_s).inspect} are not in workspace.readable " \
-                  '— the LLM would see one view via Read/Grep/Glob and a different ' \
-                  "view via bash. Add the path(s) to the workspace's readable: list."
-          end
-
+          # Probes +bwrap+ itself (raises if missing or user namespaces
+          # are unsupported), then probes overlayfs support and caches
+          # the result in +@overlay_supported+. The overlay probe runs
+          # only when there's at least one dir that would actually be
+          # overlaid — i.e. a +workspace.readable+ entry that isn't
+          # already a +workspace.writable+ +--bind+ (a project-root-only
+          # workspace overlays nothing, so the second spawn would be
+          # wasted).
           def check_bwrap!
             result = Pikuri::Subprocess.spawn(
               BWRAP_BINARY,
@@ -422,7 +432,8 @@ module Pikuri
                     'support enabled in the kernel? Pass --no-sandbox to skip.'
             end
 
-            check_overlay! unless @ephemeral_overlay.empty?
+            overlayable = @workspace.readable - @workspace.writable
+            @overlay_supported = overlayable.empty? ? false : probe_overlay_support?
           rescue Errno::ENOENT
             raise "Code::Bash::Sandbox::Bubblewrap: 'bwrap' not found on PATH. " \
                   'Install bubblewrap (apt-get install bubblewrap / dnf install ' \
@@ -430,11 +441,14 @@ module Pikuri
           end
 
           # Second-stage probe: overlayfs in a user namespace requires
-          # Linux ≥ 5.11. The basic +check_bwrap!+ above succeeds on
-          # older kernels too (it doesn't touch overlay), so without
-          # this stage a kernel < 5.11 would pass construction and
-          # then fail at the *first* bash tool call with a confusing
-          # mount error. Probe at boot, fail loud at boot.
+          # Linux ≥ 5.11. The basic +check_bwrap!+ probe succeeds on
+          # older kernels too (it doesn't touch overlay), so we probe
+          # separately here. Unlike the basic probe this does NOT raise
+          # on failure — it logs a warning and returns +false+, and
+          # {#bwrap_args} falls back to +--ro-bind+ for the readable
+          # dirs. A working sandbox (toolchain dirs visible read-only,
+          # writes failing with +EROFS+) beats no sandbox on an old
+          # kernel; the host can still pass +--no-sandbox+ to opt out.
           #
           # Uses +--overlay-src /usr --tmp-overlay /tmp+: declares
           # +/usr+ as the read-only lower layer (always present on
@@ -443,7 +457,9 @@ module Pikuri
           # back the upper with tmpfs. No host paths to manage, no
           # leftover state, and the +--overlay-src+ is required —
           # +--tmp-overlay+ refuses to construct without at least one.
-          def check_overlay!
+          #
+          # @return [Boolean] whether overlayfs-in-userns works here.
+          def probe_overlay_support?
             result = Pikuri::Subprocess.spawn(
               BWRAP_BINARY,
               '--unshare-all', '--share-net',
@@ -454,20 +470,21 @@ module Pikuri
               '/bin/true',
               chdir: '/'
             ).wait
-            return if result.status.success?
+            return true if result.status.success?
 
-            raise 'Code::Bash::Sandbox::Bubblewrap: overlay probe failed ' \
-                  "(exit #{result.status.exitstatus}). The bubblewrap " \
-                  'sandbox can run but overlayfs in a user namespace is ' \
-                  'not supported on this kernel (Linux ≥ 5.11 required). ' \
-                  'Construct with ephemeral_overlay: [] to skip overlays, ' \
-                  'or pass --no-sandbox to disable the sandbox entirely.'
+            LOGGER.warn(
+              "overlayfs in a user namespace is unavailable (bwrap overlay probe " \
+              "exit #{result.status.exitstatus}; Linux >= 5.11 required). Falling " \
+              'back to read-only binds for toolchain dirs — gem/bundle/pip/build ' \
+              'installs into read-only toolchain dirs will fail with EROFS. Pass ' \
+              '--no-sandbox to disable the sandbox entirely.'
+            )
+            false
           end
 
           def bwrap_args
             args = []
             mounted = Set.new
-            overlay_set = @ephemeral_overlay.map(&:to_s).to_set
 
             # 1. OS-runtime baseline — NOT in workspace by design.
             (SYSTEM_ROOTS + ETC_BASELINE).each do |p|
@@ -494,9 +511,11 @@ module Pikuri
             # 3. Workspace-derived mounts. Writable wins on overlap
             #    (writable ⊆ readable in the Workspace constructor;
             #    iterating writable first + the `mounted` guard
-            #    ensures each path is mounted once). Readable paths
-            #    that are also in @ephemeral_overlay get an overlay
-            #    mount instead of a plain --ro-bind.
+            #    ensures each path is mounted once). Writable paths are
+            #    plain read+write --bind (persistent). Readable paths
+            #    are read-write ephemeral overlays when overlayfs is
+            #    supported (so toolchain installs succeed but vanish at
+            #    session exit), falling back to --ro-bind otherwise.
             @workspace.writable.each do |p|
               s = p.to_s
               next if mounted.include?(s)
@@ -506,7 +525,7 @@ module Pikuri
             @workspace.readable.each do |p|
               s = p.to_s
               next if mounted.include?(s)
-              args.concat(overlay_set.include?(s) ? overlay_mount_args(s) : ['--ro-bind', s, s])
+              args.concat(@overlay_supported ? overlay_mount_args(s) : ['--ro-bind', s, s])
               mounted << s
             end
 

data/lib/pikuri/code/bash.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'rainbow'
-
 module Pikuri
   module Code
     # The +bash+ tool — run an arbitrary shell command in the workspace.
@@ -13,13 +11,18 @@ module Pikuri
     #
     # == Confirmation
     #
-    # Every command requires confirmation. Bash composes the full prompt
-    # (header line, +$ <command>+ echo, +(y/n)?+ cue) and hands it to the
-    # confirmer; the confirmer renders + parses the answer. The command
-    # echo passes through {.visible} which escapes control bytes so the
-    # model can't smuggle a +\r\033[2K rm -rf ~/+ behind the displayed
-    # text. Execution uses the raw command; only the *display* is
-    # sanitized.
+    # Every command requires confirmation. Bash composes a semantic
+    # {Pikuri::Workspace::Confirmer::Request} — question (header line)
+    # plus detail (+$ <command>+ echo) — and hands it to the confirmer,
+    # which owns ALL presentation: color, the answer cue, answer
+    # parsing, and medium-appropriate escaping of the raw bytes (a
+    # terminal neutralizes control bytes, a web client HTML-escapes).
+    # The request deliberately carries the command verbatim so each
+    # renderer can escape for its own medium. The *observation* echo
+    # (+$ ...+ in the tool result) stays on this side of the seam and
+    # passes through {.visible}, so the model can't smuggle a
+    # +\r\033[2K rm -rf ~/+ behind the displayed text there either.
+    # Execution uses the raw command; only displays are sanitized.
     #
     # == Subprocess wiring
     #
@@ -34,6 +37,12 @@ module Pikuri
     # +--kill-after=5s+ gives the command 5 seconds to handle SIGTERM
     # cleanly before SIGKILL is sent.
     #
+    # The subprocess environment is "de-bundlerized" first — pikuri is
+    # usually launched under Bundler, which would otherwise leak its own
+    # +BUNDLE_GEMFILE+ / +RUBYOPT+ / ... into the command so a +bundle
+    # exec+ run against another project picks up *pikuri's* Gemfile. See
+    # {.subprocess_env} / {.bundler_clean_delta}.
+    #
     # == Timeout detection
     #
     # GNU coreutils' +timeout+ exits +124+ after a successful SIGTERM,
@@ -195,14 +204,15 @@ module Pikuri
         return "Error: timeout must be >= 1, got #{timeout}" if timeout < 1
         return "Error: timeout must be <= #{MAX_TIMEOUT}, got #{timeout}" if timeout > MAX_TIMEOUT
 
-        prompt = compose_prompt(command: command, description: description, timeout: timeout)
-        return 'Error: user declined the bash command.' unless confirmer.confirm?(prompt: prompt)
+        request = compose_request(command: command, description: description, timeout: timeout)
+        return 'Error: user declined the bash command.' unless confirmer.confirm?(request: request)
 
         argv = sandbox.wrap([
           'timeout', '--signal=TERM', "--kill-after=#{KILL_AFTER}", "#{timeout}s",
           'bash', '-c', command
         ])
-        result = Pikuri::Subprocess.spawn(*argv, chdir: workspace.project_root.to_s, env: workspace.env).wait
+        result = Pikuri::Subprocess.spawn(*argv, chdir: workspace.project_root.to_s,
+                                                 env: subprocess_env(workspace)).wait
 
         output = truncate(result.output)
         exit_code = result.status.exitstatus
@@ -217,41 +227,117 @@ module Pikuri
         end
       end
 
-      # Compose the multi-line confirmation prompt. Three lines:
+      # Compose the semantic confirmation request:
       #
-      # 1. +OK to run bash[: <desc>][ \[Timeout: Ns\]]+ (bold)
-      # 2. +$ <visible(command)>+ (dim)
-      # 3. +(y/n)?+
+      # * question — +OK to run bash[: <desc>][ \[Timeout: Ns\]]+
+      # * detail — +$ <command>+, the command VERBATIM (the confirmer
+      #   escapes for its medium; see the class header's Confirmation
+      #   section)
       #
       # Colon after +bash+ is dropped when there's no description, since a
       # trailing colon with nothing after it reads as broken. Timeout
       # suffix appears only when non-default.
       #
-      # @return [String]
-      def self.compose_prompt(command:, description:, timeout:)
-        header = +'OK to run bash'
+      # @return [Pikuri::Workspace::Confirmer::Request]
+      def self.compose_request(command:, description:, timeout:)
+        question = +'OK to run bash'
         desc_clean = description&.strip
-        header << ": #{desc_clean}" if desc_clean && !desc_clean.empty?
-        header << " [Timeout: #{timeout}s]" if timeout != DEFAULT_TIMEOUT
+        question << ": #{desc_clean}" if desc_clean && !desc_clean.empty?
+        question << " [Timeout: #{timeout}s]" if timeout != DEFAULT_TIMEOUT
+
+        Pikuri::Workspace::Confirmer::Request.new(question: question, detail: "$ #{command}")
+      end
+      private_class_method :compose_request
+
+      # Environment for the bash subprocess: the workspace's git-identity
+      # vars ({Pikuri::Workspace::Filesystem#env}) layered over a
+      # "de-bundlerized" base.
+      #
+      # pikuri is typically launched under Bundler — the +bin/pikuri-code+
+      # demo and every downstream host (e.g. pikuri-tui) pin
+      # +BUNDLE_GEMFILE+ to their *own* Gemfile and +require
+      # 'bundler/setup'+ at boot. Doing so makes Bundler rewrite
+      # +BUNDLE_GEMFILE+ / +RUBYOPT+ / +GEM_HOME+ / +GEM_PATH+ / +RUBYLIB+
+      # / +PATH+ in the *process* environment (stashing the pre-bundler
+      # values under +BUNDLER_ORIG_*+). Those vars are inherited by every
+      # subprocess we spawn — so a +bundle exec rspec+ the agent runs in
+      # *another* Ruby project would resolve against PIKURI's Gemfile and
+      # die with a baffling "the Gemfile specifies ... is missing" error.
+      #
+      # The fix is to hand bash the environment as it was *before* bundler
+      # touched it (see {.bundler_clean_delta}), with the workspace's git
+      # identity on top.
+      #
+      # @param workspace [Pikuri::Workspace::Filesystem]
+      # @return [Hash{String=>(String,nil)}] +env:+ delta for
+      #   {Pikuri::Subprocess.spawn} (a +nil+ value unsets the key in the
+      #   child).
+      def self.subprocess_env(workspace)
+        bundler_clean_delta.merge(workspace.env)
+      end
+      private_class_method :subprocess_env
 
-        [
-          Rainbow(header).bold,
-          Rainbow("$ #{visible(command)}").dimgray,
-          '(y/n)?'
-        ].join("\n")
+      # The delta that, merged onto the current (bundler-polluted) +ENV+
+      # via {Pikuri::Subprocess.spawn}'s +env:+, reconstructs
+      # +Bundler.unbundled_env+ — the environment as it was before
+      # +bundler/setup+ ran.
+      #
+      # +Bundler.unbundled_env+ restores each +BUNDLER_ORIG_*+ backup, so
+      # a host-level +GEM_HOME+/+GEM_PATH+ from a +sudo apt install ruby+
+      # install (pointing at +~/.gem+) passes straight through and the
+      # subprocess still finds the user's gems — it is *not* a blanket
+      # +GEM_*+ wipe — while the bundler-only vars (+BUNDLE_*+, the
+      # +-rbundler/setup+ +RUBYOPT+) are dropped. We diff against the live
+      # +ENV+ rather than passing the full hash because +spawn+'s +env:+
+      # is additive: changed/added keys carry their clean value, keys
+      # bundler injected that aren't in the clean env map to +nil+
+      # (+Open3.popen2e+ unsets a +nil+-valued key in the child).
+      #
+      # When pikuri runs *without* Bundler (gem-installed, or a host that
+      # never required +bundler/setup+) this is empty and the child
+      # inherits the environment unchanged.
+      #
+      # @return [Hash{String=>(String,nil)}]
+      def self.bundler_clean_delta
+        return {} unless defined?(Bundler) && Bundler.respond_to?(:unbundled_env)
+
+        env_delta(current: ENV.to_h, clean: Bundler.unbundled_env)
+      end
+      private_class_method :bundler_clean_delta
+
+      # Pure diff between two environment hashes: the additive delta that,
+      # applied to +current+ via {Pikuri::Subprocess.spawn}'s +env:+,
+      # yields +clean+. A key whose value differs (or is new in +clean+)
+      # carries the +clean+ value; a key present in +current+ but absent
+      # from +clean+ maps to +nil+ (which +Open3.popen2e+ unsets). Keys
+      # equal in both are omitted, keeping the delta minimal.
+      #
+      # @param current [Hash{String=>String}]
+      # @param clean [Hash{String=>String}]
+      # @return [Hash{String=>(String,nil)}]
+      def self.env_delta(current:, clean:)
+        delta = {}
+        clean.each { |k, v| delta[k] = v unless current[k] == v }
+        current.each_key { |k| delta[k] = nil unless clean.key?(k) }
+        delta
       end
-      private_class_method :compose_prompt
+      private_class_method :env_delta
 
-      # Escape control bytes for safe display while preserving +\n+
-      # (multi-line shell commands are normal). Catches +\r+, +\x1b+
-      # (ESC, the ANSI introducer), +\b+, NUL, DEL, etc. — without this,
-      # a model could craft +command: "\rrm -rf ~/"+ that visually
-      # overwrites the echo line after the user has already read it.
+      # Neutralize control bytes for safe display in the *observation*
+      # echo (+"$ ..."+ in the tool result) — without this, a model could
+      # craft +command: "\rrm -rf ~/"+ that visually overwrites the echo
+      # line after the user has already read it. Delegates to the shared
+      # {Pikuri::Sanitizer}, which preserves +\n+ (multi-line shell
+      # commands are normal) and visualizes the rest; the confirmation
+      # prompt routes the same command through the same primitive (see
+      # +Confirmer::Terminal+). The echo is passive, so the
+      # {Pikuri::Sanitizer::Warning}s are dropped here — they surface at
+      # the confirmation prompt, before the user approves.
       #
       # @param command [String]
       # @return [String]
       def self.visible(command)
-        command.gsub(/[\x00-\x09\x0b-\x1f\x7f]/) { |c| format('\\x%02x', c.ord) }
+        Pikuri::Sanitizer.sanitize(command).text
       end
       private_class_method :visible
 

data/lib/pikuri/code/toolchain_paths.rb

@@ -2,17 +2,15 @@
 
 module Pikuri
   module Code
-    # Curated lists of filesystem prefixes a coding agent benefits
-    # from seeing: system toolchains under +/usr+ and +/opt+, per-user
+    # Curated list of filesystem prefixes a coding agent benefits from
+    # seeing: system toolchains under +/usr+ and +/opt+, per-user
     # toolchain managers (mise/asdf/rbenv/pyenv/nvm/rustup), and the
     # per-user dependency caches the toolchains themselves mutate
     # (Gradle, Maven, Cargo, npm, pip, …). Not a tool — a
     # configuration helper that +bin/pikuri-code+ (and any downstream
     # coding binary built on pikuri-code) feeds into
     # +Pikuri::Workspace::Filesystem.new(readable: ...)+ alongside the
-    # skill catalog's roots, and into
-    # +Pikuri::Code::Bash::Sandbox::Bubblewrap.new(ephemeral_overlay: ...)+
-    # for the overlay layer.
+    # skill catalog's roots.
     #
     # The list is the "allowlist a coding agent reads" surface derived
     # from the threat-model discussion that drove this gem; see
@@ -20,43 +18,47 @@ module Pikuri
     # containment story and CLAUDE.md's Scope decisions for the
     # Linux-first stance.
     #
-    # == .readable vs. .ephemeral_overlay
+    # == One list, overlaid — not a readable-vs-writable split
     #
-    # The split exists because the bubblewrap sandbox treats these two
-    # groups differently:
+    # Earlier this module split the paths into "true read-only"
+    # (toolchains) and "ephemeral overlay" (caches the toolchain
+    # mutates). That split is gone: every entry here is mounted by
+    # {Pikuri::Code::Bash::Sandbox::Bubblewrap} as a *read-write
+    # ephemeral overlay* (when the kernel supports overlayfs in a user
+    # namespace; read-only bind otherwise). The host's real dir is the
+    # read-through lower; a per-session upper absorbs writes and is
+    # discarded at process exit.
     #
-    # * {.readable} — true read-only: system toolchains (+/usr+,
-    #   +/opt+) and per-user toolchain managers (+~/.rbenv+, +~/.pyenv+,
-    #   +~/.nvm+, +~/.asdf+, +~/.rustup+, +~/.local/share/mise+, +~/.config/mise+).
-    #   The user installed these out-of-band; the LLM should be able
-    #   to grep them but neither write nor *appear* to write to them.
-    #   Bubblewrap +--ro-bind+'s each.
-    # * {.ephemeral_overlay} — per-user dependency caches the
-    #   toolchain itself mutates when invoked: subdirs of +~/.gradle+,
-    #   +~/.m2/repository+, +~/.cargo/registry+, +~/.ivy2/cache+,
-    #   +~/go/pkg/mod+, +~/.cache/pip+, +~/.cache/uv+, +~/.npm+, the
-    #   pnpm store, +~/.nuget/packages+. The toolchain *needs* to
-    #   write to these (Gradle's journal/locks, Maven downloading a
-    #   new dep, …), but persistent host pollution from a poisoned
-    #   pikuri-code session would propagate to the user's other
-    #   projects. The bubblewrap sandbox overlays each with a
-    #   per-session ephemeral upper layer under
-    #   +<workspace.internal_temp>/overlay-<slug>/+ — writes survive
-    #   across bash calls within one session, then vanish at process
-    #   exit. See {Pikuri::Code::Bash::Sandbox::Bubblewrap} for the
-    #   wiring.
+    # The reason is that build tools assume their dirs are writable.
+    # A read-only +~/.rbenv+ (or mise/asdf/system Ruby) breaks
+    # +gem install+ / +bundle install+ with +EROFS+ — the gem install
+    # target lives *inside* the version-manager dir, so there's no
+    # separate cache to overlay. Overlaying the whole dir lets the
+    # install succeed against an ephemeral copy: the toolchain writes,
+    # the warm result survives across bash calls within the session,
+    # and the host's real toolchain is never touched. The same
+    # ephemerality that makes a writable +/usr+ safe (writes vanish at
+    # exit, host untouched) is what makes "the LLM must not even appear
+    # to write here" moot — so the old read-only treatment bought
+    # nothing and cost a class of confusing failures.
     #
-    # The host-side workspace continues to include both lists in its
-    # +readable+ set, so the LLM can Read/Grep/Glob them via the file
-    # tools (which operate on the host filesystem, not the sandbox view).
+    # The host-side workspace includes this list in its +readable+ set,
+    # so the LLM can Read/Grep/Glob the paths via the file tools (which
+    # operate on the host filesystem, not the sandbox view). Writes the
+    # LLM makes through bash land in the overlay and are *not* visible
+    # to the host-reading file tools — the same accepted asymmetry the
+    # cache overlays always had.
     #
     # == Why subdirs, not whole toolchain dirs
     #
-    # Every entry in {.ephemeral_overlay} is a content-only subdir
-    # chosen to *exclude* the toolchain's credential / persistence
-    # files. The exposed path holds cache content (downloaded jars,
-    # distributions, modules); the excluded paths hold secrets or
-    # build-config:
+    # The per-user dependency caches are listed as *content-only
+    # subdirs* chosen to *exclude* the toolchain's credential /
+    # persistence files. Even though the overlay is ephemeral, the
+    # host's real file is the read-through lower — so a narrower mount
+    # keeps secrets out of the sandbox's view entirely rather than
+    # relying on "the write vanished." The exposed path holds cache
+    # content (downloaded jars, distributions, modules); the excluded
+    # paths hold secrets or build-config:
     #
     #   * +~/.gradle/caches+ + +~/.gradle/wrapper/dists+ + +~/.gradle/jdks+
     #     — NOT +~/.gradle/gradle.properties+ (signing keys, OSSRH /
@@ -71,50 +73,45 @@ module Pikuri
     #     (crates.io publish tokens).
     #   * +~/.ivy2/cache+ — NOT +~/.ivy2/.credentials+ (resolver creds).
     #
-    # +bwrap+ creates the parent dir (e.g. +~/.gradle/+) as an empty
-    # tmpfs directory inside the sandbox automatically, so the
-    # toolchain can mkdir new subdirs there (e.g. +~/.gradle/daemon/+)
-    # without seeing anything we didn't bind. The cost is mild: dirs
-    # outside the overlay list (+~/.gradle/daemon/+, native cache,
-    # configuration cache) start empty each bash call instead of
-    # persisting within a session. That's acceptable for daemon-style
-    # caches — the warm-cache value lives in +caches/+ and +wrapper/+,
-    # which the overlays cover.
+    # The version-manager roots (+~/.rbenv+, +~/.pyenv+, …) are listed
+    # *whole* because they don't carry credential files — their gem /
+    # package install targets live directly under them, so a narrower
+    # mount would defeat the purpose. mise installs Ruby/Node under
+    # +~/.local/share/mise/installs+, so overlaying +~/.local/share/mise+
+    # covers mise-managed +gem install+; system Ruby installs under
+    # +/usr+, covered by the +/usr+ overlay.
     module ToolchainPaths
       # @return [Array<String>] absolute paths, in stable order, each
       #   one confirmed to be an existing directory at the moment of
       #   the call. Presence-filtered: a developer who doesn't have
       #   Rust installed doesn't get a phantom +~/.rustup+ in their
-      #   workspace.
+      #   workspace, and a missing +~/.gradle/caches+ stays out (on the
+      #   assumption the user doesn't use Gradle yet — its eventual
+      #   bootstrap inside the sandbox without a host lower would fail
+      #   noisily, which is what we want). The whole list is mounted as
+      #   read-write ephemeral overlays by
+      #   {Pikuri::Code::Bash::Sandbox::Bubblewrap}; see the module
+      #   header for why each cache entry is a content-only subdir
+      #   rather than the whole toolchain dir.
       def self.readable
         home = Dir.home
         candidates = [
+          # System + per-user toolchains. Whole dirs — no credential
+          # files live here, and gem/package install targets sit
+          # directly under them.
           '/usr',
           '/opt',
           File.join(home, '.local/share/mise'),
           File.join(home, '.config/mise'),
           File.join(home, '.asdf'),
           File.join(home, '.rbenv'),
+          File.join(home, '.gem'),
           File.join(home, '.pyenv'),
           File.join(home, '.nvm'),
-          File.join(home, '.rustup')
-        ]
-        candidates.select { |p| File.directory?(p) }.freeze
-      end
-
-      # @return [Array<String>] absolute paths to per-user dependency
-      #   caches the toolchain mutates. Presence-filtered, same
-      #   discipline as {.readable}: a missing +~/.gradle/caches+
-      #   stays out of the list, on the assumption the user doesn't
-      #   use Gradle yet (and Gradle's eventual bootstrap inside the
-      #   sandbox without a host lower would fail noisily, which is
-      #   what we want — see the rationale in
-      #   {Pikuri::Code::Bash::Sandbox::Bubblewrap}). See the module
-      #   header for why each entry is a content-only subdir rather
-      #   than the whole toolchain dir.
-      def self.ephemeral_overlay
-        home = Dir.home
-        candidates = [
+          File.join(home, '.rustup'),
+          # Per-user dependency caches the toolchain mutates. Each is a
+          # content-only subdir that excludes the toolchain's
+          # credential / persistence files — see the module header.
           File.join(home, '.cargo/registry'),
           File.join(home, '.m2/repository'),
           # Gradle: caches/ (jar + journal + transforms + build-cache),

data/prompts/coding-system-prompt.txt

@@ -2,8 +2,6 @@ You are an expert coding assistant who reads, edits, and runs code via tools to
 
 You operate on the local filesystem under a workspace directory. All file-touching tools resolve paths within that workspace; trying to escape returns an error. The `bash` and `write` tools may prompt the user for confirmation before running — if they decline, accept it and don't retry the same operation.
 
-You have access to tools described in the API's tool list. To call one, use the standard tool-call mechanism — do not write tool calls as text.
-
 If several next steps are independent (e.g. reading two unrelated files, or running unrelated checks), emit them as parallel tool calls in a single turn rather than one at a time.
 
 Choosing a tool:
@@ -20,6 +18,8 @@ Working on code:
 - After a substantive change, run the project's tests or build if you can locate them (look at README, package.json, Cargo.toml, Makefile, build.gradle, Gemfile, etc.).
 - Don't add ceremonial comments. Match the surrounding code's commenting style.
 - NEVER commit, push, or open a PR unless the user explicitly asks.
+- When crafting git commit message, take a look at the diff instead of creating commit
+  message from filenames alone.
 
 Other guidelines:
 - Don't repeat a tool call with identical arguments — re-read the previous observation instead.

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-code
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Martin Vysny
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pikuri-core
@@ -16,56 +15,56 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
 - !ruby/object:Gem::Dependency
   name: pikuri-workspace
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
 - !ruby/object:Gem::Dependency
   name: pikuri-subagents
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
 - !ruby/object:Gem::Dependency
   name: pikuri-tasks
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.5
+        version: 0.0.7
 description: |
   pikuri-code adds the shell-and-dev-loop layer on top of
   pikuri-workspace's filesystem tools: a +Pikuri::Code::Bash+ that
@@ -99,7 +98,6 @@ metadata:
   changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
   bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -114,8 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: In-repo coding-agent shell tool (Bash) + pikuri-code binary.
 test_files: []