insika 0.8.0 → 1.0.1

data/lib/insika/executor.rb

@@ -3,6 +3,7 @@
 require "time"
 require "securerandom"
 require "async/queue"
+require_relative "telemetry/pricing"
 
 module Insika
   # Coordinates execution. It does not build context, decide policy, or talk to
@@ -18,12 +19,15 @@ module Insika
                    session_store:, task_store:, checkpoint_store:,
                    event_stream:, workflow_registry: nil, pending_action_store: nil,
                    capability_registry: nil, tool_catalog: nil, memory_store: nil,
-                   tool_trace_store: nil, settings_store: nil, content_filter_factory: nil,
+                   tool_trace_store: nil, llm_trace_store: nil, model_metrics_store: nil, settings_store: nil, content_filter_factory: nil,
                     delegation_store: nil, channel_delivery: nil, llm: nil,
                     context_trace_store: nil, reliability: nil, media: nil, media_output: nil,
                     grounding_enforcer: nil, cache_series_store: nil,
                     contact_store: nil, followup_store: nil, model_visible_trace_store: nil,
-                    knowledge_store: nil)
+                    knowledge_store: nil, shared_conversations: nil, llm_refresh: nil, pricing: nil)
+      @pricing = pricing || Telemetry::Pricing.from_env
+      @shared_conversations = shared_conversations
+      @shared_turns = {}
       @context_builder = context_builder
       @policy_engine = policy_engine
       @middleware = middleware
@@ -39,6 +43,10 @@ module Insika
       @workflow_registry = workflow_registry # stage 6 of trigger_workflow
       @pending_action_store = pending_action_store # approval gate
       @capability_registry = capability_registry # capability resolution (nil = off)
+      @llm_trace_store = llm_trace_store
+      @model_metrics_store = model_metrics_store
+      # task id -> the running turn's LLM diagnostics, written once when it ends
+      @llm_buffers = {}
       @tool_trace_store = tool_trace_store # tool-call trace for Studio debugging (nil = off)
       # per-turn context breakdown (tokens by category + budget) for the
       # Studio session card. nil = off (no record, zero overhead — parity).
@@ -67,6 +75,10 @@ module Insika
       # process-wide RubyLLM constant (the historic single-graph deployment).
       # Duck-typed: Context#chat and RubyLLM.chat take the same keywords.
       @llm = llm
+      # ->() re-applies the LLM providers authored at runtime when they changed
+      # (LLMConfigurator#refresh), so a key stored through another worker reaches
+      # this one before its next chat. nil = credentials fixed at boot.
+      @llm_refresh = llm_refresh
       # stability for the turn's single agent interaction (WS3): retries /
       # fallback / circuit breaker, all DATA on AgentProfile#reliability.
       # nil = the plain single ask (parity).
@@ -184,6 +196,10 @@ module Insika
     # scans, nothing mines).
     attr_accessor :harvest_engine
 
+    # Insika::MemoryTrim: hands freed malloc memory back to the OS when the worker
+    # goes quiet (a child of the turn supervisor, like the tick). nil = off.
+    attr_accessor :memory_trim
+
     # Forces the long-lived turn supervisor (and its tick/alert/distill/harvest
     # children — see #turn_parent) to start NOW instead of lazily on the first
     # served turn. Without this, a deployment whose only agents are scheduled
@@ -255,6 +271,22 @@ module Insika
       !actor.nil?
     end
 
+    # RubyLLM may query this repeatedly while partitioning pending tools.
+    # Only the persisted, exactly matching operator decision authorizes a call.
+    def approval_decision(task:, turn:, tool:, args:, call_id:)
+      raise Insika::Error, "PendingActionStore is not configured" unless @pending_action_store
+      raise Insika::ValidationError, "approval requires a tool call id" if call_id.to_s.empty?
+
+      action = @pending_action_store.find(native_pending_id(task.id, turn, call_id))
+      return nil unless action
+
+      unless action.kind == PendingActionStore::OPERATOR && action.task_id == task.id.to_s &&
+          action.turn == turn && action.tool == tool.to_s && action.args == Coercion.deep_stringify(args || {})
+        raise Insika::ValidationError, "approval does not match the pending tool call"
+      end
+      { approved: true, rejected: false }[action.status]
+    end
+
     # Approval gate, called by the ToolEnvelope at stage 6 when the
     # tool requires approval. Creates/queries the PendingAction (deterministic id
     # by task+turn+tool — per-tool correlation as with the side-effect),
@@ -281,6 +313,7 @@ module Insika
       end
 
       @task_store.transition(task.id, to: :waiting) if @task_store.find(task.id).status == :running
+      flush_llm_diagnostics(task) # the wait may last hours
 
       # Awaits the resolution of THIS pending. A spurious :approval (duplicate or
       # from another pending of the same actor) that wakes up before resolution is
@@ -349,12 +382,25 @@ module Insika
       return nil unless @supervised && session_id
 
       policy = queue_policy(profile, session_id)
-      return nil unless policy.collect? && policy.debounce?
+      # The MODE is the whole gate. `debounce_ms` used to be required here too,
+      # which made "the message arrived before the turn started" mean only "inside a
+      # window an operator configured": a burst landing on a turn already queued
+      # behind another joined nothing and became a third turn. A window still
+      # widens the door (it holds the turn at the front of the FIFO); it no longer
+      # is the door.
+      return nil unless policy.collect?
 
       actor = @session_actors[session_id]
       return nil unless actor&.alive?
 
-      actor.collect(text)
+      # FRAMED, like the steer door does at `SteerInjector#absorb_pending!`. The two
+      # doors used to disagree: a steered message became its OWN `user` message in the
+      # transcript (so the model saw a separate ask) while a merged one was concatenated
+      # into the queued turn's single payload by a bare "\n" — five customer messages
+      # arrived as one run-on paragraph, and a trailing constraint got answered by
+      # nothing. `steer_join` is the knob that already exists for exactly this, and a
+      # nil one returns the text untouched, so a wiring that never set it is unchanged.
+      actor.collect(policy.frame(text))
     end
 
     # the `steer` door: a message for a session whose turn is ALREADY
@@ -376,8 +422,8 @@ module Insika
       return nil unless session_actor&.alive?
 
       # No turn running (or one still at the door): there is nothing to steer INTO.
-      # A turn at the door is the collect door's other window — a steer agent with a
-      # debounce merges there instead , so no message waits on either.
+      # A turn at the door is the collect door's business — a steer agent merges
+      # there instead (`collect?` is true for :steer), so no message waits on either.
       task = session_actor.current_task
       return nil if task.nil?
       # A workflow turn orchestrates RubyLLM itself and has no Insika chat to append to
@@ -503,10 +549,9 @@ module Insika
       fail_spawn(task, e)
     end
 
-    # Shuts down all SessionActors (server shutdown / tests — the loop blocks
-    # forever on dequeue when idle).
+    # Shuts down all SessionActors (server shutdown / tests).
     def stop_session_actors
-      @session_actors.each_value(&:stop)
+      @session_actors.values.each(&:stop)
       @session_actors.clear
       nil
     end
@@ -587,76 +632,104 @@ module Insika
 
     # Stages 2..9. Runs INSIDE the task's fiber.
     def execute(task, profile:, actor:, resume_from: nil, timing: nil)
+      state = nil
+      @llm_buffers[task.id] = []
+      Fiber[TurnTiming::FIBER_KEY] = nil # a failure before run_pipeline has no clock of its own
       # Resume of a crash orphan: the interrupted attempt's Execution was left OPEN
       # (the fiber died). The TaskStore forbids opening a second one while one is
       # open -> close the orphan as :interrupted before opening the N+1 (a new
       # entry, never overwrites).
       close_orphan_execution(task) if resume_from
-      @task_store.begin_execution(task.id) # attempt N+1
-      # queued (normal spawn) and paused/waiting (resume) -> running. An orphan is
-      # already :running (running->running is invalid) -> no transition.
-      status = @task_store.find(task.id).status
-      @task_store.transition(task.id, to: :running) if %i[queued paused waiting].include?(status)
+      # attempt N+1, and queued (normal spawn) or paused/waiting (resume) ->
+      # running, in one write. An orphan is already :running and stays so.
+      @task_store.start_execution(task.id)
       emit(:task_started, started_data(task, profile), task: task)
 
+      if profile.respond_to?(:shared_conversations) && profile.shared_conversations
+        @shared_turns[task.id] = { committed: false }
+        raise StoreError, "shared conversation service is not configured" unless @shared_conversations
+        @shared_turns[task.id][:memory] = (profile.memory || profile.knowledge) ? @shared_conversations.memory_context(task:task,profile:profile) : {}
+        @shared_turns[task.id][:history] = if resume_from
+          @shared_conversations.resume_turn(task: task, profile: profile, checkpoint: resume_from)
+        else
+          @shared_conversations.begin_turn(task: task, profile: profile)
+        end
+      end
       actor.drain!
-      run_pipeline(task, profile, actor, resume_from, timing)
+      run_pipeline(task, profile, actor, resume_from, timing) { |current| state = current }
     # SINGLE capture at the top of the fiber: a single place maps
     # error -> terminal state -> events. Stages do no rescue of their own
     # (except tool, RubyLLM semantics). The fiber NEVER re-raises.
+    rescue SharedConversations::Recovered => recovered
+      @shared_turns[task.id][:committed] = true
+      @task_store.complete_execution(task.id, outcome: :completed)
+      emit(:content, {delta: recovered.content}, task: task)
+      recovery_state = TurnState.new(task: task, profile: profile, turn: 1, message: '')
+      recovery_state.evidence_attachments = recovered.attachments
+      finalize_channel_delivery(task, recovered.content, recovery_state, timing)
+      data = {task_id: task.id, content: recovered.content}
+      data[:output_parts] = recovered.output_parts unless recovered.output_parts.empty?
+      emit(:task_completed, data, task: task)
     rescue CancelledError
       # cancel is not an error: transition WITHOUT error: (does not close the
       # Execution), then finish_execution closes it with outcome :cancelled.
       @task_store.transition(task.id, to: :cancelled)
       @task_store.finish_execution(task.id, outcome: :cancelled)
-      emit(:task_cancelled, { task_id: task.id }, task: task)
+      data = { task_id: task.id }
+      data[:usage] = state.usage if state&.usage
+      emit(:task_cancelled, data, task: task)
     rescue PolicyDenied => e
       emit(:policy_denied, { policy: e.policy, reason: e.reason }, task: task)
-      fail_task(task, e, stage: :policy)
+      fail_task(task, e, stage: :policy, usage: state&.usage, profile: profile)
     rescue BudgetExceeded => e
       # WS2 hard budget: a typed, retryable failure — the envelope reads
       # budget_exceeded + retry_after (window roll), never a silent drop.
-      fail_task(task, e, stage: :budget)
+      fail_task(task, e, stage: :budget, usage: state&.usage, profile: profile)
     rescue CircuitOpenError => e
       # WS3 breaker: the turn died BEFORE the provider call — the envelope
       # reads circuit_open + retry_after (cooldown remaining). Worth its own
       # stage: an open breaker is a reliability decision, not an error bug.
-      fail_task(task, e, stage: :reliability)
+      fail_task(task, e, stage: :reliability, usage: state&.usage, profile: profile)
     rescue Insika::RoutingError => e
       # WS4: a route's delegate is missing or its turn failed — an operator
       # config error, staged so the envelope names routing, never :unknown.
-      fail_task(task, e, stage: :routing)
+      fail_task(task, e, stage: :routing, usage: state&.usage, profile: profile)
     rescue Insika::MediaError => e
       # WS9: a voice message that could not be fetched/transcribed (or a media
       # URL the egress guard refused) — heard-loud, never a silent drop.
-      fail_task(task, e, stage: :media)
+      fail_task(task, e, stage: :media, usage: state&.usage, profile: profile)
     rescue Insika::WorkflowSchemaError => e
       # a workflow OUTPUT that violates its output_schema. Distinct
       # stage so a contract breach is not conflated with an :unknown failure. (INPUT
       # is validated synchronously in TriggerWorkflow -> 422, never reaches here.)
-      fail_task(task, e, stage: :workflow_schema)
+      fail_task(task, e, stage: :workflow_schema, usage: state&.usage, profile: profile)
     rescue ContextError => e
-      fail_task(task, e, stage: :context)
+      fail_task(task, e, stage: :context, usage: state&.usage, profile: profile)
     rescue CapabilityError => e
-      fail_task(task, e, stage: :capability)
+      fail_task(task, e, stage: :capability, usage: state&.usage, profile: profile)
     rescue ProviderError => e
-      fail_task(task, e, stage: :ruby_llm)
+      fail_task(task, e, stage: :ruby_llm, usage: state&.usage, profile: profile)
     rescue StoreError => e
-      fail_task(task, e, stage: :persistence)
+      fail_task(task, e, stage: :persistence, usage: state&.usage, profile: profile)
     rescue TimeoutError => e
-      fail_task(task, e, stage: e.stage)
+      fail_task(task, e, stage: e.stage, usage: state&.usage, profile: profile)
     rescue StandardError => e
       # A provider/transport failure is NOT an :unknown bug: wrap it with its
       # action classification (B9) so the envelope can quote retryable and the
       # provider's own retry_after (A8). The classifier is class-name based —
       # the :ruby_llm stage stays reachable even under the smoke-shim's fake.
       if ProviderErrorClassifier.provider_error?(e)
-        fail_task(task, ProviderErrorClassifier.wrap(e), stage: :ruby_llm)
+        fail_task(task, ProviderErrorClassifier.wrap(e), stage: :ruby_llm, usage: state&.usage, profile: profile)
       else
-        fail_task(task, e, stage: :unknown)
+        fail_task(task, e, stage: :unknown, usage: state&.usage, profile: profile)
       end
     ensure
+      @shared_turns.delete(task.id)
+      llm_entries = @llm_buffers.delete(task.id)
       @running.delete(task.id) # ALWAYS deregister (a false-positive running? would break the resume)
+      # after deregistering: the writes may wait on the store, and a resume or an
+      # approve arriving meanwhile must not find a finished turn "running"
+      write_llm_diagnostics(task, llm_entries)
       # Deregistered FIRST on purpose: from here on the `steer` door finds no actor for
       # this session and answers nil, so a message arriving during the release becomes
       # its own turn instead of a post into a mailbox nobody reads again.
@@ -713,7 +786,8 @@ module Insika
       return existing if existing&.alive?
 
       @session_actors[session_id] =
-        SessionActor.new(session_id: session_id, executor: self, parent: turn_parent)
+        SessionActor.new(session_id: session_id, executor: self, parent: turn_parent,
+                         on_idle: ->(actor) { @session_actors.delete(session_id) if @session_actors[session_id].equal?(actor) })
     end
 
     # a turn that arrived while the process is draining: left
@@ -771,6 +845,7 @@ module Insika
       # the harvest engine  lives on the same supervisor — its
       # worker fiber re-scans idle sessions off the turn path.
       @harvest_engine&.start(parent: @supervisor)
+      @memory_trim&.start(parent: @supervisor)
       @supervisor
     end
 
@@ -779,6 +854,7 @@ module Insika
     # than once in a turn collides (the 2nd reuses the 1st's decision) — per-step
     # checkpointing is a future slice. One call per tool is safe.
     def pending_id(task_id, turn, tool) = "#{task_id}:#{turn}:#{tool}"
+    def native_pending_id(task_id, turn, call_id) = "#{task_id}:#{turn}:call:#{call_id}"
 
     # all readings of the persisted command go through rebuild_command
     # (the single normalizer). command_type stays a STRING (the :task_started
@@ -799,7 +875,7 @@ module Insika
     # the open Execution (real TaskStore) — do NOT call finish_execution
     # (double-close). The previous checkpoint is NEVER touched on failure. Never
     # re-raises: the fiber dies clean.
-    def fail_task(task, error, stage:)
+    def fail_task(task, error, stage:, usage: nil, profile: nil)
       # Defense-in-depth: if the task is already terminal (e.g. a failure in
       # cleanup AFTER transition(:completed)), completed->failed is invalid and
       # would raise ArgumentError INSIDE the rescue, leaking from the fiber. In
@@ -820,7 +896,9 @@ module Insika
       spec = { class: error.class.name, message: error.message, stage: stage }
       spec = spec.merge(classification) unless classification.empty?
       @task_store.transition(task.id, to: :failed, error: spec)
+      record_failed_turn(task, profile, usage, stage)
       data = { task_id: task.id, error: error.class.name, message: error.message }
+      data[:usage] = usage if usage
       data = data.merge(classification) unless classification.empty?
       emit(:task_failed, data, task: task)
       # a FAILED delegation child still delivers — the parent
@@ -836,10 +914,10 @@ module Insika
     # turn-timeout wrapping everything via Async::Task#with_timeout — NEVER
     # stdlib Timeout.timeout.
     def run_pipeline(task, profile, actor, resume_from, timing = nil)
-      # a CHANNEL turn always allocates the clock — first_balloon_ms
-      # (inbound -> first outbox flush) is H-latência and must not depend on
-      # INSIKA_TURN_TIMING. When the flag is off the clock measures ONLY that
-      # window (`breakdown: false`); the full prep/ttft/gen/total stays opt-in.
+      # Every turn runs the clock (a few clock reads): its windows become the
+      # turn row in ModelMetricsStore. INSIKA_TURN_TIMING only widens what the
+      # response exposes (`breakdown:`); with it off a channel turn still
+      # reports first_balloon_ms (inbound -> first outbox flush).
       #
       # A channel turn may already carry its clock: `SendMessage` stamped
       # `:inbound` at 202 acceptance (before the debounce window and the
@@ -848,9 +926,11 @@ module Insika
       # engine-initiated) falls back to allocating and stamps now — `mark` is
       # first-write-wins, so a threaded clock is never re-stamped.
       channel_turn = !channel_transport(task).nil?
-      timing ||= if TurnTiming.enabled? || channel_turn
-                   TurnTiming.new(breakdown: TurnTiming.enabled?)
-                 end
+      timing ||= TurnTiming.new(breakdown: TurnTiming.enabled?)
+      # Store calls count into this turn's clock (Stores::TurnCounter). Assigned
+      # even when nil, so a turn without a clock never feeds the previous one's.
+      Fiber[TurnTiming::FIBER_KEY] = timing
+      Fiber[ConfigStore::TURN_KEY] = true # config reads from here on may be cached
       timing&.mark(:inbound) if channel_turn
       timing&.mark(:prep_start)
       state = build_turn_state(task, profile, resume_from)
@@ -863,12 +943,21 @@ module Insika
         # possibly rewritten by before_task). Subject == result == TurnState
         # (the Response content lives in the :done event).
         @hooks.around(:task, state) do |state|
-        prepare_turn(task, profile, state, actor, resume_from) # stages 2-3 (mutates state)
+        yield state if block_given?
+        prepare = ->(st) { prepare_turn(task, profile, st, actor, resume_from) }
+        paid_retrieval = (Coercion.truthy?(profile.knowledge&.dig("retrieve")) && profile.knowledge&.dig("rerank")) ||
+                         (profile.memory && profile.memory_retrieval)
+        middleware_options = if paid_retrieval && @middleware.is_a?(MiddlewareStack)
+                               { prepare: prepare }
+                             else
+                               prepare.call(state)
+                               {}
+                             end
 
         # stage 4: Middleware wraps stages 5-9. A link that
         # short-circuits does NOT call the terminal and sets state.halt_reason.
         terminal_ran = false
-        @middleware.call(state) do |st|
+        @middleware.call(state, **middleware_options) do |st|
           raise Insika::Error, "turn halted: #{st.halt_reason}" if st.halt_reason
 
           terminal_ran = true
@@ -909,10 +998,15 @@ module Insika
       turn = resume_from ? resume_from.turn : 1
       state = TurnState.new(task: task, profile: profile, turn: turn,
                             message: extract_message(task))
+      state.caller_context = extract_caller_context(task)
+      state.shared_conversations = @shared_conversations if @shared_turns[task.id]
       state.tenant = memory_tenant(task) # WRITE-path memory scope (`remember`); =chat
       stamp_customer_session(task, profile)
       state.turn_context = build_turn_context(task, profile, state) # data-tools' ctx.*
       state.resumed = !resume_from.nil? # EdgeLimiter: an admitted turn is never re-counted
+      state.approval_continuation = resume_from&.continuation
+      state.usage = state.approval_continuation&.fetch("usage", nil)&.transform_keys(&:to_sym)
+      state.fence_max_chars = fence_max_chars if Insika::Fence.enabled?(profile)
       # resolved for the RUN, not per message, so what the turn accepts cannot
       # change under it. Same cost as the EdgeLimiter's per-turn resolution. Only for a
       # SESSION turn: steering needs a session to arrive through, and resolving here for a
@@ -924,6 +1018,10 @@ module Insika
       # validator/enforcer read the union, stage 8 flushes.
       state.evidence_ledger = Insika::EvidenceLedger.new(store: @session_store,
                                                          session_id: task.session_id)
+      if (evidence = state.approval_continuation&.fetch("evidence", nil))
+        state.evidence_ledger.record(evidence["ids"])
+        state.evidence_ledger.record_cards(evidence["cards"])
+      end
       state
     end
 
@@ -980,6 +1078,7 @@ module Insika
       # wire the approval gate into the state (the ToolEnvelope reads it at stage 6).
       state.actor = actor
       state.approval_coordinator = self
+      state.pending_action_store = @pending_action_store
       state.requires_approval = resolution.requires_approval
       state.allowed_tools = wrap_tools(assemble_tool_instances(resolution.allowed_tools, state), state, skip)
       state.allowed_skills = resolution.allowed_skills
@@ -1066,7 +1165,7 @@ module Insika
     # approximating RubyLLM's rendering (honest in the doc: the reason's job is
     # the CONTEXT categories; the tool hash is a guard rail).
     def serialize_tools(tools)
-      tools.map { |t| "#{t.name} #{t.description} #{t.parameters.inspect}" }.join(" ")
+      tools.map { |t| "#{t.name} #{t.description} #{t.parameters_schema.inspect}" }.join(" ")
     end
 
     # the stage-8 stamp — the usage (cached_tokens,
@@ -1146,7 +1245,7 @@ module Insika
     # Same yardstick as the fragments (TokenEstimator), so the categories are
     # comparable. `parameters` is not guaranteed JSON-safe — inspect it.
     def estimate_tools_tokens(tools)
-      TokenEstimator.estimate(tools.map { |t| "#{t.name} #{t.description} #{t.parameters.inspect}" }.join(" "))
+      TokenEstimator.estimate(tools.map { |t| "#{t.name} #{t.description} #{t.parameters_schema.inspect}" }.join(" "))
     rescue StandardError
       0
     end
@@ -1200,6 +1299,7 @@ module Insika
       # but is not honored (last stage); :cancel here still raises.
       actor.drain!
       persist_turn(task, profile, st, content, timing: timing)
+      expire_customer_confirmations(task)
 
       # the cache-hit stamp — the usage exists only now. The
       # stamped entry is durable before anything is delivered (same slot as the
@@ -1220,11 +1320,12 @@ module Insika
       # Additive sibling — the answer text stays text on purpose; the channel
       # consumes the parts next to it. Absent when nothing was generated.
       data[:output_parts] = st.output_parts if st.output_parts && !st.output_parts.empty?
-      data[:timing] = timing.to_h if timing # opt-in TTFB breakdown (INSIKA_TURN_TIMING)
+      exposed = timing&.to_h
+      data[:timing] = exposed unless exposed.nil? || exposed.empty? # opt-in TTFB breakdown (INSIKA_TURN_TIMING)
       # best-effort persist of the same timing onto the task record —
       # the Studio task page reads it from there. A failure here must not re-fail
       # the turn (the task is already committed and the event already carries it).
-      persist_turn_timing(task, timing)
+      persist_turn_timing(task, timing, profile, st.usage)
       # WS5: the agent declared it cannot proceed (signal_stuck). The turn still
       # COMPLETES (its final message was published) — but the consumer must be able
       # to act on that, so the contract carries it twice: a dedicated :turn_stuck
@@ -1304,13 +1405,6 @@ module Insika
         # release the redactor's retained tail (a value that never completed into a
         # match is emitted redacted-if-needed, not lost) before reading anything back.
         output.flush
-        # MERGED, not overwritten: a WS4 routing call already banked its tokens in
-        # state.usage before the ask — the classifier's cost must survive the ask
-        # (it feeds the EdgeLimiter's ceiling/budget and the terminal usage).
-        unless halted?(response)
-          state.usage = merge_usage(with_model_source(usage_of(response), state.model_selection),
-                                    state.usage)
-        end
 
         # BOUNDARY BEFORE THE ANSWER GOES OUT. A cancel that arrived while the provider
         # was working used to be observed at stage 8 — AFTER `:content` had already been
@@ -1322,10 +1416,23 @@ module Insika
         # holding a completed answer for an operator would strand it unpublished.
         state.actor&.drain!
 
-        output.publish(turn_answer(response, asked, output, filter))
+        output.publish(without_prompt_echo(state, turn_answer(response, asked, output, filter)))
       end
     end
 
+    # The last gate before the customer reads the answer: a reply that pasted the
+    # system prompt keeps only what came before it (or the safe refusal when that is
+    # nothing). The cut rides :guardrail_flagged like any other, with action "cut".
+    def without_prompt_echo(state, answer)
+      text, echoed = Insika::Safety::PromptEcho.cut(answer, Insika::ModelVisible.instructions_of(state.chat))
+      return answer if echoed.zero?
+
+      state.guardrail_flags = Array(state.guardrail_flags) +
+                              [{ category: "prompt_leak", source: :deterministic, action: "cut",
+                                 detail: "#{echoed} chars of the system prompt removed" }]
+      text.empty? ? Insika::Safety::SafeResponses.for(:injection) : text
+    end
+
     # stage 6, plain path: the single ask on the assembled chat. Fresh TurnOutput
     # + steer wiring per interaction (registered on state.chat, which the solve
     # already assembled). -> { response:, asked:, output: }.
@@ -1336,8 +1443,8 @@ module Insika
       { response: asked, asked: asked, output: output }
     end
 
-    # stage 6, WS3 path: the Reliability coordinator drives retries, backoff,
-    # circuit breaker and the fallback rotation. Each ATTEMPT gets a fresh chat
+    # Native chats own transport retries. Reliability keeps the circuit breaker
+    # and fallback rotation (and retries for non-native integrations). Each rotation gets a fresh chat
     # + output (a failed `ask` leaves its message in the chat, so re-asking the
     # same one would double the input) and, on a fallback, state.model_selection
     # follows — the turn's usage is attributed to the model that actually spoke
@@ -1349,8 +1456,10 @@ module Insika
       attempt_output = nil
       attempt_asked = nil
       primary = state.model_selection
+      # Native transport owns retries per request; the coordinator only rotates models.
+      coordinator_policy = state.chat.is_a?(RubyLLM::Chat) ? policy.merge("retries" => 0) : policy
       response = @reliability.call(
-        policy: policy, tenant: task_tenant(task), agent: state.profile.id.to_s,
+        policy: coordinator_policy, tenant: task_tenant(task), agent: state.profile.id.to_s,
         selection: primary, chain: reliability_chain(state)
       ) do |selection, tries|
         first_attempt = state.chat && selection == primary && tries == 1
@@ -1361,7 +1470,9 @@ module Insika
           chat = build_attempt_chat(state, selection)
           state.chat = chat
         end
+        filter&.flush # Discard the failed stream's retained tail before the next attempt.
         attempt_output = new_turn_output(task, state, filter)
+        configure_reliable_chat(state.chat, policy)
         wire_chat_output(task, state, attempt_output)
         attempt_asked = ask_on(task, state, state.chat, attempt_output, timing)
         attempt_asked
@@ -1369,6 +1480,19 @@ module Insika
       { response: response, asked: attempt_asked, output: attempt_output }
     end
 
+    def configure_reliable_chat(chat, policy)
+      return unless chat.is_a?(RubyLLM::Chat)
+
+      config = (chat.context&.config || RubyLLM.config).dup
+      config.max_retries = [policy["retries"].to_i, 0].max
+      timeout = policy["timeout"].to_i
+      config.request_timeout = timeout.positive? ? timeout : Reliability::DEFAULT_TIMEOUT
+      if policy["backoff"]
+        config.retry_backoff_factor = policy["backoff"] == "exponential" ? 2 : 1
+      end
+      chat.with_context(RubyLLM::Context.new(config))
+    end
+
     # The fallback chain for WS3: profile's `reliability["fallback"]` refs first,
     # then the platform-resolved fallbacks (ModelSelection). Each node is a
     # ModelSelection (the SAME duck the primary is — usage attribution and
@@ -1376,6 +1500,8 @@ module Insika
     # primary. Deduped by ref, primary excluded.
     def reliability_chain(state)
       primary = state.model_selection
+      return [] if primary.pinned?
+
       refs = Array((state.profile.reliability || {})["fallback"]).map(&:to_s)
       nodes = refs.filter_map { |r| parse_model_ref(r) }.reject { |n| n[:model].to_s.empty? }
       nodes.concat(Array(primary.fallbacks).map { |f| { model: f[:model], provider: f[:provider] } })
@@ -1392,6 +1518,19 @@ module Insika
                                       : seen.keys.any? { |known| known.split("/").last == ref }
         next if duplicate
 
+        unless ModelPolicy.allowed?(state.profile.model_policy, model: node[:model], provider: node[:provider])
+          next if node[:provider]
+          next unless Array(ModelPolicy.allow_list(state.profile.model_policy)).any? { |allowed| allowed.to_s.include?("/") }
+
+          begin
+            node[:provider] = RubyLLM.models.find(node[:model]).provider.to_sym
+          rescue RubyLLM::ModelNotFoundError
+            next
+          end
+          next unless ModelPolicy.allowed?(state.profile.model_policy, model: node[:model], provider: node[:provider])
+          ref = model_ref(node)
+        end
+
         seen[ref] = true
         Insika::ModelSelection.new(model: node[:model], provider: node[:provider],
                                    source: :fallback, params: primary.params, fallbacks: [])
@@ -1410,6 +1549,11 @@ module Insika
     # for data/HTTP tools. The engine transports media, never meaning: no
     # speech/vision logic beyond the call itself.
     def run_media_stage(task, state)
+      if state.shared_conversations
+        attachments = state.shared_conversations.input_attachments(task: task)
+        state.media_attachments = attachments unless attachments.empty?
+        return
+      end
       # a consumer that pre-transcribed voice text labels it `source: voice`;
       # the marker rides the turn even when there are no audio PARTS left.
       state.message_source = :voice if rebuild_command(task).payload["source"].to_s == "voice"
@@ -1467,7 +1611,7 @@ module Insika
       transcriber = @media || Insika::Media.default_transcriber(
         stt_model: Insika::EnvSchema.read("INSIKA_STT_MODEL"),
         stt_language: Insika::EnvSchema.read("INSIKA_STT_LANGUAGE"),
-        stt_prompt: resolved_stt_prompt(state.profile)
+        stt_prompt: resolved_stt_prompt(state.profile), context: @llm
       )
       transcriber.call(url)
     end
@@ -1551,8 +1695,9 @@ module Insika
     # "routing", same turn number as the answer ask).
     def route_ask(selection, prompt, message, task, st)
       require "ruby_llm"
-      chat = (@llm || RubyLLM).chat(model: selection.model, provider: selection.provider,
-                                    assume_model_exists: selection.assume_model_exists?)
+      chat = llm_operation_context(st, selection.model, operation: "routing")
+             .chat(model: selection.model, provider: selection.provider,
+                   assume_model_exists: selection.assume_model_exists?)
       chat.with_instructions(prompt) if chat.respond_to?(:with_instructions)
       response = chat.ask(message.to_s)
       record_model_visible(task, st, chat, part: "routing")
@@ -1603,7 +1748,7 @@ module Insika
               "routed delegate '#{agent_id}' at depth #{depth} exceeds cap #{cap}"
       end
 
-      result = spawn_and_await_child(child, state.message, depth, state)
+      result = spawn_and_await_child(child, ask_text(state), depth, state)
       if result[:error]
         raise Insika::RoutingError, "routed delegate '#{agent_id}' failed: #{result[:error]}"
       end
@@ -1617,12 +1762,18 @@ module Insika
     def merge_usage(main, extra)
       return main || extra if main.nil? || extra.nil?
 
-      Insika::Routing::TOKEN_FIELDS.each_with_object(main.dup) do |k, acc|
+      merged = Insika::Routing::TOKEN_FIELDS.each_with_object(extra.merge(main)) do |k, acc|
         next if extra[k].nil?
         next unless main.key?(k) || extra[k].to_i.positive?
 
         acc[k] = main[k].to_i + extra[k].to_i
       end
+      if main.key?(:cost_usd) || extra.key?(:cost_usd)
+        costs = [main[:cost_usd], extra[:cost_usd]]
+        merged[:cost_usd] = costs.sum unless costs.any?(&:nil?)
+        merged[:cost_usd] = nil if costs.any?(&:nil?)
+      end
+      merged
     end
 
     # "provider/model" for any selection duck (ModelSelection | { model:, provider: }).
@@ -1654,7 +1805,7 @@ module Insika
     # state (the seed history is identical), baseline reset -> the transcript
     # recorded from than point is the attempt that spoke.
     def build_attempt_chat(state, selection)
-      chat = build_chat(selection, state.model_selection)
+      chat = build_chat(selection, state.model_selection, state: state)
       @chat_builder.assemble(chat, state, emit: ->(type, data) { emit(type, data, task: state.task) })
       state.chat_baseline = Array(chat.messages).size if chat.respond_to?(:messages)
       chat
@@ -1662,6 +1813,7 @@ module Insika
 
     def new_turn_output(task, state, filter)
       TurnOutput.new(filter: filter, emit: ->(type, data) { emit(type, data, task: task) },
+                     halt_text: state.approval_continuation&.fetch("halt_text", ""),
                      public_intermediate: state.profile.stream_public?(:intermediate))
     end
 
@@ -1670,6 +1822,7 @@ module Insika
     # anything is appended after it — the gem's callbacks are additive and run
     # in registration order.
     def wire_chat_output(task, state, output)
+      state.turn_output = output
       chat = state.chat
       chat.after_message { |message| output.message_ended(message) } if chat.respond_to?(:after_message)
       state.steer_injector = install_steer_injector(task, state)
@@ -1693,16 +1846,10 @@ module Insika
       return if halted?(result[:response])
       return if injector.absorb_pending!.zero?
 
-      # TWO provider round trips now. Bank the first one's tokens BEFORE the response
-      # is replaced — stage 6's merge only sees whatever `result[:response]` ends up
-      # being, so without this the extra round silently erases the first round's cost
-      # from the terminal usage and from the EdgeLimiter's budget.
-      state.usage = merge_usage(with_model_source(usage_of(result[:response]), state.model_selection),
-                                state.usage)
       # COMPLETE, not `ask(nil)`: the messages are already in the history, and an
       # ask with no text appends an EMPTY user message after them — which is both a
       # duplicate turn-opener and something providers refuse outright.
-      extra = state.chat.complete(&turn_chunk_handler(task, state, result[:output], timing))
+      extra = complete_chat(state, state.chat, &turn_chunk_handler(task, state, result[:output], timing))
       result[:response] = extra
       result[:asked] = extra
     end
@@ -1720,12 +1867,150 @@ module Insika
       # An image with no caption asks with NIL, not "": an empty text part is a
       # thing some providers refuse, and nil is how RubyLLM says "attachments
       # only".
-      if state.media_attachments
-        text = state.message.to_s.empty? ? nil : state.message
-        chat.ask(text, with: state.media_attachments, &each_chunk)
+      if state.native_approvals && state.approval_continuation
+        continuation = state.approval_continuation
+        @chat_builder.seed_history(chat, continuation.fetch("messages"))
+        if continuation.key?("halt")
+          close_halted_tool_calls(state, chat)
+          return ToolDefinition::Halt.new(content: continuation["halt"])
+        end
+      elsif state.media_attachments
+        text = ask_text(state)
+        chat.ask_later(text.empty? ? nil : text, with: state.media_attachments)
       else
-        chat.ask(state.message, &each_chunk)
+        chat.ask_later(ask_text(state))
       end
+      complete_chat(state, chat, &each_chunk)
+    end
+
+    def complete_chat(state, chat, &on_chunk)
+      before = usage_of(chat)
+      state.tool_halt = nil
+      response = nil
+      loop do
+        if chat.awaiting_approval?
+          break unless state.native_approvals
+
+          save_approval_continuation(state, chat, before)
+          await_native_approvals(state, chat)
+        end
+        response = chat.step(&on_chunk)
+        recover_text_tool_call(state, chat, response)
+        close_halted_tool_calls(state, chat) if state.native_approvals && state.tool_halt
+        save_approval_continuation(state, chat, before) if state.tool_halt || !chat.complete?
+        break if state.tool_halt || chat.complete?
+      end
+      state.tool_halt || response
+    ensure
+      # Native chat totals include tool rounds and failed provider attempts. Take
+      # a delta because a steered message can continue this same chat once more.
+      usage = chat_usage_since(chat, before, response)
+      state.usage = merge_usage(with_model_source(usage, state.model_selection), state.usage) if usage
+    end
+
+    # The model wrote the call as TEXT (see TextToolCall). Swap that message for the
+    # tool call it meant, BEFORE the loop checks `complete?`: the chat then has a
+    # pending call, the next step runs the tool, and the model answers from the
+    # result. The swapped message is what the session persists, so the markup never
+    # reaches the history. TurnOutput already took the markup as the answer
+    # candidate at the boundary; the message that ends the turn now replaces it.
+    def recover_text_tool_call(state, chat, response)
+      # RubyLLM is required lazily (the load-guard); FakeChat answers plain structs.
+      return unless defined?(RubyLLM::Message) && response.is_a?(RubyLLM::Message)
+      return unless response.role == :assistant && !response.tool_call?
+      return unless chat.messages.last.equal?(response)
+
+      parsed = TextToolCall.parse(response.content, chat.tools.keys.map(&:to_s)) or return
+      calls = parsed[:calls].to_h do |call|
+        id = "call_text_#{SecureRandom.hex(6)}"
+        [id, RubyLLM::ToolCall.new(id: id, name: call[:name], arguments: call[:arguments])]
+      end
+      chat.messages.pop
+      chat.add_message(RubyLLM::Message.new(
+        role: :assistant, content: parsed[:text], tool_calls: calls, model: response.model,
+        tokens: response.tokens, thinking: response.thinking, raw_reasoning: response.raw_reasoning
+      ))
+      names = calls.values.map(&:name)
+      # One line per recovery in the deploy log: it is how the rate of text tool
+      # calls is measured per agent.
+      warn "[insika] text tool call recovered agent=#{state.profile&.id} tools=#{names.join(',')}"
+      emit(:tool_call_recovered, { tools: names }, task: state.task) if state.task
+    end
+
+    def chat_usage_since(chat, before, response = nil)
+      usage = chat.respond_to?(:tokens) ? usage_of(chat) : usage_of(response)
+      if usage
+        if before
+          Insika::Routing::TOKEN_FIELDS.each do |key|
+            usage[key] -= before[key].to_i if usage.key?(key)
+          end
+          if usage[:cost_usd]
+            prior_reported = Insika::Routing::TOKEN_FIELDS.any? { |key| before.key?(key) }
+            usage[:cost_usd] = if before[:cost_usd] || !prior_reported
+                                 usage[:cost_usd] - before[:cost_usd].to_f
+                               end
+          end
+        end
+      end
+      usage
+    end
+
+    # A terminal result can leave approval-gated siblings unanswered. Close them
+    # without executing them so the persisted batch is valid on the next turn.
+    def close_halted_tool_calls(state, chat)
+      index = chat.messages.rindex { |message| message.role == :assistant && message.tool_call? }
+      return unless index
+
+      answered = chat.messages.drop(index + 1).filter_map(&:tool_call_id)
+      chat.messages[index].tool_calls.each_value do |call|
+        action = @pending_action_store&.find(native_pending_id(state.task.id, state.turn, call.id))
+        if action&.status == :pending
+          @pending_action_store.resolve(action.id, decision: :rejected, operator: "engine:halted")
+          emit(:approval_resolved, { pending_id: action.id, decision: :rejected,
+                                    task_id: state.task.id, resolved_by: "engine:halted" }, task: state.task)
+        end
+        next if answered.include?(call.id)
+
+        chat.add_message(role: :tool, tool_call_id: call.id,
+          content: JSON.generate(error: "Tool call not executed because the turn halted."))
+      end
+    end
+
+    def save_approval_continuation(state, chat, before)
+      return unless state.native_approvals
+      return unless state.approval_continuation || state.profile.reliability || chat.tools.values.any?(&:requires_approval?)
+
+      continuation = {
+        "messages" => recorded_turn_messages(state, chat: chat),
+        "tools" => chat.tools.keys.map(&:to_s),
+        "halt_text" => state.turn_output&.halt_text,
+        "usage" => merge_usage(with_model_source(chat_usage_since(chat, before), state.model_selection), state.usage),
+        "evidence" => { "ids" => state.evidence_ledger&.ids, "cards" => state.evidence_ledger&.cards }
+      }
+      continuation["halt"] = state.tool_halt.content if state.tool_halt
+      saved = @checkpoint_store.save_continuation(state.task.id, turn: state.turn, continuation: continuation)
+      state.approval_continuation = saved.continuation
+    end
+
+    def await_native_approvals(state, chat)
+      task = state.task
+      chat.pending_approvals.each do |call|
+        tool = chat.tools[call.name.to_sym]
+        unless tool.respond_to?(:approval_tool_name)
+          raise Insika::Error, "native approval has no Insika tool binding"
+        end
+        name = tool.approval_tool_name
+        approval_decision(task: task, turn: state.turn, tool: name, args: call.arguments, call_id: call.id)
+        id = native_pending_id(task.id, state.turn, call.id)
+        next if @pending_action_store.find(id)
+
+        @pending_action_store.create(id: id, task_id: task.id, session_id: task.session_id,
+          turn: state.turn, tool: name, args: call.arguments)
+        emit(:approval_requested, { pending_id: id, tool: name, args: call.arguments }, task: task)
+      end
+      @task_store.transition(task.id, to: :waiting) if @task_store.find(task.id).status == :running
+      state.actor.await(reason: :approval) while chat.awaiting_approval?
+      @task_store.transition(task.id, to: :running)
     end
 
     # The per-round chunk sink. Built FRESH per round: `ttft_sent` is that round's
@@ -1787,7 +2072,7 @@ module Insika
     # stage, because the `:agent` after-hook runs after the message boundary and is
     # allowed to have the last word.
     def turn_answer(response, asked, output, filter)
-      # HALTED BY A TOOL RESULT (`halt_when`): RubyLLM returns the Tool::Halt itself
+      # HALTED BY A TOOL RESULT (`halt_when`): complete_chat returns the marker
       # instead of a Message, and its `content` is the tool PAYLOAD — publishing it
       # would ship the envelope to the customer as the answer. The turn is worth
       # exactly the lead-in of the message that called the tool (the model's "vou te
@@ -1820,7 +2105,7 @@ module Insika
       Insika::ToolDefinition.halt_say_of(content_of(response)).to_s
     end
 
-    def halted?(response) = response.is_a?(RubyLLM::Tool::Halt)
+    def halted?(response) = response.is_a?(Insika::ToolDefinition::Halt)
 
     def content_of(response) = response.respond_to?(:content) ? response.content : response.to_s
 
@@ -1865,31 +2150,33 @@ module Insika
       return usage if usage.nil? || selection.nil?
 
       usage[:model_source] = selection.source
-      usage[:model] ||= selection.model # falls back to the resolved id when the provider omits it
+      unless usage[:model] # the provider omitted it: the resolved id stands in, and prices it
+        usage[:model] = selection.model
+        usage[:cost_usd] ||= @pricing&.cost(usage)
+      end
+      provider = selection.respond_to?(:provider) ? selection.provider : selection[:provider]
+      usage[:provider] ||= provider.to_s if provider
       usage
     end
 
-    # Token usage of the provider's response (RubyLLM::Message exposes
-    # input_tokens/output_tokens/cached_tokens/model_id). Duck-typed: a provider/
-    # fake with no counting -> nil (nothing to report). Shape compatible with the
-    # OpenAI Responses usage (input/output/total) + model, consumed by
-    # /v1/responses and Telemetry.
+    # Internal buckets are disjoint; total_tokens is the input/output subtotal.
+    # The Responses adapter projects cache-inclusive input/total at the HTTP edge.
+    # Budgets and evals already add the separate cache buckets to this subtotal.
     def usage_of(response)
-      return nil unless response.respond_to?(:input_tokens)
-
-      input = response.input_tokens.to_i
-      output = response.output_tokens.to_i
-      usage = { input_tokens: input, output_tokens: output, total_tokens: input + output }
-      if response.respond_to?(:cached_tokens) && response.cached_tokens
-        usage[:cached_tokens] = response.cached_tokens.to_i # cache_read_input_tokens
-      end
-      # R3: prompt-cache WRITE tokens (Anthropic cache_creation_input_tokens),
-      # billed at ~1.25x. Reported so the first (write) turn vs later (read) turns
-      # are distinguishable in telemetry/usage.
-      if response.respond_to?(:cache_creation_tokens) && response.cache_creation_tokens
-        usage[:cache_creation_tokens] = response.cache_creation_tokens.to_i
+      return nil unless response.respond_to?(:tokens) && (tokens = response.tokens)
+
+      usage = { input_tokens: tokens.input, output_tokens: tokens.output,
+                cached_tokens: tokens.cache_read, cache_creation_tokens: tokens.cache_write }.compact
+      reported = [tokens.input, tokens.output].compact
+      usage[:total_tokens] = reported.sum unless reported.empty?
+      if response.respond_to?(:model) && (model = response.model)
+        usage[:model] = model.respond_to?(:id) ? model.id : model.to_s
       end
-      usage[:model] = response.model_id.to_s if response.respond_to?(:model_id) && response.model_id
+      # Priced per response under ITS model (RubyLLM's cost; the operator table
+      # only when RubyLLM has none), so a turn that summed a failed primary, a
+      # fallback and the router costs each at its own rate.
+      usage[:cost_usd] = response.cost.total if response.respond_to?(:cost)
+      usage[:cost_usd] = @pricing.cost(usage) if usage[:cost_usd].nil? && @pricing
       usage
     end
 
@@ -1905,6 +2192,17 @@ module Insika
       payload["message"] || payload["input"]
     end
 
+    def extract_caller_context(task)
+      text = rebuild_command(task).payload["context"].to_s.strip
+      text.empty? ? nil : text
+    end
+
+    # What the model is asked and the transcript keeps: the caller's context, then
+    # the message. Guardrails scanned `message` alone, before this point.
+    def ask_text(state)
+      [state.caller_context, state.message.to_s].compact.reject(&:empty?).join("\n\n")
+    end
+
     def command_history(task)
       rebuild_command(task).payload["history"]
     end
@@ -1912,19 +2210,27 @@ module Insika
     def build_context_request(task, profile, state, resume_from)
       session = task.session_id ? @session_store.find(task.session_id) : nil
       state.session = session # create_chat reads it for the per-chat model pin
-      hist = command_history(task)
+      hist = @shared_turns.dig(task.id, :history) || command_history(task)
       # `vars` reconciles the seam (the Request/Session provider already
       # called request.vars): session metadata + the explicit `history` in the
       # convention the Session provider consumes (vars["history"]).
       vars = (session&.vars || {}).dup
       vars["history"] = hist if hist
+      vars["shared_memory"] = @shared_turns[task.id][:memory] if @shared_turns[task.id]
       # The single type is Insika::ContextRequest (Data); the explicit `history`
       # travels in vars["history"] (Session provider convention), not in a field
       # of its own. `memory_scope` is the WS8 customer cell (nil = the providers
       # fall back to tenant || session, today's behavior).
+      turn = state.turn
       ContextRequest.new(profile: profile, message: state.message, session: session,
                          checkpoint: resume_from, tenant: command_tenant(task), vars: vars,
-                         memory_scope: memory_tenant(task))
+                         memory_scope: memory_tenant(task),
+                         diagnostics: lambda { |type, data|
+                           if type == :llm_usage && data["operation"] == "rerank"
+                             (state.rerank_usage ||= []) << data
+                           end
+                           emit(type, data.merge("turn" => turn), task: task)
+                         })
     end
 
     # task_started payload. Carries the EXPLICIT command tenant so
@@ -1969,19 +2275,8 @@ module Insika
     # indistinguishable from a single-tenant customer ref, and the Studio drill
     # must not list conversations as customers with a Forget button.
     def memory_tenant(task)
-      customer = command_customer(task)
-      return command_tenant(task) || session_scope(task.session_id) if customer.nil?
-
-      [command_tenant(task), customer].compact.join(":")
-    end
-
-    # The marked per-session scope : "chat:<session id>" -> cell
-    # "memory:chat:<session id>". nil for a one-shot turn (no session) — the
-    # MemoryStore applies _default.
-    def session_scope(session_id)
-      return nil if session_id.nil?
-
-      "#{MemoryStore::SESSION_TAG}:#{session_id}"
+      MemoryStore.scope_for(tenant: command_tenant(task), customer: command_customer(task),
+                            session_id: task.session_id)
     end
 
     # WS8 +  : stamp the customer (WS8 — the `forget_customer`
@@ -1989,16 +2284,22 @@ module Insika
     # distillation engine resolves each session's pack through it) on the
     # session ONCE (idempotent). A session that does not exist yet (no
     # session_id on the turn) is skipped; a look-up failure never breaks the
-    # turn.
+    # turn. The optional labels (SessionStore::CUSTOMER_LABELS: name, phone)
+    # are NOT stamped once: they follow the latest value the caller sends.
     def stamp_customer_session(task, profile)
       customer = command_customer(task)
-      return if customer.nil? || task.session_id.nil?
+      labels = command_customer_labels(task)
+      return if (customer.nil? && labels.empty?) || task.session_id.nil?
 
       session = @session_store&.find(task.session_id)
-      return if session.nil? || !Coercion.presence(session.vars["customer"]).nil?
+      return if session.nil?
 
-      @session_store.update_vars(task.session_id,
-                                 "customer" => customer, "agent" => profile.id)
+      vars = {}
+      if customer && Coercion.presence(session.vars["customer"]).nil?
+        vars.merge!("customer" => customer, "agent" => profile.id)
+      end
+      vars.merge!(labels.reject { |k, v| session.vars[k] == v })
+      @session_store.update_vars(task.session_id, vars) unless vars.empty?
     rescue Insika::NotFoundError, ArgumentError
       nil
     end
@@ -2011,17 +2312,31 @@ module Insika
       Coercion.presence(rebuild_command(task).payload["customer"])
     end
 
+    # The optional labels on the command payload (customer_name, customer_phone):
+    # how the Studio shows and finds the conversation. Only a non-blank String
+    # counts; anything else is ignored.
+    def command_customer_labels(task)
+      payload = rebuild_command(task).payload
+      SessionStore::CUSTOMER_LABELS.filter_map do |key|
+        value = payload[key]
+        value.is_a?(String) && (value = Coercion.presence(value)) ? [key, value] : nil
+      end.to_h
+    end
+
     # Turn context: the ids the data-tools resolve via
     # {{ctx.*}} to emit X-Chat-Id/X-Store-Id/X-Agent-Id to /api/internal/*. They
-    # come from the TURN, never from the model args (R2). chat_id = the session
-    # (the /v1/responses adapter creates the session with id = user = chat.id);
+    # come from the TURN, never from the model args (R2). chat_id is the external
+    # session id, without the server-added tenant namespace;
     # tenant = the Command tenant (memory) OR chat_id (drop-in default); agent_id =
     # profile; store_id = the profile metadata (stable per store, from the pack).
     # Absent fields -> nil (the data-tool emits an empty header; in the pilot the
     # profile carries store_id). Generic: nothing here mentions a consumer.
     def build_turn_context(task, profile, state)
+      tenant = command_tenant(task)
       {
-        chat_id: task.session_id,
+        chat_id: tenant ? task.session_id&.delete_prefix("#{tenant}:") : task.session_id,
+        # the conversation itself — MCP clients are kept per conversation.
+        session_id: task.session_id,
         agent_id: profile.id,
         # the DATA-TOOL header tenant stays the merchant (or the chat), even when
         # the memory scope carries a customer — the backend identifies the store,
@@ -2336,6 +2651,7 @@ module Insika
 
       @task_store.transition(task.id, to: :paused)
       emit(:task_paused, { task_id: task.id }, task: task)
+      flush_llm_diagnostics(task) # the wait may last hours
       actor.await(reason: :paused) # blocks until :resume (or raises on :cancel/:timeout)
       @task_store.transition(task.id, to: :running)
       emit(:task_resumed, { task_id: task.id }, task: task)
@@ -2346,13 +2662,11 @@ module Insika
     # (does not re-save — the CheckpointStore's monotonicity would raise). It emits
     # NO event (:checkpoint_created is stage 8's only) and touches no side-effects.
     def save_initial_checkpoint(task, profile, state)
-      return unless @checkpoint_store.find(task.id, turn: state.turn).nil?
-
       @checkpoint_store.save(Insika::Checkpoint.new(
                                task_id: task.id, turn: state.turn, session_id: task.session_id,
                                agent_id: profile.id, messages: flatten_history(state.context.history),
                                completed_side_effects: [], created_at: Time.now.utc.iso8601
-                             ))
+                             ), if_absent: true)
     end
 
     # GRACEFUL halt: a Middleware short-circuited with a safe reply.
@@ -2384,8 +2698,9 @@ module Insika
       persist_turn(task, profile, state, content, reply_origin: MessageOrigin::ENGINE,
                    session: state.guardrail_block&.[](:source) != "edge", timing: timing)
       data = { task_id: task.id, content: content, usage: state.usage }
-      data[:timing] = timing.to_h if timing # a channel halt still measured
-      persist_turn_timing(task, timing)
+      exposed = timing&.to_h
+      data[:timing] = exposed unless exposed.nil? || exposed.empty? # a channel halt still measured
+      persist_turn_timing(task, timing, profile, state.usage)
       emit(:task_completed, data, task: task)
     end
 
@@ -2393,9 +2708,12 @@ module Insika
     # The record gains `timing` once, when the turn completes; a store failure
     # here is swallowed — the turn is already committed and the event already
     # carries the number.
-    def persist_turn_timing(task, timing)
+    # The full windows also go to ModelMetricsStore as the turn's row (agent,
+    # model, provider), flag or not.
+    def persist_turn_timing(task, timing, profile, usage)
       return unless timing
 
+      record_turn_metrics(task, timing, profile, usage)
       hash = timing.to_h
       return if hash.empty?
 
@@ -2404,6 +2722,28 @@ module Insika
       nil
     end
 
+    def record_turn_metrics(task, timing, profile, usage, status: "completed", stage: nil)
+      return unless @model_metrics_store.respond_to?(:record_turn)
+
+      usage ||= {}
+      @model_metrics_store.record_turn(task_id: task.id, row: timing.metrics.merge(
+        "at" => Time.now.utc.iso8601(6), "agent" => profile.id.to_s, "status" => status,
+        "stage" => stage&.to_s, "model" => usage[:model]&.to_s, "provider" => usage[:provider]&.to_s
+      ).compact)
+    end
+
+    # A failed turn keeps its row too: its total_ms runs to the failure, so a
+    # turn timeout stays in the p95 instead of vanishing from it.
+    def record_failed_turn(task, profile, usage, stage)
+      timing = TurnTiming.current
+      return unless timing && profile
+
+      timing.mark(:done)
+      record_turn_metrics(task, timing, profile, usage, status: "failed", stage: stage)
+    rescue StandardError
+      nil # metrics never fail the failure path
+    end
+
       # Emits one :guardrail_flagged per flag the OutputValidator appended in
       # after_task (audit only — the turn already completed). Reads a plain Array off
       # the state, keeping the Executor decoupled from Safety. an
@@ -2436,9 +2776,27 @@ module Insika
     # So a long session legitimately has a Checkpoint SHORTER than the Session:
     # that is not drift to reconcile — it is the point. Do NOT "fix" the checkpoint
     # to carry the full history (it would defeat the budget) nor evict the session.
+    # A customer confirmation lives for exactly one more customer message: a hold
+    # an EARLIER task of this session left open, and this turn neither confirmed
+    # nor cancelled, is rejected here, once the turn is durable. Fail-closed — a
+    # customer who changed the subject did not agree. Best-effort like the other
+    # stage-8 side writes: a store failure must not re-fail a committed turn.
+    def expire_customer_confirmations(task)
+      return unless @pending_action_store && task.session_id
+
+      expired = @pending_action_store.expire_customer_holds(session_id: task.session_id, except_task_id: task.id)
+      expired.each { |pa| emit(:confirmation_expired, { pending_id: pa.id, tool: pa.tool }, task: task) }
+    rescue StandardError
+      nil
+    end
+
     def persist_turn(task, profile, state, content, session: true, reply_origin: nil, timing: nil)
       new_messages = turn_transcript(state, content, origin: command_origin(task), reply_origin: reply_origin)
-      transcript = flatten_history(state.context.history) + new_messages
+      # Early edge refusal has no built context; retain the existing history in
+      # its checkpoint while keeping the refusal out of the session transcript.
+      history = state.context&.history || command_history(task) ||
+                (task.session_id && @session_store.find(task.session_id)&.messages)
+      transcript = flatten_history(history) + new_messages
 
       @checkpoint_store.save(Insika::Checkpoint.new(
                                task_id: task.id, turn: state.turn + 1, session_id: task.session_id,
@@ -2449,12 +2807,26 @@ module Insika
       # session only when the turn is from a persisted session; one-shot/history
       # do not persist TO THE SESSION (but always checkpoint). `session: false` is
       # the edge-blocked halt (see complete_with_halt).
-      @session_store.append_messages(task.session_id, new_messages) if session && task.session_id
+      # task_id on each persisted message ties it to the turn's traces (the
+      # Studio's "why this reply" reads it); history replay ignores the key.
+      if session && task.session_id
+        @session_store.append_messages(task.session_id, new_messages.map { |m| m.merge("task_id" => task.id) },
+                                       agent: profile.id)
+      end
+
+      if (shared = @shared_turns[task.id])
+        if @pending_action_store && task.session_id
+          @pending_action_store.expire_customer_holds(session_id: task.session_id, except_task_id: task.id)
+        end
+        pending = @pending_action_store && task.session_id && !@pending_action_store.open_for_session(task.session_id).empty?
+        @shared_conversations.complete(task: task, messages: new_messages, pending_approval: !!pending,
+          output_parts: state.output_parts, attachments: delivery_attachments(state))
+        shared[:committed] = true
+        emit(:content, { delta: content }, task: task) unless content.empty?
+      end
 
-      # finish_execution (closes the Execution) BEFORE transition(:completed) —
-      # transition without error: does not close, so the finish is needed here.
-      @task_store.finish_execution(task.id, outcome: :completed)
-      @task_store.transition(task.id, to: :completed)
+      # closes the Execution and moves to :completed in one write.
+      @task_store.complete_execution(task.id, outcome: :completed)
       # prune is best-effort cleanup: a failure here must NOT re-fail an
       # already-committed turn (the task is already :completed and durable).
       # Swallow.
@@ -2480,13 +2852,13 @@ module Insika
       # path — the user already has the answer above. Same terminal hook,
       # next door to the other two, for the same reason: it fires for a fresh
       # turn and a recovered one.
-      finalize_knowledge_extraction(task, profile, new_messages)
+      finalize_knowledge_extraction(task, profile, new_messages, state)
 
       # in-session compaction (RFC-0044): when the uncompacted
       # transcript crossed the threshold this turn, summarize the old prefix
       # with the cheap model and move the boundary — off the critical path,
       # same terminal hook, same best-effort discipline as the other three.
-      finalize_compaction(task, profile)
+      finalize_compaction(task, profile, state.chat)
     end
 
     # Records the answer in the outbox and dispatches it. The discriminator is the
@@ -2515,7 +2887,11 @@ module Insika
 
       # the hoarded evidence attachments ride the channel delivery
       # (additive outbox payload key — the channel contract widens, nothing breaks).
-      attachments = state.respond_to?(:evidence_attachments) ? state.evidence_attachments : nil
+      # When the model SELECTED cards with a presentation tool this turn, the
+      # selection is what rides — in call order, each card stamped with the
+      # component and title of the call that picked it. No selection = every
+      # hoarded card, as before.
+      attachments = delivery_attachments(state)
       deliveries = @channel_delivery.record_balloons(
         task: task, channel_id: channel_id, content: content,
         progressive: @channel_delivery.progressive?(channel_id),
@@ -2529,6 +2905,17 @@ module Insika
       nil
     end
 
+    def delivery_attachments(state)
+      presentations = state.respond_to?(:presentations) ? Array(state.presentations) : []
+      if presentations.empty?
+        return state.respond_to?(:evidence_attachments) ? state.evidence_attachments : nil
+      end
+
+      presentations.flat_map do |p|
+        Array(p["items"]).map { |item| item.merge("component" => p["component"], "title" => p["title"]).compact }
+      end
+    end
+
     # Turns whose combined transcript slice is this trivially short skip
     # extraction entirely ("ok thanks" exchanges) — no new config surface,
     # just avoids a wasted utility-model call.
@@ -2541,22 +2928,27 @@ module Insika
     # boot sweep), a child of the turn supervisor when serving (survives the
     # request's own disconnect). Best-effort: any failure is swallowed here,
     # never re-fails an already-committed turn.
-    def finalize_knowledge_extraction(task, profile, new_messages)
+    def finalize_knowledge_extraction(task, profile, new_messages, state = nil)
       return unless @knowledge_store
+      return if simulated_session?(task.session_id)
 
       config = Coercion.deep_stringify(profile.knowledge)
       return unless config && Coercion.truthy?(config["extract"])
       return if knowledge_transcript(new_messages).length < KNOWLEDGE_MIN_CHARS
 
-      extractor = Knowledge::ExtractorFactory.build(config, utility_model: utility_model)
+      extractor = Knowledge::ExtractorFactory.build(config, utility_model: utility_model,
+                                                    llm: llm_operation_context(state, nil, operation: "knowledge_extract"))
       return unless extractor
 
       # Same resolved model as the extractor — a deployment names one
       # knowledge model, not two. nil consolidator (no model resolvable) is
       # still meaningful: write_concept's conservative default.
-      consolidator = Knowledge::ConsolidatorFactory.build(config, utility_model: utility_model)
+      consolidator = Knowledge::ConsolidatorFactory.build(config, utility_model: utility_model,
+                                                          llm: llm_operation_context(state, nil, operation: "knowledge_consolidate"))
 
-      run = lambda { run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator) }
+      context = state&.context
+      agent_brief = context.respond_to?(:system_identity) ? context.system_identity : nil
+      run = lambda { run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator, agent_brief) }
       return run.call unless @supervised
 
       turn_parent.async do |t|
@@ -2565,10 +2957,17 @@ module Insika
       end
     end
 
-    def run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator)
-      prompt = knowledge_prompt(config, new_messages)
+    def run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator, agent_brief = nil)
+      prompt = knowledge_prompt(config, new_messages, agent_brief)
       result = extractor.extract(prompt: prompt)
       result[:concepts].each do |concept|
+        if profile.shared_conversations
+          redacted, = Safety::Detectors.redact(concept['body'].to_s)
+          @shared_conversations.propose_memory(task:task,id:concept['name'],kind:'knowledge',
+            value:Knowledge.first_sighting(concept,redacted,rebuild_command(task).payload.dig('shared_conversation','conversation_id')))
+          emit(:knowledge_conflict, {name:concept['name'],agent:profile.id}, task:task)
+          next
+        end
         outcome = Knowledge.write_concept(
           store: @knowledge_store, agent_id: profile.id, concept: concept, session_id: task.session_id,
           tenant: task_tenant(task), consolidator: consolidator
@@ -2591,26 +2990,32 @@ module Insika
       end
     end
 
-    def knowledge_prompt(config, new_messages)
+    # Transcripts drop tool results (product cards, search hits), so without the
+    # agent's own identity the extractor guesses the domain: "pode ser importado"
+    # about a perfume became "imported vehicles" for a beauty store.
+    KNOWLEDGE_BRIEF_CHARS = 1500
+
+    def knowledge_prompt(config, new_messages, agent_brief = nil)
       base = Coercion.presence(config["prompt"]) || Knowledge::DEFAULT_PROMPT
+      # ponytail: the head of the identity prompt names the store in our packs; a pack whose prompt
+      # opens elsewhere needs a `knowledge.prompt` that states the domain.
+      brief = Coercion.presence(agent_brief.to_s[0, KNOWLEDGE_BRIEF_CHARS])
+      agent = brief ? "\n## The agent (read for its business domain only)\n\n#{brief}\n" : ""
       <<~PROMPT
         #{base.rstrip}
-
+        #{agent}
         ## The conversation
 
         #{knowledge_transcript(new_messages)}
       PROMPT
     end
 
-    # Redacted (RFC's PII rule applies to what reaches the model too, not
-    # just what gets persisted).
-    def knowledge_transcript(new_messages)
-      redacted, = Insika::Safety::Detectors.redact(
-        new_messages.each_with_index.map { |m, i| "[#{i}] #{m['role'] || m[:role]}: #{m['content'] || m[:content]}" }
-                    .join("\n")
-      )
-      redacted
-    end
+    # Synthetic traffic must not teach the production agent (SessionStore.synthetic?).
+    def simulated_session?(session_id) = Insika::SessionStore.synthetic?(session_id)
+
+    # Only what people said, PII-redacted — a `role: tool` message is
+    # third-party text and never a source of a learned concept.
+    def knowledge_transcript(new_messages) = Insika::SpokenTranscript.render(new_messages)
 
     def utility_model
       return nil unless @settings_store
@@ -2618,6 +3023,14 @@ module Insika
       @settings_store.get["utility_model"]
     end
 
+    # `Settings fencing.max_chars`, the per-leaf cap the envelope applies for a
+    # fenced agent. One settings read per fenced turn, like the queue policy.
+    def fence_max_chars
+      config = @settings_store && Coercion.deep_stringify(@settings_store.get["fencing"])
+      n = config && config["max_chars"].to_i
+      n && n.positive? ? n : Insika::Fence::DEFAULT_MAX_CHARS
+    end
+
     # in-session compaction (RFC-0044). Platform-gated
     # (Settings compaction.enabled — parity when off), planned over the
     # POST-append transcript (persist_turn already wrote this turn's messages),
@@ -2625,7 +3038,7 @@ module Insika
     # finalize_knowledge_extraction: inline when non-supervised, a child of the
     # turn supervisor when serving. Best-effort: any failure leaves the session
     # record untouched and the next turn re-plans.
-    def finalize_compaction(task, profile)
+    def finalize_compaction(task, profile, chat = nil)
       return unless task.session_id && @settings_store
 
       config = Coercion.deep_stringify(@settings_store.get["compaction"])
@@ -2635,16 +3048,29 @@ module Insika
       return unless session
 
       state = session.respond_to?(:compaction) ? session.compaction : nil
+      native = config["mode"] == "native"
+      binding = Compaction.native_binding(chat) if native
+      return if native && !binding
+
+      # A portable summary must start from the original prefix, not an opaque
+      # native marker, when the operator switches compaction modes.
+      state = nil if !native && state && state["native"]
       plan = Insika::Compaction.plan(messages: session.messages, state: state, config: config)
       return unless plan
 
       # compaction.model -> platform utility_model -> inert (never a guess);
       # `insika doctor` warns on enabled-with-no-model. @llm rides along so a
       # deployment (or spec) that injects its LLM seam covers this call too.
-      summarizer = Compaction::SummarizerFactory.build(config, utility_model: utility_model, llm: @llm)
-      return unless summarizer
+      if native
+        run = lambda { run_native_compaction(task, profile, session, plan, chat, binding) }
+      else
+        llm = @llm || (defined?(RubyLLM) && RubyLLM)
+        llm = instrumented_llm(task, nil, operation: "compaction", agent: profile.id) if llm
+        summarizer = Compaction::SummarizerFactory.build(config, utility_model: utility_model, llm: llm)
+        return unless summarizer
 
-      run = lambda { run_compaction(task, profile, session, state, plan, config, summarizer) }
+        run = lambda { run_compaction(task, profile, session, state, plan, config, summarizer) }
+      end
       return run.call unless @supervised
 
       turn_parent.async do |t|
@@ -2653,6 +3079,27 @@ module Insika
       end
     end
 
+    def run_native_compaction(task, profile, session, plan, source, binding)
+      # Rebuild from persisted, filtered messages; never copy the live chat's raw output.
+      chat = source.context.chat(model: source.model.id, provider: binding.fetch("provider"),
+        protocol: :responses, assume_model_exists: true)
+      @chat_builder.seed_history(chat, session.messages.take(plan.upto))
+      message = chat.compact
+      raw = message.raw_content
+      return unless Compaction.native_payload?(raw)
+
+      native = { "binding" => binding, "message" => {
+        "role" => "assistant", "content" => "", "raw_content" => raw
+      } }
+      updated = @session_store.set_compaction(task.session_id, native: native,
+        upto: plan.upto, model: binding.fetch("model"))
+      emit(:context_compacted, { task_id: task.id, agent: profile.id, from: 0, upto: plan.upto,
+        messages: plan.upto, runs: updated.compaction["runs"], model: binding.fetch("model"),
+        usage: usage_of(chat) }, task: task)
+    rescue StandardError
+      nil # A failed compaction cannot fail the already-committed turn.
+    end
+
     def run_compaction(task, profile, session, state, plan, config, summarizer)
       prompt = Insika::Compaction.prompt(messages: session.messages, plan: plan,
                                          previous: state && state["summary"],
@@ -2712,28 +3159,39 @@ module Insika
     def turn_transcript(state, content, origin: nil, reply_origin: nil)
       recorded = recorded_turn_messages(state)
       if recorded.empty?
-        return [MessageOrigin.stamp({ "role" => "user", "content" => state.message.to_s }, origin),
+        return [stamp_guardrail_flags(MessageOrigin.stamp({ "role" => "user", "content" => ask_text(state) }, origin), state),
                 MessageOrigin.stamp({ "role" => "assistant", "content" => content.to_s }, reply_origin)]
       end
 
-      recorded[0] = MessageOrigin.stamp(recorded[0], origin) if recorded[0]["role"] == "user"
+      recorded[0] = stamp_guardrail_flags(MessageOrigin.stamp(recorded[0], origin), state) if recorded[0]["role"] == "user"
       recorded[-1] = recorded[-1].merge("content" => content.to_s) if recorded.last["role"] == "assistant"
       recorded
     end
 
+    # Flags raised on the INCOMING message (the input guardrail runs before the
+    # model; output flags come after persist) ride on that message, so the
+    # transcript shows them after the live event stream is gone. Never sent to the
+    # model: history replay reads role/content/tool_calls only.
+    def stamp_guardrail_flags(message, state)
+      flags = Array(state.guardrail_flags)
+      return message if flags.empty?
+
+      message.merge("guardrail_flags" => flags.map { |f| f.transform_keys(&:to_s) })
+    end
+
     # Slices the chat's messages added DURING this turn and serializes them.
     # [] when there is no recorded transcript (baseline nil / no #messages).
-    def recorded_turn_messages(state)
-      chat = state.chat
+    def recorded_turn_messages(state, chat: state.chat)
       baseline = state.chat_baseline
       return [] unless chat && baseline && chat.respond_to?(:messages)
 
-      Array(chat.messages).drop(baseline).filter_map { |m| serialize_chat_message(m) }
+      Array(chat.messages).drop(baseline).filter_map { |m| serialize_chat_message(m, clip: !(state.task && @shared_turns.key?(state.task.id))) }
     end
 
     # A RubyLLM::Message (duck-typed) -> string-keyed Hash. Assistant carries
     # "tool_calls" only when present; tool carries "tool_call_id" + a clipped content.
-    def serialize_chat_message(msg)
+    # Do not persist raw_content: native replay would bypass redaction and clipping.
+    def serialize_chat_message(msg, clip: true)
       role = msg_field(msg, :role).to_s
       content = msg_field(msg, :content).to_s
       case role
@@ -2744,7 +3202,7 @@ module Insika
         h
       when "tool"
         { "role" => "tool", "tool_call_id" => msg_field(msg, :tool_call_id).to_s,
-          "content" => clip_tool_content(content) }
+          "content" => clip ? clip_tool_content(content) : content }
       else
         { "role" => role, "content" => content }
       end
@@ -2793,6 +3251,7 @@ module Insika
       require_relative "tools/load_knowledge"
       require_relative "tools/tool_search"
       require_relative "tools/remember"
+      require_relative "tools/confirm_pending"
       require_relative "tools/subagent"
       require_relative "tools/subagents"
       require_relative "tools/stuck_signal"
@@ -2807,16 +3266,17 @@ module Insika
       # enforced, fallback chain resolved. Kept on the state for telemetry (usage).
       selection = @model_resolver.resolve(profile: profile, session: state.session)
       state.model_selection = selection
-      build_chat(selection, selection)
+      build_chat(selection, selection, state: state)
     end
 
     # The gem boundary: one chat for a model selection (the resolved primary or
     # a WS3 fallback node). The primary's generation params apply to the whole
     # chain (params_source: ModelSelection#apply_params).
-    def build_chat(selection, params_source)
+    def build_chat(selection, params_source, state: nil)
       model = selection.respond_to?(:model) ? selection.model : selection[:model]
       provider = selection.respond_to?(:provider) ? selection.provider : selection[:provider]
-      chat = (@llm || RubyLLM).chat(
+      @llm_refresh&.call
+      chat = llm_operation_context(state, model).chat(
         model: model,
         provider: provider,
         assume_model_exists: !provider.nil?
@@ -2825,6 +3285,62 @@ module Insika
       chat
     end
 
+    # `operation` labels every request this context makes in the task's traces and
+    # model metrics: "chat" for the answer, knowledge_* for the post-turn calls, so
+    # the Models page can tell the reply's cost from the learning's.
+    def llm_operation_context(state, model, operation: "chat")
+      return @llm || RubyLLM unless state.respond_to?(:task) && state.task
+
+      instrumented_llm(state.task, model, operation: operation, turn: state.turn,
+                                          agent: state.respond_to?(:profile) ? state.profile&.id : nil)
+    end
+
+    # Every request a task makes, whatever the caller: rows carry the agent, so
+    # the Models page filters by it.
+    def instrumented_llm(task, model, operation:, turn: nil, agent: nil)
+      source = @llm || RubyLLM
+      return source unless source.respond_to?(:config)
+
+      require_relative "telemetry/ruby_llm_instrumenter"
+      config = source.config.dup
+      extra = { "turn" => turn, "agent" => agent&.to_s }.compact
+      config.instrumenter = Telemetry::RubyLLMInstrumenter.new(
+        delegate: config.instrumenter, operation: operation, model: model, pricing: @pricing,
+        emit: ->(type, data) { emit(type, data.merge(extra), task: task) }
+      )
+      RubyLLM::Context.new(config)
+    end
+
+    # A turn's LLM diagnostics in one batch per store, instead of one transaction
+    # per provider event: written when the turn ends (however it ends, after the
+    # customer already has the answer) and before it suspends for a human.
+    def write_llm_diagnostics(task, entries)
+      return if entries.nil? || entries.empty?
+
+      [@llm_trace_store, @model_metrics_store].each do |store|
+        next unless store
+
+        if store.respond_to?(:record_many)
+          store.record_many(task_id: task.id, entries: entries)
+        else
+          entries.each { |entry| store.record(task_id: task.id, entry: entry) }
+        end
+      rescue StandardError
+        # Diagnostics must never fail the turn.
+      end
+    end
+
+    # Writes what the running turn buffered so far and keeps buffering: a turn
+    # about to wait (approval, pause) may wait for hours, and its cost so far
+    # must be visible and survive a crash meanwhile.
+    def flush_llm_diagnostics(task)
+      entries = @llm_buffers[task.id]
+      return if entries.nil? || entries.empty?
+
+      @llm_buffers[task.id] = []
+      write_llm_diagnostics(task, entries)
+    end
+
     # Single emitter: an Event with meta and a monotonic seq per task. @seqs is not
     # cleared at the end of the task — the resume (new Execution) continues the
     # numbering (reliable replay). A task WITH a tenant (WS1) tags every event it
@@ -2832,10 +3348,28 @@ module Insika
     # event without a task has no tenant and never matches a tenant stream);
     # absent tenant -> the meta is byte-identical to before.
     def emit(type, data, task:)
+      # Required mode releases only the accepted final answer after its durable ack.
+      if (shared = @shared_turns[task.id]) && !shared[:committed]
+        return if %i[content intermediate thinking workflow_completed].include?(type)
+      end
       meta = { task_id: task.id, session_id: task.session_id,
-               seq: (@seqs[task.id] += 1), at: Time.now.utc.iso8601 }
+               seq: (@seqs[task.id] += 1), at: Time.now.utc.iso8601(6) }
       tenant = task_tenant(task)
       meta[:tenant] = tenant unless tenant.nil?
+      if type == :llm_request || type == :llm_usage
+        entry = data.merge("type" => type.to_s, "at" => meta[:at])
+        if (buffer = @llm_buffers[task.id])
+          buffer << entry # a running turn writes them all at its end (#flush_llm_diagnostics)
+        else
+          [@llm_trace_store, @model_metrics_store].each do |store|
+            begin
+              store&.record(task_id: task.id, entry: entry)
+            rescue StandardError
+              # Recorders fail independently; diagnostics must not interrupt the model.
+            end
+          end
+        end
+      end
       @event_stream.emit(Insika::Event.new(type: type, data: data, meta: meta))
     end