rubik 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc6b8b3ff7cb67e302bbb3a74237615515318acde17b8c41193a293dadef7576
-  data.tar.gz: 3c0616b8f9b6544619903234c4595242b95c1998b2602aca584334eaf19fcc5d
+  metadata.gz: 220e106421fc0a5692890a2c3f3e7ba2296661c5ce60a96f62a3f8d5fcaa4c0a
+  data.tar.gz: 1a287e603bb553b11ebc1e0187f4a0d00e8e6b17a68c005311bc144635a1696a
 SHA512:
-  metadata.gz: e714d3f5fb612958caba5ed92829af4262b55ac50390d5ed9262cdb8c81143886d613424c13f1fe585c4debead0758469b4aeadea855edcc02d14ef5b9eb5d9b
-  data.tar.gz: cef0f0645353fe8c6f4413c39f6adff50c810c51720022774db779bce54de99a2555396f211a62af336be0be5c4a534f1c14c616a180c3c3344790ca56235772
+  metadata.gz: c02dbe25a9cc8a3af6a4c24187fc9115ad8ae5077c49e4842e2f03151ade01bedc4cc5e4709056a388a3934151b4a361422c30b1de92158e3d4c6d6d87c56743
+  data.tar.gz: db9835fd0913e3fad74ab68bdbd25137df95544579b2beed718237d09699e378fb2cbfde7da9341785f407d3aea9a43b98aedec34df1305278b93ddc3434adb6

data/CHANGELOG.md

@@ -10,6 +10,83 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 Nothing yet.
 
+## [0.3.4] - 2026-10-23
+
+A security-hardening patch: three injection/traversal findings in
+child-process enumeration, the docker sandbox driver and overlay
+storage are closed, scan-heavy paths got faster, and a wave of
+oversized REPL/LLM methods was decomposed with no behavior change.
+
+### Fixed
+
+- **Command injection in child-process enumeration (#238):**
+  `direct_child_pids` interpolated the target pid into backtick
+  shells (`pgrep -P #{pid}` / `ps --ppid #{pid}`); both lookups now
+  run through array-parameterized `Open3.capture2` calls, so pid
+  values never reach a shell for re-parsing.
+- **Command injection in the docker sandbox driver (#237):**
+  `DockerDriver#available?` and container cleanup built command
+  strings with interpolation (`docker rm -f #{container_name}`);
+  both now use array-form `system`, keeping shell metacharacters
+  inert.
+- **Path traversal in OverlayStorage (#232):** overlay directories
+  are validated against an allowlist of the four known overlay dirs
+  resolved under their trusted roots, manifests and every
+  command/tool write path are containment-checked, and traversal
+  attempts are rejected loudly with a `[SECURITY]` warning instead
+  of escaping the overlay root.
+
+### Performance
+
+- **Faster scanning internals (#220, #225, #227, #228, #244):**
+  storage indexing parses JSON lines with less string churn;
+  `Session::Replayer` streams with `File.foreach`;
+  `Buffer::Manager#all_files` prunes `.git` traversal;
+  `FuzzyMatcher#find_closest_subsequence` tightens its inner loop;
+  and `clean_utf8_deep` gains an allocation-free fast path
+  (Symbol#name validation, Hash-based cycle tracking, ~3.3x on
+  clean input). `Buffer::Manager#diff_all` also reads through
+  `Platform.read_text`, so on-disk content is UTF-8-tagged
+  consistently (#226).
+
+### Changed
+
+- **No-behavior-change decompositions (#231, #233, #234, #235,
+  #239, #240, #242, #243):** oversized REPL command registrations
+  (workspace allow-list, goal, agent providers, allow-cmd, LSP),
+  the LLM client's `post_json`, `GoalLedger::Patch#normalize_op`
+  and config `Defaults` scalar validation were split into helper
+  methods — same behavior, reviewable units.
+
+## [0.3.3] - 2026-10-21
+
+A field-incident patch: subagent runs get a lifetime step ceiling,
+budget grants stop lying about what they applied, and execution
+journals keep their terminal outcomes after truncation.
+
+### Fixed
+
+- **Subagent runs have a lifetime step ceiling (#219):** a live
+  incident showed one subagent at 950 model steps, 1,004 tool calls
+  and 10 budget grants — repeated grants could extend a run forever.
+  The new `subagents.max_total_steps` ceiling (default 256) bounds
+  the initial allocation plus every grant; grants that would exceed
+  it are truncated to the remaining room and partial or rejected
+  grants are reported as such, so the REPL and `manage_subagents`
+  echo the number that actually applied.
+- **Execution journals keep their terminal outcomes (#219):** when a
+  journal hits its byte cap, truncation now preserves the terminal
+  `run_finished` and `cancelled` records instead of cutting exactly
+  the facts a post-mortem needs; the default per-execution journal
+  cap rises from 2 MiB to 8 MiB (`subagents.journal.max_bytes`).
+
+### Changed
+
+- **Bare `rescue` clauses are explicit `rescue StandardError`
+  (#218):** standardization across platform, process, sanitize,
+  config store and the interrupt handler — same semantics, harder to
+  misread.
+
 ## [0.3.2] - 2026-10-21
 
 A reliability patch: LSP requests tell timeouts and crashes apart and

data/lib/rubik/buffer/manager.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "find"
 require "digest"
 require "pathname"
 require "monitor"
@@ -265,10 +266,27 @@ module Rubik
       # for callers that only need a fuzzy-match candidate list.
       def all_files
         buffer_keys = @monitor.synchronize { @buffer.keys }
+        return buffer_keys unless File.directory?(@root_dir)
+
         disk_files = begin
-          Dir.glob("**/*", File::FNM_DOTMATCH, base: @root_dir).reject do |f|
-            f.start_with?(".git") || File.directory?(File.expand_path(f, @root_dir))
+          files = []
+          root_size = @root_dir.bytesize
+          Find.find(@root_dir) do |path|
+            next if path.bytesize == root_size
+
+            rel = path.byteslice((root_size + 1)..-1)
+            rel = rel.tr("\\", "/") if File::ALT_SEPARATOR
+
+            if rel.start_with?(".git")
+              Find.prune if File.directory?(path)
+              next
+            end
+
+            next if File.directory?(path)
+
+            files << rel
           end
+          files
         rescue SystemCallError
           []
         end
@@ -282,7 +300,7 @@ module Rubik
 
         diffs = snapshot.map do |rel_path, new_content|
           full_path = File.expand_path(rel_path, @root_dir)
-          orig_content = File.exist?(full_path) ? Rubik::Platform.normalize_newlines(File.read(full_path)) : ""
+          orig_content = File.exist?(full_path) ? Rubik::Platform.normalize_newlines(Rubik::Platform.read_text(full_path)) : ""
           Diff.unified_diff(rel_path, orig_content, new_content)
         end
 

data/lib/rubik/config/defaults.rb

@@ -142,6 +142,7 @@ module Rubik
           "max_concurrency" => 10,
           "max_depth" => 2,
           "default_max_steps" => 88,
+          "max_total_steps" => 256, # Hard per-run ceiling across the initial allocation and all grants.
           "provider_concurrency" => 2,
           "budget_wait_timeout" => 180,
           "auto_apply_buffer" => true,
@@ -156,19 +157,15 @@ module Rubik
           # Sonuç arşivi (issue #122): tamamlanan koşular oturum-içi saklanır; redeploy öncekini EZMEZ.
           "result_archive" => { "ttl_seconds" => 3600, "max_runs_per_instance" => 8, "page_chars" => 4000 },
           # Append-only execution journal (issue #124): per-execution JSONL, capped per file.
-          "journal" => { "max_bytes" => 2_097_152 },
+          "journal" => { "max_bytes" => 8_388_608 },
           # Maestro kapısı: maestro write_file/replace_file_content/run_command/run_tests'ı ÇALIŞTIRAMAZ:
           "maestro_gate" => true,
           "auto_pause_on_network_error" => true,
           "reactive_wakeup" => true,
-          # Vakanüvis arka plan kronikçisi (storage/vakanuvis; plan
-          # 2026-10-04 K1-K9): deterministik annal + wiki derleyicisi.
-          # enabled: Düzlem 1 harness'i kur/kurulama; distiller: Düzlem 2
-          # LLM doğumu (token üst sınırı flush_events x max_steps);
-          # flush_events: damıtıcı doğumu için olay eşiği; model: nil =
-          # root provider; retention: supersede (iz bırak) | purge (sil);
-          # root_turns: REPL kök-turn'leri de annal'a yazılsın mı
-          # (root-turn planı 2026-10-04; kapalıyken abonelik kurulmaz).
+          # Vakanüvis arka plan kronikçisi (plan 2026-10-04 K1-K9): deterministik
+          # annal + wiki derleyicisi. enabled: harness kur/kurulama; distiller:
+          # Düzlem 2 LLM doğumu (bütçe: flush_events x max_steps); model: nil =
+          # root provider; retention: supersede|purge; root_turns: kök-turn annal'ı.
           "vakanuvis" => {
             "enabled" => true,
             "distiller" => true,
@@ -178,18 +175,12 @@ module Rubik
             "retention" => "supersede",
             "root_turns" => true
           },
-          # Pruner (repl/pruner): yarı deterministik KÖK pencere temizleyicisi.
-          # DEFAULT ON (kullanıcı kararı 2026-10-10) — deterministik yığın
-          # (trim_conversation_window! / ContextCompactor / EmergencyCompactor)
-          # her zaman güvenlik ağıdır; subagent kanalları bu özellikten asla
-          # etkilenmez; opt-out: "enabled" => false (kill-switch). enabled:
-          # harness'i kur (prune_context aracı + !prune komutu açılır);
-          # trigger_ratio: turn sonu pencere tahmini girdi tavanının bu
-          # oranına ulaşınca LLM budayıcı doğar (0.85'lik kör trim'den ÖNCE
-          # anlamsal sıkıştırma); target_ratio: plan yalnızca sonuç bu
-          # orana sığıyorsa uygulanır; max_steps/model: budayıcı bütçesi
-          # (nil = root provider); min_turns_between: otomatik doğum oranı
-          # sınırlayıcısı (turn sayısı).
+          # Pruner (repl/pruner): yarı deterministik KÖK pencere temizleyicisi,
+          # DEFAULT ON (kullanıcı kararı 2026-10-10; kill-switch: enabled=false).
+          # trigger_ratio: tahmini girdi tavanının bu oranında LLM budayıcı doğar
+          # (kör trim'den ÖNCE anlamsal sıkıştırma); target_ratio: plan sadece
+          # sonuca sığıyorsa uygulanır; max_steps/model: budayıcı bütçesi (nil =
+          # root provider); min_turns_between: otomatik doğum oranı sınırlayıcısı.
           "pruner" => {
             "enabled" => true,
             "trigger_ratio" => 0.6,
@@ -215,6 +206,12 @@ module Rubik
 
       private
 
+      def validate_prompt_grace_value!(key, value)
+        return unless key == "ui.prompt_grace_window_ms" && !(value.is_a?(Integer) && value >= 0)
+
+        raise ArgumentError, "ui.prompt_grace_window_ms must be a non-negative integer (milliseconds)"
+      end
+
       def validate_schema(config, schema = DEFAULT_CONFIG, prefix = "", strict: false)
         raise ArgumentError, "Configuration must be a Hash, got #{config.class}" unless config.is_a?(Hash)
 
@@ -223,11 +220,7 @@ module Rubik
           validate_prompt_grace_value!(current_key, val)
           if schema.is_a?(Hash) && !schema.key?(key.to_s)
             candidate_keys = schema.keys
-            candidates = if defined?(Rubik::Tools::FuzzyMatcher)
-                           Rubik::Tools::FuzzyMatcher.best_matches(key.to_s, candidate_keys)
-                         else
-                           []
-                         end
+            candidates = defined?(Rubik::Tools::FuzzyMatcher) ? Rubik::Tools::FuzzyMatcher.best_matches(key.to_s, candidate_keys) : []
 
             suggestion_msg = if candidates && !candidates.empty?
                                suggested_full = prefix.empty? ? candidates.first : "#{prefix}.#{candidates.first}"

data/lib/rubik/config/store.rb

@@ -113,7 +113,7 @@ module Rubik
           if File.exist?(target_path)
             begin
               File.chmod(0o600, target_path)
-            rescue
+            rescue StandardError
               nil
             end
           end

data/lib/rubik/config.rb

@@ -163,12 +163,6 @@ module Rubik
 
     private
 
-    def validate_prompt_grace_value!(key, value)
-      return unless key == "ui.prompt_grace_window_ms" && !(value.is_a?(Integer) && value >= 0)
-
-      raise ArgumentError, "ui.prompt_grace_window_ms must be a non-negative integer (milliseconds)"
-    end
-
     # save! returns itself for no-write scopes; persist outcomes are hashes.
     def persist_result(res)
       res.is_a?(Hash) ? res : { ok: true }

data/lib/rubik/llm/client.rb

@@ -234,87 +234,118 @@ module Rubik
         )
       end
 
-      def self.post_json(url_str, headers: {}, payload: {}, timeout: 30, open_timeout: 10,
-                         max_retries: 2, max_429_retries: 5, backoff_base: 0.2, max_wall_clock: 120,
-                         on_retry: nil, http_factory: nil)
-        begin
-          uri = URI.parse(url_str.to_s)
-        rescue URI::InvalidURIError => e
-          raise ClientError, "Invalid endpoint URL '#{url_str}': #{e.message}"
-        end
-
+      def self.parse_and_validate_uri(url_str)
+        uri = URI.parse(url_str.to_s)
         unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
           raise ClientError, "Invalid endpoint URL '#{url_str}'. URL must start with http:// or https:// (e.g. https://api.openai.com/v1/chat/completions)"
         end
 
+        uri
+      rescue URI::InvalidURIError => e
+        raise ClientError, "Invalid endpoint URL '#{url_str}': #{e.message}"
+      end
+
+      def self.perform_post_request(uri, headers, payload, timeout:, open_timeout:, http_factory:)
+        if http_factory
+          http = http_factory.call(uri)
+          req = build_post_request(uri, headers, payload)
+          http.request(req)
+        else
+          with_pooled_connection(uri, timeout: timeout, open_timeout: open_timeout) do |http|
+            req = build_post_request(uri, headers, payload)
+            http.request(req)
+          end
+        end
+      end
+
+      # Rate limiting is transitory and self-healing — it gets its own
+      # larger budget (max_429_retries), a Retry-After-aware delay, and
+      # a typed error when exhausted so callers can report "provider
+      # throttled" distinctly. The generic 5xx budget is untouched, so
+      # one 429 burst cannot exhaust the transport-failure budget.
+      def self.handle_429_retry(res, rate_limit_retries:, max_429_retries:, start_time:, backoff_base:, max_wall_clock:, on_retry:)
+        if rate_limit_retries < max_429_retries
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+          delay = retry_delay_after(res, rate_limit_retries + 1, backoff_base)
+          if elapsed + delay <= max_wall_clock
+            rate_limit_retries += 1
+            on_retry&.call(rate_limit_retries, max_429_retries, "HTTP 429")
+            sleep(delay)
+            return rate_limit_retries
+          end
+        end
+        raise rate_limit_error(res, rate_limit_retries)
+      end
+
+      def self.attempt_backoff_retry(retries:, max_retries:, start_time:, backoff_base:, max_wall_clock:, reason:, on_retry:)
+        return nil unless retries < max_retries
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        delay = backoff_base * (2**retries) * (0.8 + (0.4 * rand))
+        return nil if elapsed + delay > max_wall_clock
+
+        retries += 1
+        on_retry&.call(retries, max_retries, reason)
+        sleep(delay)
+        retries
+      end
+
+      # A body without a charset arrives tagged ASCII-8BIT; embedding it
+      # raw makes every ClientError message binary and the UTF-8 output
+      # layer raises inside the REPL's rescue clause (masking the real
+      # HTTP error as Encoding::CompatibilityError).
+      # Exhausted 5xx is transport-class (provider outage) → transient;
+      # a 4xx is content/auth/moderation → permanent. One raise point
+      # for both, the flag decided by status (issue #106).
+      def self.parse_json_response(res, uri:, status:)
+        unless status >= 200 && status < 300
+          raise ClientError.new(
+            "HTTP Request failed with code #{res.code}: #{Rubik::Platform.safe_utf8(res.body)}",
+            transient: status >= 500
+          )
+        end
+
+        begin
+          JSON.parse(res.body)
+        rescue JSON::ParserError => e
+          raise ClientError, "Invalid JSON response from #{uri.host} (HTTP #{status}): #{e.message}"
+        end
+      end
+
+      def self.post_json(url_str, headers: {}, payload: {}, timeout: 30, open_timeout: 10,
+                         max_retries: 2, max_429_retries: 5, backoff_base: 0.2, max_wall_clock: 120,
+                         on_retry: nil, http_factory: nil)
+        uri = parse_and_validate_uri(url_str)
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         retries = 0
         rate_limit_retries = 0
 
         loop do
-          res =
-            if http_factory
-              http = http_factory.call(uri)
-              req = build_post_request(uri, headers, payload)
-              http.request(req)
-            else
-              with_pooled_connection(uri, timeout: timeout, open_timeout: open_timeout) do |http|
-                req = build_post_request(uri, headers, payload)
-                http.request(req)
-              end
-            end
-
+          res = perform_post_request(uri, headers, payload, timeout: timeout, open_timeout: open_timeout, http_factory: http_factory)
           status = res.code.to_i
 
           if status == 429
-            # Rate limiting is transitory and self-healing — it gets its own
-            # larger budget (max_429_retries), a Retry-After-aware delay, and
-            # a typed error when exhausted so callers can report "provider
-            # throttled" distinctly. The generic 5xx budget is untouched, so
-            # one 429 burst cannot exhaust the transport-failure budget.
-            if rate_limit_retries < max_429_retries
-              elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-              delay = retry_delay_after(res, rate_limit_retries + 1, backoff_base)
-              if elapsed + delay <= max_wall_clock
-                rate_limit_retries += 1
-                on_retry&.call(rate_limit_retries, max_429_retries, "HTTP 429")
-                sleep(delay)
-                next
-              end
-            end
-            raise rate_limit_error(res, rate_limit_retries)
+            rate_limit_retries = handle_429_retry(
+              res, rate_limit_retries: rate_limit_retries, max_429_retries: max_429_retries,
+                   start_time: start_time, backoff_base: backoff_base, max_wall_clock: max_wall_clock,
+                   on_retry: on_retry
+            )
+            next
           end
 
-          if (status >= 500) && (retries < max_retries)
-            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-            delay = backoff_base * (2**retries) * (0.8 + (0.4 * rand))
-            if elapsed + delay <= max_wall_clock
-              retries += 1
-              on_retry&.call(retries, max_retries, "HTTP #{status}")
-              sleep(delay)
+          if status >= 500
+            new_retries = attempt_backoff_retry(
+              retries: retries, max_retries: max_retries, start_time: start_time,
+              backoff_base: backoff_base, max_wall_clock: max_wall_clock, reason: "HTTP #{status}",
+              on_retry: on_retry
+            )
+            if new_retries
+              retries = new_retries
               next
             end
           end
 
-          unless status >= 200 && status < 300
-            # A body without a charset arrives tagged ASCII-8BIT; embedding it
-            # raw makes every ClientError message binary and the UTF-8 output
-            # layer raises inside the REPL's rescue clause (masking the real
-            # HTTP error as Encoding::CompatibilityError).
-            # Exhausted 5xx is transport-class (provider outage) → transient;
-            # a 4xx is content/auth/moderation → permanent. One raise point
-            # for both, the flag decided by status (issue #106).
-            raise ClientError.new(
-              "HTTP Request failed with code #{res.code}: #{Rubik::Platform.safe_utf8(res.body)}",
-              transient: status >= 500
-            )
-          end
-
-          begin
-            return JSON.parse(res.body)
-          rescue JSON::ParserError => e
-            raise ClientError, "Invalid JSON response from #{uri.host} (HTTP #{status}): #{e.message}"
-          end
+          return parse_json_response(res, uri: uri, status: status)
         rescue ClientError
           raise
         rescue Net::ReadTimeout
@@ -323,15 +354,14 @@ module Rubik
         rescue Interrupt
           raise # rubocop:disable Lint/DuplicateBranch -- Ctrl+C yayilimi bilinçli olarak ayri tutuldu, even mid-backoff
         rescue *RETRYABLE_ERRORS => e
-          if retries < max_retries
-            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-            delay = backoff_base * (2**retries) * (0.8 + (0.4 * rand))
-            if elapsed + delay <= max_wall_clock
-              retries += 1
-              on_retry&.call(retries, max_retries, e.class.name)
-              sleep(delay)
-              next
-            end
+          new_retries = attempt_backoff_retry(
+            retries: retries, max_retries: max_retries, start_time: start_time,
+            backoff_base: backoff_base, max_wall_clock: max_wall_clock, reason: e.class.name,
+            on_retry: on_retry
+          )
+          if new_retries
+            retries = new_retries
+            next
           end
           raise ClientError.new(
             "Network error calling #{uri.host}: #{e.class} #{e.message} (gave up after #{retries} retr#{retries == 1 ? 'y' : 'ies'})",

data/lib/rubik/orchestrator/goal_ledger/patch.rb

@@ -121,81 +121,98 @@ module Rubik
         end
 
         def self.normalize_op(raw, idx)
-          return [nil, [op_shape_reason(idx)]] unless raw.is_a?(Hash)
+          err = validate_op_keys(raw, idx)
+          return [nil, [err]] if err
+
+          verb, path, err = validate_op_verb_and_path(raw, idx)
+          return [nil, [err]] if err
+
+          tokens, err = tokenize(path, idx)
+          return [nil, [err]] if err
+
+          err = validate_op_value_and_hyphen(raw, verb, path, tokens, idx)
+          return [nil, [err]] if err
+
+          value = verb == "remove" ? nil : deep_freeze(raw["value"])
+          [{ op: verb.to_sym, path: path, tokens: tokens, value: value, index: idx }.freeze, []]
+        end
+
+        def self.validate_op_keys(raw, idx)
+          return op_shape_reason(idx) unless raw.is_a?(Hash)
 
           unknown = raw.keys - OP_KEYS
-          unless unknown.empty?
-            return [nil, [GoalLedger.reason(
-              :schema, op_index: idx, path: "",
-                       message: "op #{idx} carries unknown key(s) #{unknown.join(', ')}",
-                       hint: "allowed op keys: op, path, value"
-            )]]
-          end
+          return nil if unknown.empty?
+
+          GoalLedger.reason(
+            :schema, op_index: idx, path: "",
+                     message: "op #{idx} carries unknown key(s) #{unknown.join(', ')}",
+                     hint: "allowed op keys: op, path, value"
+          )
+        end
 
+        def self.validate_op_verb_and_path(raw, idx)
           verb = raw["op"]
           unless OP_VERBS.include?(verb)
-            return [nil, [GoalLedger.reason(
+            return nil, nil, GoalLedger.reason(
               :schema, op_index: idx, path: "",
                        message: "op #{idx} has unknown verb #{GoalLedger.json_type_name(verb)}#{verb_inspect(verb)}",
                        hint: "allowed verbs: add, replace, remove"
-            )]]
+            )
           end
 
           path = raw["path"]
           unless path.is_a?(String)
-            return [nil, [GoalLedger.reason(
+            return nil, nil, GoalLedger.reason(
               :schema, op_index: idx, path: "",
                        message: "op #{idx} path must be a JSON string (got #{GoalLedger.json_type_name(path)})",
                        hint: 'address sections with JSON pointers like "/tasks/3/status" or "/findings/-"'
-            )]]
+            )
           end
 
           unless path.start_with?("/")
-            return [nil, [GoalLedger.reason(
+            return nil, nil, GoalLedger.reason(
               :schema, op_index: idx, path: path,
                        message: "op #{idx} path '#{path}' is not a JSON pointer",
                        hint: 'pointers start with "/" — use /section, /section/idx, /section/idx/field or /section/-'
-            )]]
+            )
           end
 
           if path == "/"
-            return [nil, [GoalLedger.reason(
+            return nil, nil, GoalLedger.reason(
               :schema, op_index: idx, path: path,
                        message: "op #{idx} addresses the whole ledger root",
-                       hint: "the ledger root is not replaceable; address sections individually " \
-                             "(/tasks/3/status, /findings/-, ...)"
-            )]]
+                       hint: "the ledger root is not replaceable; address sections individually (/tasks/3/status, /findings/-, ...)"
+            )
           end
 
-          tokens, err = tokenize(path, idx)
-          return [nil, [err]] if err
+          [verb, path, nil]
+        end
 
+        def self.validate_op_value_and_hyphen(raw, verb, path, tokens, idx)
           if verb == "remove" && raw.key?("value")
-            return [nil, [GoalLedger.reason(
+            return GoalLedger.reason(
               :schema, op_index: idx, path: path,
                        message: "op #{idx} (remove) must not carry a value",
                        hint: "to change a value use replace; remove deletes the item outright"
-            )]]
+            )
           end
           unless verb == "remove" || raw.key?("value")
-            return [nil, [GoalLedger.reason(
+            return GoalLedger.reason(
               :schema, op_index: idx, path: path,
                        message: "op #{idx} (#{verb}) is missing its value",
                        hint: 'carry the value in the op: {"op": "add", "path": "/findings/-", "value": ...}'
-            )]]
+            )
           end
 
           if hyphen_violation(tokens, verb)
-            return [nil, [GoalLedger.reason(
+            return GoalLedger.reason(
               :schema, op_index: idx, path: path,
                        message: "op #{idx} path '#{path}' uses '-' outside an append position",
-                       hint: "'-' appends and may only be the final token of an add path " \
-                             "(e.g. /findings/-); use a numeric index for existing items"
-            )]]
+                       hint: "'-' appends and may only be the final token of an add path (e.g. /findings/-); use a numeric index for existing items"
+            )
           end
 
-          value = verb == "remove" ? nil : deep_freeze(raw["value"])
-          [{ op: verb.to_sym, path: path, tokens: tokens, value: value, index: idx }.freeze, []]
+          nil
         end
 
         def self.op_shape_reason(idx)
@@ -261,6 +278,7 @@ module Rubik
         end
 
         private_class_method :header_reasons, :normalize_op, :op_shape_reason, :verb_inspect,
+                             :validate_op_keys, :validate_op_verb_and_path, :validate_op_value_and_hyphen,
                              :tokenize, :hyphen_violation, :deep_freeze
       end
     end

data/lib/rubik/orchestrator/subagent/budget.rb

@@ -28,9 +28,11 @@ module Rubik
       class Budget
         DEFAULT_MAX_STEPS = 88
         DEFAULT_GRANT_STEPS = 20
+        DEFAULT_MAX_TOTAL_STEPS = 256
 
-        def initialize(max_steps: nil)
-          @max_steps = (max_steps || DEFAULT_MAX_STEPS).to_i
+        def initialize(max_steps: nil, max_total_steps: DEFAULT_MAX_TOTAL_STEPS)
+          @max_total_steps = [(max_total_steps || DEFAULT_MAX_TOTAL_STEPS).to_i, 1].max
+          @max_steps = [(max_steps || DEFAULT_MAX_STEPS).to_i, @max_total_steps].min
           @current_step = 0
           @monitor = Monitor.new
         end
@@ -39,6 +41,10 @@ module Rubik
           @monitor.synchronize { @max_steps }
         end
 
+        def max_total_steps
+          @monitor.synchronize { @max_total_steps }
+        end
+
         def current_step
           @monitor.synchronize { @current_step }
         end
@@ -62,14 +68,16 @@ module Rubik
           @monitor.synchronize { "[Step #{@current_step}/#{@max_steps}]" }
         end
 
-        # Normalize -> floor -> +=, atomically. Returns the
-        # [extra, total] pair Instance's note lambda needs. Terminal-state
+        # Normalize -> floor -> cap, atomically. Returns the [extra, total]
+        # pair Instance's note lambda needs. Repeated grants can never push a
+        # run past its configured lifetime ceiling. Terminal-state
         # refusal, the :running transition, the history note, and the condvar
         # broadcast stay on Instance — lifecycle facts, not budget facts.
         # Called with the Instance monitor held (lock order: instance -> budget).
         def grant!(steps)
           @monitor.synchronize do
-            extra = Budget.normalize_grant(steps)
+            available = [@max_total_steps - @max_steps, 0].max
+            extra = [Budget.normalize_grant(steps), available].min
             @max_steps += extra
             [extra, @max_steps]
           end
@@ -80,11 +88,10 @@ module Rubik
           @monitor.synchronize { { current_step: @current_step, max_steps: @max_steps } }
         end
 
-        # Pure half of the grant invariant, shared by grant! (mutation edge)
-        # and the reporting edges (manage_subagents steps arg, REPL
-        # !subagents extend arg): nil/non-positive -> DEFAULT_GRANT_STEPS, so
-        # the number a caller echoes can never disagree with the number
-        # grant! applies. Idempotent.
+        # Pure normalization half shared by grant! and the reporting edges
+        # (manage_subagents steps arg, REPL !subagents extend arg). A grant
+        # may be smaller than this normalized request when the lifetime
+        # ceiling has less room remaining. Idempotent.
         def self.normalize_grant(steps)
           extra = (steps || DEFAULT_GRANT_STEPS).to_i
           extra = DEFAULT_GRANT_STEPS if extra <= 0