rubik 0.1.5 → 0.1.6

data/lib/rubik/tools/builtins/exec.rb

@@ -150,51 +150,99 @@ module Rubik
       def execute(args = {})
         cmd = (args["command"] || args[:command]).to_s.strip
         background = args["background"] || args[:background]
-        if background
-          task_mgr = @task_manager || (@runtime_context.respond_to?(:get) ? Rubik::Coeffects.get(@runtime_context, Rubik::Coeffects::TASK_MANAGER) : nil)
-          return ToolOutput.error("TaskManager is not available to run commands in background.") unless task_mgr
+        return execute_background(cmd) if background
 
-          @guard.verify_command_safety!(cmd)
-          task = task_mgr.start(cmd, chdir: @root_dir, ctx: @runtime_context)
-          return "Command dispatched to background task [#{task.id}] (PID #{task.pid}): #{cmd}\nUse `manage_task` with action 'status' or 'logs' to inspect."
+        timeout = effective_timeout(args)
+        @guard.verify_command_safety!(cmd)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        res = @runner.run(cmd, timeout: timeout, chdir: @root_dir)
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(1)
+        command_result(cmd, res, duration_ms: duration_ms)
+      rescue Rubik::Security::BlockedWriteError => e
+        # Authorization denial (issue #127): nothing executed, so no process
+        # exit code is fabricated — the metadata says denied / not executed.
+        # The prefix stays first for display consumers (StepExecutor::ERROR_PREFIXES).
+        Rubik::Tools::Result.new(
+          tool_name: "run_command", status: :error,
+          output: Rubik::Tools::RunCommandTool.blocked_guidance(e),
+          error: "command denied by security policy (not executed)",
+          exit_code: nil, metadata: { "executed" => false, "denied" => "authorization" }
+        )
+      rescue StandardError => e
+        Rubik::Tools::Result.new(
+          tool_name: "run_command", status: :error,
+          output: "Command error: #{e.message}", error: e.message,
+          exit_code: nil, metadata: { "executed" => false }
+        )
+      end
+
+      # Stable public seam (RunCommandTool#execute, ManageTaskTool, tests and
+      # dev/review_fix_check call it). The renderer lives in the security
+      # domain next to the error it renders: Rubik::Security::BlockedGuidance
+      # — also keeps this file under the builtin line budget.
+      def self.blocked_guidance(err)
+        Rubik::Security::BlockedGuidance.render(err)
+      end
+
+      private
+
+      def execute_background(cmd)
+        task_mgr = @task_manager ||
+                   (@runtime_context.respond_to?(:get) ? Rubik::Coeffects.get(@runtime_context, Rubik::Coeffects::TASK_MANAGER) : nil)
+        if task_mgr.nil?
+          return Rubik::Tools::Result.new(tool_name: "run_command", status: :error,
+                                          output: "TaskManager is not available to run commands in background.",
+                                          error: "task manager unavailable",
+                                          metadata: { "executed" => false, "background" => true })
         end
 
+        @guard.verify_command_safety!(cmd)
+        task = task_mgr.start(cmd, chdir: @root_dir, ctx: @runtime_context)
+        text = "Command dispatched to background task [#{task.id}] (PID #{task.pid}): #{cmd}\n" \
+               "Use `manage_task` with action 'status' or 'logs' to inspect."
+        Rubik::Tools::Result.new(tool_name: "run_command", status: :ok, output: text, exit_code: nil,
+                                 metadata: { "executed" => true, "background" => true, "task_id" => task.id })
+      end
+
+      def effective_timeout(args)
         # Timeout contract: runners expose their config via a public `config`
         # reader (Sandbox::Runner does via attr_reader). Never reach into an
         # arbitrary object with instance_variable_get — that couples us to an
         # ivar name we do not own and silently falls back if it is ever renamed.
         cfg = @runner.config if @runner.respond_to?(:config)
         cfg_timeout = cfg&.fetch("tools.timeout_seconds", 30) || 30
-        timeout = (args["timeout"] || args[:timeout] || cfg_timeout).to_i.clamp(1, 600)
+        (args["timeout"] || args[:timeout] || cfg_timeout).to_i.clamp(1, 600)
+      end
 
-        @guard.verify_command_safety!(cmd)
-        res = @runner.run(cmd, timeout: timeout, chdir: @root_dir)
-        status = res[:ok] ? "OK" : "EXIT #{res[:exit_code]}"
-        # Shell tag (Plan 55 D-5) teaches the model which interpreter ran the
-        # command; drivers that resolve no shell simply omit it.
+      # The structured command outcome (issue #127): the display text keeps
+      # the historical [OK]/[EXIT n] prefix and diagnostics, while the machine
+      # fields (status / exit_code / truncated / metadata) ride the Result
+      # contract through BOTH dispatch paths — no display-text parsing.
+      def command_result(cmd, res, duration_ms:)
+        exit_code = res[:exit_code]
+        timed_out = exit_code.to_i == 124
+        status_text = res[:ok] ? "OK" : "EXIT #{exit_code}"
         shell_tag = res[:shell] ? " (#{res[:shell]})" : ""
-        out = "[#{status}]#{shell_tag} #{res[:output]}"
+        out = "[#{status_text}]#{shell_tag} #{res[:output]}"
         out += "\n#{res[:isolation]}" if res[:isolation]
 
+        diagnostic = nil
         unless res[:ok]
           require_relative "../../runtime/diagnostic_engine" unless defined?(Rubik::Runtime::DiagnosticEngine)
-          diag = Rubik::Runtime::DiagnosticEngine.analyze_process_result(res, cmd: cmd)
-          out += "\n\n#{diag.format_for_llm}" if diag
+          diagnostic = Rubik::Runtime::DiagnosticEngine.analyze_process_result(res, cmd: cmd)
+          out += "\n\n#{diagnostic.format_for_llm}" if diagnostic
         end
-        out
-      rescue Rubik::Security::BlockedWriteError => e
-        # Prefix stays first: StepExecutor::ERROR_PREFIXES classifies by start_with?.
-        ToolOutput.error(Rubik::Tools::RunCommandTool.blocked_guidance(e))
-      rescue StandardError => e
-        ToolOutput.error("Command error: #{e.message}")
-      end
 
-      # Stable public seam (RunCommandTool#execute, ManageTaskTool, tests and
-      # dev/review_fix_check call it). The renderer lives in the security
-      # domain next to the error it renders: Rubik::Security::BlockedGuidance
-      # — also keeps this file under the builtin line budget.
-      def self.blocked_guidance(err)
-        Rubik::Security::BlockedGuidance.render(err)
+        timeout_suffix = timed_out ? " (timed out)" : ""
+        error_message = res[:ok] ? nil : "command exited with status #{exit_code}#{timeout_suffix}"
+
+        Rubik::Tools::Result.new(
+          tool_name: "run_command", status: res[:ok] ? :ok : :error, output: out,
+          error: error_message, exit_code: exit_code, duration_ms: duration_ms,
+          metadata: { "executed" => true, "timed_out" => timed_out,
+                      "diagnostic_category" => diagnostic && diagnostic.category.to_s,
+                      "shell" => res[:shell].to_s, "driver" => res[:driver].to_s }.reject { |_k, v| v.nil? || v == "" }
+        )
       end
     end
 

data/lib/rubik/tools/builtins/files.rb

@@ -19,7 +19,12 @@ module Rubik
           type: "object",
           properties: {
             path: { type: "string", description: "File path, or virtual rubik:// URI: 'rubik://storage/<project>/<type>/<id>' " \
-                                                 "(browse from 'rubik://storage/index'), 'rubik://goal/state', 'rubik://subagent/<id>/transcript'" },
+                                                 "(browse from 'rubik://storage/index'), 'rubik://goal/state', " \
+                                                 "'rubik://subagent/<storage-id>/transcript' (the UNIQUE storage id from " \
+                                                 "manage_subagents status 'transcript_ref' or wait rows — live while running, " \
+                                                 "persisted after the first save; a display id like 'subagent-2' or a disk path " \
+                                                 "is NOT a transcript address), 'rubik://subagent/<storage-id>/result[/<run>]' " \
+                                                 "(retained completed results)" },
             offset: { type: "integer", description: "1-based line number to start reading from (optional)" },
             limit: { type: "integer", description: "Maximum number of lines to read (optional)" },
             from_disk: { type: "boolean", description: "Read current disk content without modifying in-memory buffer" },

data/lib/rubik/tools/builtins/subagent.rb

@@ -49,6 +49,8 @@ module Rubik
                   workspace: { type: "string", enum: ["inherit", "branch", "share"], description: "Isolation mode" },
                   model: { type: "string", enum: ["inherit", "flash_lite", "flash", "pro"], description: "Model tier" },
                   max_steps: { type: "integer", description: "Step budget for subagent execution (default: #{steps_default})" },
+                  detach: { type: "boolean", description: "true = this subagent is NOT owned by the current task: a foreground " \
+                                                          "interrupt (^C) will not stop it (default: false)" },
                   depends_on: { type: "array", description: "Dispatch constraints: ['subagent-1'] = FS (launch after it completes); " \
                                                             "{'id': 'subagent-1', 'type': 'SS'} = launch when it starts. Queued specs hold no slot until released." }
                 },
@@ -58,7 +60,8 @@ module Rubik
             role: { type: "string", description: "Role for single subagent invocation" },
             prompt: { type: "string", description: "Prompt for single subagent invocation" },
             type_name: { type: "string", description: "Archetype: 'research', 'coder', or 'self'" },
-            max_steps: { type: "integer", description: "Step budget for single subagent invocation (default: #{steps_default})" }
+            max_steps: { type: "integer", description: "Step budget for single subagent invocation (default: #{steps_default})" },
+            detach: { type: "boolean", description: "true = single-spawn variant of the detach flag above" }
           }
         }
       end
@@ -87,14 +90,22 @@ module Rubik
         specs = extract_subagent_specs(args)
         return ToolOutput.error("No valid subagents specified to invoke.") if specs.empty?
 
+        # Task ownership (issue #125): the spawning context's token owns the new
+        # work (detached specs opt out per spec). Resolved at call time, so a
+        # nested subagent inherits its ancestor's task through its child ctx.
+        owner = Rubik::Coeffects.get(@runtime_context, Rubik::Coeffects::TASK_CANCELLATION)
+
         begin
-          results = sup.spawn_batch(specs)
+          results = sup.spawn_batch(specs, owner: owner)
         rescue StandardError => e
           return ToolOutput.error("Failed to invoke subagent(s): #{e.message}")
         end
 
         launched, queued = results.partition { |outcome, _obj| outcome == :launched }
-        lines = ["Launched #{launched.size} background subagent(s):"] + launched.map { |_o, i| "  • [#{i.id}] '#{i.role}' (#{i.type_name}) - #{i.state.to_s.upcase}" }
+        lines = ["Launched #{launched.size} background subagent(s):"] +
+                launched.map do |_o, i|
+                  "  • [#{i.id}] '#{i.role}' (#{i.type_name}) - #{i.state.to_s.upcase} | transcript: #{i.transcript_ref}"
+                end
         unless queued.empty?
           rows = queued.map { |_o, s| "  • [#{s.id}] '#{s.role}' - QUEUED (waiting on: #{s.depends_on.join(', ')})" }
           lines << ("\nQueued #{queued.size} subagent(s) on unmet dependencies (no slot, no cost until released): " + rows.join("\n"))
@@ -120,6 +131,7 @@ module Rubik
           type_name: args["type_name"] || args[:type_name], role: role, prompt: prompt,
           system_prompt: args["system_prompt"] || args[:system_prompt], workspace: args["workspace"] || args[:workspace] || "inherit",
           model: args["model"] || args[:model] || "inherit", max_steps: args["max_steps"] || args[:max_steps],
+          detach: args["detach"] || args[:detach],
           depends_on: args["depends_on"] || args[:depends_on]
         )]
       end
@@ -158,7 +170,15 @@ module Rubik
             timeout: { type: "integer", description: "Max seconds to wait for actions 'wait' or 'status' if running " \
                                                      "(default: #{Rubik::Orchestrator::Subagent::Notices::DEFAULT_WAIT_TIMEOUT} for wait)" },
             conversation_ids: { type: "array", items: { type: "string" }, description: "IDs of subagents to manage/wait" },
-            conversation_id: { type: "string", description: "Single subagent ID" },
+            conversation_id: { type: "string", description: "Single subagent ID (display id; actions 'transcript'/'result' also " \
+                                                            "accept the unique storage id — the only valid transcript address)" },
+            run: { type: "integer", description: "Run sequence for action 'result' (default: latest retained run)" },
+            cursor: { type: "integer", description: "Character offset for 'result'/'transcript' pagination (default: 0)" },
+            limit: { type: "integer", description: "Max characters per page for 'result'/'transcript' " \
+                                                   "(defaults: #{Rubik::Orchestrator::Subagent::ResultArchive::DEFAULT_PAGE_CHARS} / " \
+                                                   "#{Rubik::Orchestrator::Subagent::TranscriptReader::DEFAULT_PAGE_CHARS})" },
+            snapshot: { type: "string", description: "Snapshot token from a previous 'transcript' page — pins the page " \
+                                                     "sequence; a transcript changed since that snapshot answers explicitly" },
             prompt: { type: "string", description: "New task text for action 'redeploy'" },
             steps: { type: "integer", description: "Additional steps (extend_budget) or redeploy budget" }
           },
@@ -189,12 +209,16 @@ module Rubik
           return ToolOutput.error("Subagent '#{id}' not found.") unless inst
 
           timeout = (args["timeout"] || args[:timeout]).to_i
+          wait_reason = nil
           if timeout.positive? && inst.running?
-            sup.wait_for([id], timeout: timeout)
+            outcome = sup.respond_to?(:wait) ? sup.wait([id], timeout: timeout) : nil
+            sup.wait_for([id], timeout: timeout) unless outcome
+            wait_reason = outcome&.reason
             inst = sup.get(id) || inst
           end
 
           data = inst.to_h
+          data[:wait_reason] = wait_reason if wait_reason
           guidance = Rubik::Orchestrator::Subagent::Narration.guidance(inst.state, id: inst.id, max_steps: inst.max_steps)
           if guidance
             data[:guidance] = guidance
@@ -205,28 +229,11 @@ module Rubik
           end
           JSON.pretty_generate(data)
         when "wait"
-          timeout = [(args["timeout"] || args[:timeout] || Rubik::Orchestrator::Subagent::Notices::DEFAULT_WAIT_TIMEOUT).to_i, 1].max
-          ids = resolve_ids(args) # empty = wait for ALL (wait_any_hint contract)
-          results = sup.wait_for(ids, timeout: timeout)
-          return "No active subagents to wait for.#{unknown_ids_hint(sup, ids)}" if results.empty?
-
-          lines = ["Subagents wait finished (#{results.size} tracked):"]
-          results.each do |r|
-            lines << "  • [#{r[:id]}] '#{r[:role]}' (#{r[:type]}) - #{r[:state].to_s.upcase}"
-            res = (r[:result] || r[:result_summary]).to_s.strip
-            lines << "    #{truncated_result_line(res, r)}" unless res.empty?
-            lines << "    Guidance: #{guidance}" if (guidance = Rubik::Orchestrator::Subagent::Narration.guidance(r[:state], id: r[:id], max_steps: r[:max_steps]))
-          end
-          lines.join("\n")
+          wait_action(sup, args)
         when "transcript"
-          id = resolve_id(args)
-          return ToolOutput.error("Missing required parameter 'conversation_id' for action 'transcript'.") if id.empty?
-
-          inst = sup.get(id)
-          return ToolOutput.error("Subagent '#{id}' not found.") unless inst
-          return ToolOutput.error("Subagent '#{id}' is #{inst.state} — no transcript yet.") unless inst.respond_to?(:format_transcript)
-
-          inst.format_transcript
+          transcript_action(sup, args)
+        when "result"
+          result_action(sup, args)
         when "extend_budget"
           id = resolve_id(args)
           return ToolOutput.error("Missing required parameter 'conversation_id' for action 'extend_budget'.") if id.empty?
@@ -296,14 +303,15 @@ module Rubik
         missing.empty? ? "" : " Unknown id(s): #{missing.join(', ')}.#{id_format_hint}"
       end
 
-      # Truncation hands the model the DIRECT read path (transcript URI) —
-      # session review B10: retrieving the full report cost an extra call.
-      # Returns the line WITHOUT indentation; the caller adds the prefix.
+      # Truncation hands the model the CANONICAL retained-result reference
+      # (issue #122) — a read route that never touches the workspace gate;
+      # the live transcript action stays the fallback when no result
+      # reference exists. Returns the line WITHOUT indentation.
       def truncated_result_line(res, row)
         return "Result: #{res}" if res.length <= 1500
 
-        uri = row[:transcript].to_s
-        more = uri.empty? ? "manage_subagents(action: 'transcript', conversation_id: '#{row[:id]}')" : "read_file(path: '#{uri}')"
+        ref = row[:result_ref].to_s
+        more = ref.empty? ? "manage_subagents(action: 'transcript', conversation_id: '#{row[:id]}')" : "read_file(path: '#{ref}')"
         "Result: #{res[0, 1500]}... [truncated — full result: #{more}]"
       end
     end

data/lib/rubik/tools/builtins/subagent_lifecycle.rb

@@ -4,6 +4,8 @@ require_relative "../output"
 require_relative "../../orchestrator/subagent/budget"
 require_relative "../../orchestrator/subagent/notices"
 require_relative "../../orchestrator/subagent/narration"
+require_relative "../../orchestrator/subagent/result_archive"
+require_relative "../../orchestrator/subagent/transcript_reader"
 
 module Rubik
   module Tools
@@ -37,6 +39,78 @@ module Rubik
           "transcripts remain readable via their transcript URIs and rubik://storage search."
       end
 
+      # The wait surface (issue #126): rows keep the per-execution story
+      # (state, truncated result + canonical reference, guidance) and the
+      # header now names WHY the wait returned, with an actionable hint for
+      # every non-settled reason (deadline / pause / dependency queue / unknown
+      # ids) — a timeout no longer reads as a mystery.
+      def wait_action(sup, args)
+        timeout = [(args["timeout"] || args[:timeout] || Rubik::Orchestrator::Subagent::Notices::DEFAULT_WAIT_TIMEOUT).to_i, 1].max
+        ids = resolve_ids(args) # empty = wait for ALL (wait_any_hint contract)
+        outcome = sup.respond_to?(:wait) ? sup.wait(ids, timeout: timeout) : nil
+        results = outcome ? outcome.rows : sup.wait_for(ids, timeout: timeout)
+        return "No active subagents to wait for.#{unknown_ids_hint(sup, ids)}" if results.empty?
+
+        reason_suffix = outcome ? " — wait reason: #{outcome.reason}" : ""
+        lines = ["Subagents wait finished (#{results.size} tracked)#{reason_suffix}:"]
+        if outcome && (hint = Rubik::Orchestrator::Subagent::Narration.wait_reason_hint(outcome.reason))
+          lines << "  #{hint}"
+        end
+        results.each do |r|
+          lines << "  • [#{r[:id]}] '#{r[:role]}' (#{r[:type]}) - #{r[:state].to_s.upcase}"
+          res = (r[:result] || r[:result_summary]).to_s.strip
+          lines << "    #{truncated_result_line(res, r)}" unless res.empty?
+          guidance = Rubik::Orchestrator::Subagent::Narration.guidance(r[:state], id: r[:id], max_steps: r[:max_steps])
+          lines << "    Guidance: #{guidance}" if guidance
+        end
+        lines.join("\n")
+      end
+
+      # Canonical transcript read (issue #123): the supervisor seam serves the
+      # live memory snapshot while the execution is active and the persisted
+      # snapshot once available — one address, snapshot-stable pages. Accepts
+      # the display id or the raw storage id (after reaping/eviction); unknown,
+      # pending and expired executions answer distinctly.
+      def transcript_action(sup, args)
+        id = resolve_id(args)
+        return ToolOutput.error("Missing required parameter 'conversation_id' for action 'transcript'.") if id.empty?
+        return ToolOutput.error("Canonical transcript reads require the supervisor transcript seam; this runtime has none.") unless sup.respond_to?(:read_transcript)
+
+        inst = sup.get(id)
+        if inst.respond_to?(:queued?) && inst.queued?
+          return ToolOutput.error("Subagent '#{id}' is QUEUED (waiting on dependencies) — no transcript exists until it is released and runs.")
+        end
+
+        storage_id = inst.respond_to?(:storage_id) && inst.storage_id ? inst.storage_id : id
+        page = sup.read_transcript(storage_id,
+                                   cursor: args["cursor"] || args[:cursor],
+                                   limit: args["limit"] || args[:limit],
+                                   snapshot: args["snapshot"] || args[:snapshot])
+        page.ok? ? Rubik::Orchestrator::Subagent::TranscriptReader.render_page(page, id: id) : ToolOutput.error(page.message)
+      end
+
+      # Paginated retained-result read (issue #122): the archive serves a
+      # settled run's full result in bounded pages without a redeploy, a model
+      # call, or any execution-state change. Accepts the display id (roster or
+      # tombstone lookup) or the raw unique storage id (post-reap), plus an
+      # optional run/cursor/limit; unknown and expired references answer
+      # explicitly instead of guessing another run.
+      def result_action(sup, args)
+        id = resolve_id(args)
+        return ToolOutput.error("Missing required parameter 'conversation_id' for action 'result'.") if id.empty?
+        return ToolOutput.error("Result archive is not available in this runtime.") unless sup.respond_to?(:result_archive)
+
+        archive = sup.result_archive
+        inst = sup.get(id)
+        storage_id = inst.respond_to?(:storage_id) ? inst.storage_id : nil
+        storage_id ||= id if archive.known?(id)
+        return ToolOutput.error("Subagent '#{id}' not found and no retained result exists for that id.") unless storage_id
+
+        page = archive.read(storage_id: storage_id, run: args["run"] || args[:run],
+                            cursor: args["cursor"] || args[:cursor], limit: args["limit"] || args[:limit])
+        page.ok? ? Rubik::Orchestrator::Subagent::ResultArchive.render_page(page) : ToolOutput.error(page.message)
+      end
+
       # Blocked states that need maestro action before their chain proceeds
       # (bug-llm-timeout-observability ④): a bare JSON list made a stalled
       # subagent indistinguishable from a healthy one at a glance.

data/lib/rubik/tools/fuzzy_matcher.rb

@@ -128,24 +128,39 @@ module Rubik
         # PERF: memoize raw file lines once before loop to avoid re-splitting inside loop on score updates
         f_raw_lines = f_raw.lines
 
+        # PERF: Pre-compute line membership and prefix sum array to prune window evaluations
+        target_set = Set.new(t_lines)
+        pref = Array.new(f_lines.size + 1, 0)
+        f_lines.each_with_index { |l, idx| pref[idx + 1] = pref[idx] + (target_set.include?(l) ? 1 : 0) }
+
         (0...(f_lines.size)).each do |i|
           window_len = [k, f_lines.size - i].min
-          # PERF: Array#[start, len] slice avoids Range object allocation inside hot loop
-          window = f_lines[i, window_len]
-
-          matches, total =
-            if defined?(Diff::LCS) && Diff::LCS.respond_to?(:LCS)
-              [Diff::LCS.LCS(t_lines, window).size, [t_lines.size, window.size].max]
-            else
-              # Fallback line matching
-              [(0...[t_lines.size, window.size].min).count { |idx| t_lines[idx] == window[idx] },
-               [t_lines.size, window.size].max]
-            end
-          score = total.positive? ? (matches.to_f / total) : 0.0
+          total = [k, window_len].max
+
+          overlap_count = pref[i + window_len] - pref[i]
 
           if k == 1 && window_len == 1
-            char_score = similarity_ratio(t_lines.first, window.first)
-            score = [score, char_score].max
+            window_line = f_lines[i]
+            score = if overlap_count == 1
+                      1.0
+                    else
+                      similarity_ratio(t_lines.first, window_line, min_threshold: best_score)
+                    end
+          else
+            # PERF: Upper-bound check — if maximum possible overlap cannot beat best_score, skip LCS
+            next if (overlap_count.to_f / total) <= best_score
+
+            # PERF: Array#[start, len] slice avoids Range object allocation inside hot loop
+            window = f_lines[i, window_len]
+
+            matches =
+              if defined?(Diff::LCS) && Diff::LCS.respond_to?(:LCS)
+                Diff::LCS.LCS(t_lines, window).size
+              else
+                # Fallback line matching
+                (0...[t_lines.size, window.size].min).count { |idx| t_lines[idx] == window[idx] }
+              end
+            score = total.positive? ? (matches.to_f / total) : 0.0
           end
 
           next unless score > best_score

data/lib/rubik/tools/truncator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "English"
+
 module Rubik
   module Tools
     module Truncator
@@ -13,12 +15,27 @@ module Rubik
         # whole downstream pipeline (JSON generation, regex work, token
         # estimation). Scrub exactly once, after the last byteslice.
         str = str.scrub("") unless str.valid_encoding?
-        lines = str.lines
 
         max_c = (max_chars || DEFAULT_MAX_CHARS).to_i
         max_l = (max_lines || DEFAULT_MAX_LINES).to_i
 
-        return { text: str, truncated: false, omitted_lines: 0, omitted_chars: 0 } if str.bytesize <= max_c && lines.size <= max_l
+        # PERF: With the default input separator, calculate the line upper bound
+        # using zero-allocation C-level #count("\n") and short-circuit BEFORE
+        # calling #lines (which allocates an Array of line strings). Keep the
+        # original #lines behavior when callers customize Ruby's global record
+        # separator, since String#lines uses $/ when no separator is supplied.
+        if $INPUT_RECORD_SEPARATOR == "\n"
+          line_bound = if str.empty?
+                         0
+                       elsif str.end_with?("\n")
+                         str.count("\n")
+                       else
+                         str.count("\n") + 1
+                       end
+          return { text: str, truncated: false, omitted_lines: 0, omitted_chars: 0 } if str.bytesize <= max_c && line_bound <= max_l
+        end
+
+        lines = str.lines
 
         strategy_sym = strategy.to_s.downcase.to_sym
 

data/lib/rubik/tools/uri_resolver.rb

@@ -4,8 +4,9 @@ require "monitor"
 require_relative "../uris"
 require_relative "../coeffects"
 require_relative "../orchestrator/subagent/transcript_formatter"
+require_relative "../orchestrator/subagent/transcript_reader"
+require_relative "../orchestrator/subagent/result_archive"
 require_relative "output"
-require_relative "diagnostic_reporter"
 require_relative "../storage"
 
 module Rubik
@@ -115,39 +116,102 @@ module Rubik
         end
       end
 
-      # rubik://subagent/<storage-id>/transcript reads the transcript FILE
-      # directly — never through the buffer manager. The URL must carry the
-      # unique storage dir name: the absolute path advertised by
-      # manage_subagents status and Instance#to_h. A bare display id
-      # ("subagent-1") resolves to a nonexistent dir and returns an honest
-      # not-found — deliberately no glob-newest fallback, which would serve
-      # a previous session's transcript while a live unsaved instance may
-      # exist (the stale-evidence failure mode of 2026-09-27). One route,
-      # one truth. The sandbox workspace gate does not apply: the id is
-      # charset-validated and the path is an internal artifact under the
-      # transcript root, not a user-supplied filesystem location.
+      # rubik://subagent/<storage-id>/transcript[#cursor=N&snapshot=TOK] is
+      # THE canonical transcript reference (issue #123): it resolves the
+      # EXECUTION by its unique storage id and then serves the right source —
+      # a synchronized live memory snapshot while the run is active, the
+      # persisted JSONL snapshot once available — through one interface with
+      # snapshot-stable, bounded pages. The URL must carry the unique storage
+      # dir name (a bare display id is not an address): deliberately no
+      # glob-newest fallback, which would serve a previous session's transcript
+      # while a live instance exists (the stale-evidence failure mode of
+      # 2026-09-27). The sandbox workspace gate does not apply: live reads come
+      # from the supervisor roster, disk reads from the execution's own
+      # storage-id path — never a user-supplied filesystem location.
+      #
+      # rubik://subagent/<storage-id>/result[/<run>] reads the RETAINED RESULT
+      # from the session's ResultArchive (issue #122): memory-only as well, and
+      # no model call or execution state is touched. One scheme owns one
+      # adapter slot, so the grammars dispatch inside here (the
+      # GoalStateAdapter precedent — a second registration would shadow this
+      # one).
       class SubagentTranscriptAdapter
         def match?(uri)
-          Rubik::Uris::SUBAGENT_TRANSCRIPT.match?(uri)
+          Rubik::Uris::SUBAGENT_TRANSCRIPT.match?(uri) || Rubik::Uris::SUBAGENT_RESULT.match?(uri)
         end
 
         def read(uri, ctx:, buffer_manager:)
+          if (result = Rubik::Uris::SUBAGENT_RESULT.match(uri))
+            return read_result(result[1], result[2], ctx: ctx)
+          end
+
           sub_id = uri[Rubik::Uris::SUBAGENT_TRANSCRIPT, 1]
           unless sub_id.match?(/\A[a-zA-Z0-9_-]+\z/)
             return ToolOutput.error("Invalid subagent id: #{sub_id} (allowed: letters, digits, _ and -). Use the " \
                                     "storage-id dir name from the absolute 'transcript' path in manage_subagents status.")
           end
 
-          storage = Rubik::Coeffects.get(ctx, Rubik::Coeffects::STORAGE_STORE)
-          file = Rubik::Orchestrator::Subagent::TranscriptFormatter.resolve(buffer_manager.root_dir, sub_id, storage: storage)
-          return File.read(file) if File.exist?(file)
-
-          ToolOutput.error(DiagnosticReporter.render_file_not_found(file.to_s, candidates: []) +
-                           "\nHint: for a running subagent the live copy is manage_subagents action 'transcript' " \
-                           "(in-memory); the on-disk file appears only after the subagent's first save.")
+          read_transcript(sub_id, uri, ctx: ctx, buffer_manager: buffer_manager)
         rescue StandardError => e
           ToolOutput.error("Transcript read failed: #{e.class}: #{e.message}")
         end
+
+        private
+
+        # Live-or-disk resolution lives in the supervisor seam when one is
+        # wired; a bare construction (no supervisor coeffect) falls back to
+        # the disk snapshot only, exactly as before the live plane existed.
+        def read_transcript(storage_id, uri, ctx:, buffer_manager:)
+          params = fragment_params(uri)
+          supervisor = Rubik::Coeffects.get(ctx, Rubik::Coeffects::SUBAGENT_SUPERVISOR)
+          page =
+            if supervisor.respond_to?(:read_transcript)
+              supervisor.read_transcript(storage_id, cursor: params["cursor"], limit: params["limit"], snapshot: params["snapshot"])
+            else
+              storage = Rubik::Coeffects.get(ctx, Rubik::Coeffects::STORAGE_STORE)
+              Rubik::Orchestrator::Subagent::TranscriptReader.read(
+                storage_id: storage_id, root_dir: buffer_manager.root_dir, storage: storage,
+                cursor: params["cursor"], limit: params["limit"], snapshot: params["snapshot"]
+              )
+            end
+          return ToolOutput.error(page.message) unless page.ok?
+
+          Rubik::Orchestrator::Subagent::TranscriptReader.render_page(page)
+        end
+
+        # Fragment grammar: "#cursor=N&snapshot=TOK" — values are charset-safe
+        # (digits / "live:hex"), so no percent-decoding is needed.
+        def fragment_params(uri)
+          uri.split("#", 2)[1].to_s.split("&").each_with_object({}) do |pair, acc|
+            key, value = pair.split("=", 2)
+            acc[key] = value if key && !key.empty? && value
+          end
+        end
+
+        # The result half of the scheme: resolve the retained page through the
+        # supervisor's archive coeffect, never through the filesystem. Page 1
+        # carries its own continuation hint when more content remains.
+        def read_result(storage_id, run, ctx:)
+          unless storage_id.match?(/\A[a-zA-Z0-9_-]+\z/)
+            return ToolOutput.error("Invalid subagent storage id: #{storage_id} (allowed: letters, digits, _ and -). " \
+                                    "Use the execution-specific reference reported by manage_subagents status/wait.")
+          end
+
+          supervisor = Rubik::Coeffects.get(ctx, Rubik::Coeffects::SUBAGENT_SUPERVISOR)
+          archive = supervisor.respond_to?(:result_archive) ? supervisor.result_archive : nil
+          unless archive
+            return ToolOutput.error("Retained results are not available in this runtime: no subagent supervisor " \
+                                    "with a result archive is wired. Use manage_subagents action 'transcript' for " \
+                                    "the live execution, or wait for a completion notice carrying a result reference.")
+          end
+
+          page = archive.read(storage_id: storage_id, run: run)
+          return ToolOutput.error(page.message) unless page.ok?
+
+          Rubik::Orchestrator::Subagent::ResultArchive.render_page(page)
+        rescue StandardError => e
+          ToolOutput.error("Result read failed: #{e.class}: #{e.message}")
+        end
       end
 
       # rubik://goal/state + rubik://goal/ledger: canlı !goal anlık

data/lib/rubik/uris.rb

@@ -27,6 +27,9 @@ module Rubik
     # /ledger'ı EŞLEMEZ — iki ayrı gramer, tek adapter içinde iç dispatch.
     GOAL_LEDGER = %r{\Arubik://goal/ledger(?:\.xml)?\z}i
     SUBAGENT_TRANSCRIPT = %r{\Arubik://subagent/([^/]+)/transcript(?:\.jsonl)?(?:#.*)?\z}i
+    # Execution-specific retained result (issue #122): capture 1 = unique
+    # storage id, capture 2 = run sequence (nil = latest retained run).
+    SUBAGENT_RESULT = %r{\Arubik://subagent/([^/]+)/result(?:/(\d+))?\z}i
 
     # TranscriptIndexer ref sözleşimi: "subagent-<storage-id>".
     TRANSCRIPT_REF_PREFIX = "subagent-"
@@ -88,6 +91,14 @@ module Rubik
       "#{SCHEME}://#{SUBAGENT}/#{storage_id}/transcript"
     end
 
+    # Execution-specific retained-result reference: run nil = the latest
+    # retained run of that execution (the archive resolves it explicitly).
+    def subagent_result(storage_id, run: nil)
+      seq = run.to_i
+      suffix = seq.positive? ? "/#{seq}" : ""
+      "#{SCHEME}://#{SUBAGENT}/#{storage_id}/result#{suffix}"
+    end
+
     # TranscriptIndexer ref sözleşimi: "subagent-<storage-id>". storage-id
     # kendisi zaten "subagent-" önekli doğar (ör. "subagent-1-12456-...") —
     # öneki körlemesine eklemek çift önekli, çözümlenemez alias üretiyordu

data/lib/rubik/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubik
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end