robot_lab-durable 0.2.1 → 0.2.6

data/docs/index.md

@@ -1,22 +1,25 @@
-# robot_lab-durable
+# robot_lab-durable — Reference Documentation
 
-Cross-session durable learning for the [RobotLab](https://github.com/MadBomber/robot_lab) LLM agent framework.
+Cross-session durable memory for the [RobotLab](https://github.com/MadBomber/robot_lab) LLM agent framework, backed by the [htm gem](https://madbomber.github.io/htm) (PostgreSQL + pgvector).
 
 > [!CAUTION]
 > This gem is under active development. APIs may change without notice.
 
 ## What it provides
 
-- **`Durable::Entry`** — immutable, confidence-tracked knowledge record
-- **`Durable::Store`** — YAML-backed, file-locked per-domain knowledge persistence in `~/.robot_lab/durable/`
-- **`Durable::Reflector`** — promotes session-level learnings into the durable store at end-of-run
-- **`Durable::Learning`** — mixin included into `RobotLab::Robot`; enabled via `learn: true, learn_domain:` constructor params
-- **`RecallKnowledge`** tool — lets robots query the durable store before making decisions
-- **`RecordKnowledge`** tool — lets robots write new knowledge during a session
+- **`Durable::Adapter`** — thin wrapper around an `HTM` instance; scoped to a robot by name. Exposes `record` and `recall` methods plus direct `htm` access.
+- **`Durable::Entry`** — presenter over raw HTM node hashes returned by recall. Provides typed fields.
+- **`Durable::Hook`** — RobotLab hook handler that wires the `Adapter` lifecycle into `around_run` and `on_learn` automatically.
+- **`RecallKnowledge`** tool — lets a robot query its durable memory before answering.
+- **`RecordKnowledge`** tool — lets a robot persist new knowledge during a session.
 
-## Installation
+## Prerequisites
+
+- PostgreSQL with the pgvector extension enabled.
+- The `htm` gem — see documentation at https://madbomber.github.io/htm.
+- The `robot_lab` gem.
 
-Add to your Gemfile:
+## Installation
 
 ```ruby
 gem "robot_lab"
@@ -30,33 +33,235 @@ require "robot_lab"
 require "robot_lab/durable"
 
 robot = RobotLab.build(
-  name: "advisor",
-  system_prompt: "You are a financial advisor that learns from each session.",
-  learn: true,
-  learn_domain: "finance"
+  name:          "advisor",
+  system_prompt: "You are a financial advisor.",
+  local_tools:   [RobotLab::RecallKnowledge, RobotLab::RecordKnowledge]
 )
+robot.on(RobotLab::Durable::Hook)
 
-# RecallKnowledge and RecordKnowledge tools are automatically available.
-# At the end of each run, the Reflector promotes learned facts to
-# ~/.robot_lab/durable/finance.yml for use in future sessions.
 result = robot.run("What do you know about my risk tolerance?")
 puts result.last_text_content
 ```
 
-## Knowledge Persistence
+No `domain:` argument is required. HTM scopes all storage to the robot's `name` automatically.
+
+---
+
+## Adapter API
+
+`Durable::Adapter` is initialised by `Hook#around_run` for each run and stored as a thread-local. It wraps `HTM.new(robot_name: name)`.
+
+| Method | Arguments | Returns | Notes |
+|--------|-----------|---------|-------|
+| `record` | `content:` (String, required), `reasoning:` (String, optional), `category:` (String/Symbol, default `'fact'`) | Integer (HTM node_id) | Calls `htm.remember(content, metadata: { reasoning:, category: })`. HTM deduplicates by SHA-256 content hash — safe to call with the same content multiple times. |
+| `recall` | `query:` (String, required), `limit:` (Integer, default 20), `strategy:` (Symbol, default `:hybrid`) | `Array<Entry>` | Calls `htm.recall(query, limit:, strategy:, raw: true)` then wraps each result in `Entry.from_node`. |
+| `htm` | — | `HTM` instance | Direct access to the underlying HTM object for advanced operations. |
+
+### Accessing the current adapter
+
+```ruby
+adapter = RobotLab::Durable::Hook.current_adapter
+```
+
+Returns the `Adapter` for the current thread, or `nil` when called outside an active `around_run`. Useful for direct access from custom tools or middleware.
+
+### Direct HTM access
+
+```ruby
+adapter = RobotLab::Durable::Hook.current_adapter
+raw_nodes = adapter.htm.recall("risk tolerance", strategy: :vector, raw: true)
+```
+
+Use `adapter.htm` when you need HTM operations not exposed through `Adapter`, such as bulk deletion or direct node inspection.
+
+---
+
+## Entry Fields
+
+`Durable::Entry` is constructed via `Entry.from_node(node)` from a raw HTM node hash. HTM nodes use string keys (not symbols), so `from_node` reads `node['id']`, not `node[:id]`.
+
+| Field | Type | Description | Source in HTM node |
+|-------|------|-------------|--------------------|
+| `node_id` | Integer | Unique identifier for the stored node | `node['id']` |
+| `content` | String | The stored knowledge text | `node['content']` |
+| `reasoning` | String / nil | Optional rationale recorded at write time | `node['metadata']['reasoning']` |
+| `category` | Symbol | Category of knowledge (e.g. `:fact`, `:observation`) | `(node['metadata']['category'] || 'fact').to_sym` |
+| `created_at` | String | Raw timestamp as returned by HTM (e.g. `'2026-05-06T12:00:00Z'`) — not parsed into a `Time` object | `node['created_at']` |
+
+---
+
+## Hook Lifecycle
+
+The `Durable::Hook` handler implements two lifecycle callbacks.
+
+### around_run
+
+1. Reads `ctx.robot.name` from the run context.
+2. Instantiates `Durable::Adapter.new(robot_name: name)`, which in turn creates `HTM.new(robot_name: name)`.
+3. Stores the adapter as a thread-local so tools can reach it via `Hook.current_adapter`.
+4. Yields to execute the actual robot run.
+5. In `ensure`, clears the thread-local adapter so state never leaks to subsequent runs on the same thread.
+
+### on_learn
+
+Fires after each call to `robot.learn(text)`, but only persists when both of these hold:
+
+1. `ctx.stored` is true — `robot.learn` sets this only when the text was actually added to the robot's in-memory `@learnings` list. If `text` is a substring of an existing learning (or vice versa, see `robot.learn`'s dedup rule in `robot_lab` core), `ctx.stored` stays `false` and `on_learn` returns early without recording.
+2. A durable session is active (`Hook.current_adapter` is non-nil).
+
+When both hold, calls:
+
+```ruby
+adapter.record(content: ctx.text, category: :observation)
+```
+
+This persists the learning immediately. HTM's content-hash deduplication ensures that re-seeding the same fact across sessions does not create duplicate entries.
+
+### Enabling the hook
+
+```ruby
+robot.on(RobotLab::Durable::Hook)
+```
+
+No additional context keys are required. HTM scopes storage to the robot name automatically.
+
+---
+
+## Tools
+
+### RecallKnowledge
+
+Allows the LLM to query the robot's durable memory store.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | String | yes | Natural-language description of the decision you are about to make |
+
+`limit` and `strategy` are not exposed as tool parameters — the tool always calls `adapter.recall` with its defaults (`limit: 20`, `strategy: :hybrid`). Use `Hook.current_adapter` directly (see [Adapter API](#adapter-api)) if you need to control those.
+
+Returns formatted text entries (`"[category] content — reasoning"`, one per line, prefixed with `"Relevant past knowledge:"`) when matches are found. Returns `"No relevant past knowledge found for: <query>. When in doubt, skip."` when the recall is empty, or `"No durable session active on this robot."` when no `Hook.current_adapter` is active (e.g. the hook wasn't registered with `robot.on`).
+
+Implementation calls:
+
+```ruby
+Hook.current_adapter.recall(query: query)
+```
+
+### RecordKnowledge
+
+Allows the LLM to persist new knowledge during a session.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | String | yes | The knowledge text to store |
+| `reasoning` | String | yes | Rationale or context for why this is being stored |
+| `category` | String | yes | One of: fact, preference, pattern, correction |
+
+All three are required — neither `param` (which defaults to `required: true`) nor the tool's `execute(content:, reasoning:, category:)` signature declares a default. (The `'fact'` default described in the [Adapter API](#adapter-api) applies only when calling `Adapter#record` directly, not through this tool.)
+
+Returns `"Recorded: <content>"` on success, or `"No durable session active on this robot."` when no `Hook.current_adapter` is active.
+
+Implementation calls:
+
+```ruby
+adapter.record(content: content, reasoning: reasoning, category: category)
+robot.learn(content)
+```
+
+`robot.learn` updates the current session context so the LLM has immediate access to the new knowledge without waiting for the next run. Because HTM deduplicates by content hash, the subsequent `on_learn` callback does not produce a duplicate entry.
+
+---
+
+## HTM Recall Strategies
+
+| Strategy | Mechanism | Best for |
+|----------|-----------|----------|
+| `:hybrid` | Combines vector similarity and full-text scoring | General use — recommended default |
+| `:vector` | Embedding-based cosine similarity (pgvector) | Semantic / conceptual queries where exact keywords are unknown |
+| `:fulltext` | PostgreSQL full-text search (tsvector / tsquery) | Keyword lookup, proper nouns, technical identifiers |
+
+---
+
+## Day Trader Demo
+
+`examples/01_day_trader.rb` demonstrates cross-session durable memory in a quantitative trading context.
+
+It spawns two subprocesses:
+
+- **`[GEN ]`** — GBM (Geometric Brownian Motion) stock price generator.
+- **`[PRED]`** — SMA+EMA ensemble predictor that issues directional forecasts.
+
+Each prediction window receives a GOOD / MISS verdict printed to the terminal. The durable agent accumulates parameter tuning knowledge across sessions: window sizes, smoothing factors, and signal thresholds that worked well in past runs are recalled and applied, improving prediction accuracy over time.
+
+```
+ruby examples/01_day_trader.rb
+```
+
+---
+
+## Migration Guide — v0.2.x to v0.3.0
+
+v0.3.0 replaces the YAML file store, the `Durable::Store` class, the `Durable::Reflector`, the `Durable::Learning` mixin, and the `skip_persist` mechanism with a direct adapter over the `htm` gem. All domain/confidence concepts are gone.
+
+### Gemfile
+
+```ruby
+# Before
+gem "robot_lab-durable"
+
+# After — htm gem is required; ensure PostgreSQL + pgvector are available
+gem "robot_lab-durable"
+gem "htm"
+```
+
+### Registering the hook
+
+```ruby
+# Before (v0.2.x)
+robot.on(RobotLab::Durable::Hook, context: { domain: "finance" })
 
+# After (v0.3.0) — no domain argument; scoped by robot name automatically
+robot.on(RobotLab::Durable::Hook)
 ```
-~/.robot_lab/durable/
-  finance.yml       # per-domain YAML store
-  support.yml
-  ...
+
+### Building a robot
+
+```ruby
+# Before (v0.2.x)
+robot = RobotLab.build(
+  name:         "advisor",
+  system_prompt: "...",
+  learn:        true,
+  learn_domain: "finance"
+)
+
+# After (v0.3.0) — learn: / learn_domain: removed; use tools + hook instead
+robot = RobotLab.build(
+  name:          "advisor",
+  system_prompt: "...",
+  local_tools:   [RobotLab::RecallKnowledge, RobotLab::RecordKnowledge]
+)
+robot.on(RobotLab::Durable::Hook)
 ```
 
-Each entry records `content`, `confidence`, `category`, `domain`, `use_count`, `created_at`, and `updated_at`.
+### Storage location
+
+Before v0.3.0, knowledge was stored as YAML files under `~/.robot_lab/durable/`. In v0.3.0, all knowledge is stored in PostgreSQL via HTM. Existing YAML data is not migrated automatically — if you need to preserve past learnings, insert them into HTM using `adapter.record` before removing the old files.
+
+### Removed classes
+
+The following classes no longer exist and should be removed from any code that references them:
+
+- `Durable::Store`
+- `Durable::Reflector`
+- `Durable::Learning` (mixin)
+- `Hook.skip_persist` block helper
+
+---
 
 ## Links
 
-- [Implementation Plan](superpowers/plans/2026-05-06-durable-learning.md)
-- [Design Spec](superpowers/specs/2026-05-06-durable-learning-design.md)
 - [RobotLab Core](https://github.com/MadBomber/robot_lab)
+- [HTM gem docs](https://madbomber.github.io/htm)
 - [RubyGems](https://rubygems.org/gems/robot_lab-durable)
+- [GitHub](https://github.com/MadBomber/robot_lab-durable)

data/examples/01_day_trader.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Day Trader: subprocess launcher with interleaved prefixed output
+#
+# Spawns the generator and predictor as child processes, reads their
+# stdout in background threads, and prints every line with a color-coded
+# prefix so both streams are visible in a single terminal.
+#
+# [GEN ] lines — amber  — price ticks from the XYZZY generator
+# [PRED] lines — cyan   — predictions, window results, and GOOD/MISS verdicts
+#
+# Ctrl-C forwards SIGINT to both children and shuts everything down.
+#
+# Prerequisites:
+#   Redis server running on localhost:6379
+#   PostgreSQL configured for HTM (see HTM gem setup)
+#
+# Usage (from the robot_lab-durable root):
+#   ruby examples/01_day_trader.rb
+
+require 'open3'
+
+RUBY         = RbConfig.ruby
+EXAMPLES_DIR = File.expand_path("day_trader_lib", __dir__)
+GENERATOR    = File.join(EXAMPLES_DIR, "generator.rb")
+PREDICTOR    = File.join(EXAMPLES_DIR, "predictor.rb")
+
+GEN_COLOR  = "\e[33m"   # amber
+PRED_COLOR = "\e[36m"   # cyan
+RESET      = "\e[0m"
+GEN_LABEL  = "[GEN ] "
+PRED_LABEL = "[PRED] "
+
+def die(msg)
+  warn msg
+  exit 1
+end
+
+[GENERATOR, PREDICTOR].each { |f| die("Missing: #{f}") unless File.exist?(f) }
+
+puts <<~BANNER
+  #{"=" * 62}
+    Day Trader Demo
+    Generator : XYZZY price stream via Redis (5s ticks, GBM model)
+    Predictor : SMA+EMA ensemble tuned by a RobotLab durable agent
+    Feedback  : ✓ GOOD / ✗ MISS verdict on each prediction window
+    Stop      : Ctrl-C
+  #{"=" * 62}
+BANNER
+
+# ── Spawn generator ───────────────────────────────────────────────────────────
+
+_gen_in, gen_out, gen_thread = Open3.popen2e(RUBY, GENERATOR)
+gen_pid = gen_thread.pid
+
+# Give the generator one tick to connect to Redis before the predictor
+# subscribes, avoiding a missed first message.
+sleep 1
+
+# ── Spawn predictor ───────────────────────────────────────────────────────────
+
+_pred_in, pred_out, pred_thread = Open3.popen2e(RUBY, PREDICTOR)
+pred_pid = pred_thread.pid
+
+# ── Ctrl-C: forward SIGINT to both children ───────────────────────────────────
+
+trap("INT") do
+  [gen_pid, pred_pid].each { |pid| Process.kill("INT", pid) rescue nil }
+end
+
+# ── Relay each process's output with a color-coded label ─────────────────────
+
+def relay(io, label, color)
+  Thread.new do
+    io.each_line do |line|
+      $stdout.print "#{color}#{label}#{RESET}#{line}"
+      $stdout.flush
+    end
+  end
+end
+
+t1 = relay(gen_out,  GEN_LABEL,  GEN_COLOR)
+t2 = relay(pred_out, PRED_LABEL, PRED_COLOR)
+
+t1.join
+t2.join
+
+gen_thread.value
+pred_thread.value
+
+puts "\nDay Trader stopped."

data/examples/{33_stock_generator.rb → day_trader_lib/generator.rb}

@@ -1,22 +1,24 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Example 33: XYZZY Stock Price Generator
+# Day Trader: XYZZY Stock Price Generator
 #
 # Publishes fake streaming prices for ticker XYZZY to a Redis channel
 # using Geometric Brownian Motion with occasional volatility regime shifts.
 #
+# Launched by examples/01_day_trader.rb.
+# Can also be run standalone.
+#
 # Prerequisites:
 #   gem install redis
 #   Redis server running on localhost:6379
-#
-# Usage:
-#   ruby examples/33_stock_generator.rb
 
 require "redis"
 require "json"
 require "time"
 
+$stdout.sync = true   # flush every line immediately through the pipe
+
 CHANNEL     = "stock:xyzzy"
 START_PRICE = 100.0
 BASE_VOL    = 0.008   # baseline volatility per tick (~0.8%)

data/examples/{33_stock_predictor.rb → day_trader_lib/predictor.rb}

@@ -1,30 +1,40 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Example 33: XYZZY Stock Price Predictor
+# Day Trader: XYZZY Stock Price Predictor
 #
-# Consumes fake streaming prices for ticker XYZZY from a Redis channel,
-# predicts the high and low over the next price window using an SMA + EMA
-# ensemble, and uses a RobotLab learning robot to tune predictor parameters
-# after each window closes.
+# Subscribes to the XYZZY Redis channel, accumulates ticks into windows,
+# predicts each window's high/low using an SMA+EMA ensemble, and uses a
+# RobotLab durable agent to tune parameters across sessions.
 #
-# Run alongside:
-#   ruby examples/33_stock_generator.rb   (in a separate terminal)
+# After each window closes the predictor prints a GOOD/MISS verdict:
+#   ✓ GOOD  mean prediction error ≤ GOOD_THRESHOLD
+#   ✗ MISS  mean prediction error >  GOOD_THRESHOLD
+#
+# Launched by examples/01_day_trader.rb.
+# Can also be run standalone alongside generator.rb.
 #
 # Prerequisites:
 #   gem install redis
 #   Redis server running on localhost:6379
-#
-# Usage:
-#   ruby examples/33_stock_predictor.rb
+#   PostgreSQL configured for HTM (see HTM gem setup)
+
+$stdout.sync = true   # flush every line immediately through the pipe
+
+$LOAD_PATH.unshift File.expand_path('../../../robot_lab/lib', __dir__)
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
 
 require "robot_lab"
 require "robot_lab/durable"
 require "redis"
 require "json"
 
-CHANNEL     = "stock:xyzzy"
-WINDOW_SIZE = 12  # ticks per prediction window
+DEBUG_MODE = ARGV.delete("--debug")
+RubyLLM.configure { |c| c.log_level = DEBUG_MODE ? Logger::DEBUG : Logger::WARN }
+
+CHANNEL        = "stock:xyzzy"
+WINDOW_SIZE    = 12    # ticks per prediction window
+GOOD_THRESHOLD = 2.00  # mean error (dollars) at or below which a window is GOOD
 
 # ── Mutable predictor parameters ──────────────────────────────────────────────
 
@@ -139,14 +149,12 @@ class AdjustParameters < RobotLab::Tool
 
     clamped = value.to_f.clamp(spec[:min], spec[:max])
     clamped = clamped.round if spec[:integer]
-
     PredictorConfig.send(:"#{parameter}=", clamped)
-
     "Set #{parameter} = #{clamped}. #{reasoning}"
   end
 end
 
-# ── Error metrics ──────────────────────────────────────────────────────────────
+# ── Window evaluation ──────────────────────────────────────────────────────────
 
 WindowResult = Data.define(
   :window_num,
@@ -170,6 +178,17 @@ def evaluate_window(window_num, predicted, actuals)
   )
 end
 
+def print_window_result(result)
+  verdict = result.mean_err <= GOOD_THRESHOLD ? "✓ GOOD" : "✗ MISS"
+  puts "─" * 58
+  puts "Window #{result.window_num}  #{verdict}  " \
+       "mean_err=$#{"%.2f" % result.mean_err}  (threshold $#{"%.2f" % GOOD_THRESHOLD})"
+  puts "  Predicted  h=$%-8.2f  l=$%.2f" % [result.predicted_high, result.predicted_low]
+  puts "  Actual     h=$%-8.2f  l=$%.2f  err h=$%.2f l=$%.2f" % [
+    result.actual_high, result.actual_low, result.high_err, result.low_err
+  ]
+end
+
 def tuner_prompt(result)
   <<~PROMPT
     Window #{result.window_num} just closed.
@@ -193,49 +212,52 @@ end
 
 # ── Main ──────────────────────────────────────────────────────────────────────
 
-puts "=" * 60
+puts "=" * 58
 puts "XYZZY Stock Predictor"
-puts "=" * 60
+puts "=" * 58
 puts "Channel    : #{CHANNEL}"
 puts "Window     : #{WINDOW_SIZE} ticks"
 puts "Model      : SMA + EMA Ensemble with Durable Learning"
 puts "Warmup     : #{PredictorConfig.sma_window} ticks"
-puts "Press Ctrl-C to stop."
-puts "-" * 60
-
-redis      = Redis.new
-prices     = []
-robot      = RobotLab.build(
-               name:          "predictor_tuner",
-               system_prompt: <<~PROMPT,
-                 You are a quantitative analyst tuning an ensemble stock price range
-                 predictor for ticker XYZZY. Each prediction covers the high and low
-                 price over the next #{WINDOW_SIZE} ticks.
-
-                 The ensemble combines a Simple Moving Average (SMA) band and an
-                 Exponential Moving Average (EMA) band. Adjustable parameters:
-
-                   sma_window (3-30 int)         — lookback period for SMA
-                   sma_std_multiplier (0.5-4.0)  — band width relative to SMA stddev
-                   ema_alpha (0.05-0.5)           — EMA smoothing (higher = more reactive)
-                   ema_vol_multiplier (0.5-4.0)   — band width relative to EMA volatility
-                   sma_weight (0.0-1.0)           — SMA share in ensemble (EMA = 1 - weight)
-
-                 Workflow per window:
-                   1. Call RecallKnowledge to check past findings before acting.
-                   2. If the error is clearly too high/low in one direction, adjust the
-                      relevant band multiplier via AdjustParameters.
-                   3. Make at most two adjustments per window to isolate cause and effect.
-                   4. If you observe a reliable pattern, call RecordKnowledge to preserve it.
-                   5. When uncertain, do nothing rather than guess.
-               PROMPT
-               local_tools:   [AdjustParameters],
-               learn:         true,
-               learn_domain:  "xyzzy stock prediction"
-             )
+puts "Good threshold: $#{"%.2f" % GOOD_THRESHOLD} mean error"
+puts "-" * 58
+
+redis = Redis.new
+prices = []
+robot  = RobotLab.build(
+           name:          "predictor_tuner",
+           model:         "gpt-4.1-mini",
+           provider:      :openai,
+           system_prompt: <<~PROMPT,
+             You are a quantitative analyst tuning an ensemble stock price range
+             predictor for ticker XYZZY. Each prediction covers the high and low
+             price over the next #{WINDOW_SIZE} ticks.
+
+             The ensemble combines a Simple Moving Average (SMA) band and an
+             Exponential Moving Average (EMA) band. Adjustable parameters:
+
+               sma_window (3-30 int)         — lookback period for SMA
+               sma_std_multiplier (0.5-4.0)  — band width relative to SMA stddev
+               ema_alpha (0.05-0.5)           — EMA smoothing (higher = more reactive)
+               ema_vol_multiplier (0.5-4.0)   — band width relative to EMA volatility
+               sma_weight (0.0-1.0)           — SMA share in ensemble (EMA = 1 - weight)
+
+             Workflow per window:
+               1. Call RecallKnowledge to check past findings before acting.
+               2. If the error is clearly too high/low in one direction, adjust the
+                  relevant band multiplier via AdjustParameters.
+               3. Make at most two adjustments per window to isolate cause and effect.
+               4. If you observe a reliable pattern, call RecordKnowledge to preserve it.
+               5. When uncertain, do nothing rather than guess.
+           PROMPT
+           local_tools: [AdjustParameters,
+                         RobotLab::RecallKnowledge,
+                         RobotLab::RecordKnowledge]
+         )
+robot.on(RobotLab::Durable::Hook)
 
 warmed_up    = false
-pending_pred = nil  # { prediction: {high:, low:}, window_prices: [] }
+pending_pred = nil
 window_num   = 0
 
 trap("INT") { puts "\nPredictor stopped."; exit }
@@ -251,7 +273,7 @@ redis.subscribe(CHANNEL) do |on|
     EMAPredictor.update(price)
     prices << price
 
-    # ── Warmup phase ──────────────────────────────────────────────
+    # ── Warmup phase ────────────────────────────────────────────────────────
     unless warmed_up
       if prices.size < PredictorConfig.sma_window
         puts "Tick %5d  $%8.2f  [warming up %d/%d]" % [tick, price, prices.size, PredictorConfig.sma_window]
@@ -261,44 +283,41 @@ redis.subscribe(CHANNEL) do |on|
       warmed_up    = true
       pred         = EnsemblePredictor.predict(prices)
       pending_pred = { prediction: pred, window_prices: [] }
-
-      puts "Tick %5d  $%8.2f  [warmup done]" % [tick, price]
-      puts "  First prediction → high=$#{pred[:high]}  low=$#{pred[:low]}"
+      puts "Tick %5d  $%8.2f  [warmup done — first window open]" % [tick, price]
+      puts "  First prediction → h=$#{pred[:high]}  l=$#{pred[:low]}"
       next
     end
 
-    # ── Accumulate current window ──────────────────────────────────
+    # ── Accumulate current window ──────────────────────────────────────────
     pending_pred[:window_prices] << price
     progress = pending_pred[:window_prices].size
     pred     = pending_pred[:prediction]
 
-    puts "Tick %5d  $%8.2f  [%2d/#{WINDOW_SIZE}]  (pred high=$#{pred[:high]} low=$#{pred[:low]})" %
+    puts "Tick %5d  $%8.2f  [%2d/#{WINDOW_SIZE}]  pred h=$#{pred[:high]} l=$#{pred[:low]}" %
          [tick, price, progress]
 
     next unless progress >= WINDOW_SIZE
 
-    # ── Window closed — evaluate ───────────────────────────────────
+    # ── Window closed: evaluate, print verdict, tune ───────────────────────
     window_num += 1
     result = evaluate_window(window_num, pred, pending_pred[:window_prices])
 
-    puts "\n#{"─" * 60}"
-    puts "  Window #{result.window_num} result:"
-    puts "    Predicted  high=$%-8.2f  low=$%-.2f" % [result.predicted_high, result.predicted_low]
-    puts "    Actual     high=$%-8.2f  low=$%-.2f" % [result.actual_high, result.actual_low]
-    puts "    Error      high=%-8.2f  low=%-8.2f  mean=%.2f" % [result.high_err, result.low_err, result.mean_err]
-    puts "#{"─" * 60}"
-
-    print "  [tuner] analyzing window #{window_num}..."
-    tuner_response = robot.run(tuner_prompt(result))
-    tuner_line     = tuner_response.reply.lines.first&.chomp || "(no response)"
-    puts "\r  [tuner] #{tuner_line}#{" " * 20}"
+    print_window_result(result)
+
+    puts "  Tuning..."
+    begin
+      tuner_response = robot.run(tuner_prompt(result))
+      tuner_line     = tuner_response.reply.lines.first&.chomp || "(no response)"
+      puts "  → #{tuner_line}"
+    rescue StandardError => e
+      puts "  → Tuning skipped: #{e.message.lines.first&.chomp}"
+    end
     puts "  Params: #{PredictorConfig.summary}"
-    puts
+    puts "─" * 58
 
-    # ── Start next window ──────────────────────────────────────────
+    # ── Start next window ─────────────────────────────────────────────────
     new_pred     = EnsemblePredictor.predict(prices)
     pending_pred = { prediction: new_pred, window_prices: [] }
-    puts "  Next prediction → high=$#{new_pred[:high]}  low=$#{new_pred[:low]}"
-    puts
+    puts "Next prediction → h=$#{new_pred[:high]}  l=$#{new_pred[:low]}"
   end
 end