insika 0.2.0 → 0.7.0

data/lib/insika/executor.rb

@@ -20,7 +20,10 @@ module Insika
                    capability_registry: nil, tool_catalog: nil, memory_store: nil,
                    tool_trace_store: nil, settings_store: nil, content_filter_factory: nil,
                     delegation_store: nil, channel_delivery: nil, llm: nil,
-                    context_trace_store: nil, reliability: 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)
       @context_builder = context_builder
       @policy_engine = policy_engine
       @middleware = middleware
@@ -40,6 +43,10 @@ module Insika
       # per-turn context breakdown (tokens by category + budget) for the
       # Studio session card. nil = off (no record, zero overhead — parity).
       @context_trace_store = context_trace_store
+      # the model-visible trace — what the provider received per
+      # (task, turn), captured at the chat boundary. nil = off (no record,
+      # zero overhead — parity).
+      @model_visible_trace_store = model_visible_trace_store
       # Guardrails output filter: ->(state) { OutputFilter | nil }.
       # Injected by the Safety::Factory; nil = off (parity — the stream is untouched).
       # The INPUT guardrail is a Middleware (in the stack, not here); this is the seam
@@ -64,13 +71,38 @@ module Insika
       # fallback / circuit breaker, all DATA on AgentProfile#reliability.
       # nil = the plain single ask (parity).
       @reliability = reliability
+      # WS9 media seam (nil = default built on first audio turn): ->(url) { text }.
+      @media = media
+      # WS9 (saída) media-generation seams: { image: ->(prompt, cfg) [part,
+      # usage], tts: ->(text, cfg) [part, usage] }. nil = the defaults (built
+      # lazily on first generation — RubyLLM + Net::HTTP behind lazy requires,
+      # the core stays gem-free at load). Injected by specs; a production graph
+      # that wants a non-RubyLLM backend injects its own lambdas.
+      @media_output = media_output
+      # the :enforce boundary step, called between stages 6 and 8.
+      # Defaults to a REAL enforcer (inert unless the profile's grounding.mode is
+      # :enforce — zero behavior change for parity) so an embedder that builds
+      # the Executor directly still gets the cut; `nil` stays injectable for
+      # stubs that want none.
+      @grounding_enforcer = grounding_enforcer || Insika::Safety::GroundingEnforcer.new
+      # the per-AGENT cache-hit series. nil = no series recorded
+      # (parity — the trace store still gets the per-turn entry when wired).
+      @cache_series_store = cache_series_store
       # LLM config v2: resolves the model at turn start (Chat > Agent >
       # platform default) + model_policy + fallback chain. settings_store nil =
       # no platform layer (pre-v2 behavior: the agent's own model is used as-is).
       @model_resolver = ModelResolver.new(settings_store: settings_store)
+      # the follow-up stores the ChatBuilder gates the
+      # schedule/cancel_followup tools on (nil = never wired — parity).
+      @contact_store = contact_store
+      @followup_store = followup_store
       # the platform layer of the queue policy (nil = per-agent and
       # defaults only, which is `followup` with no window — today's behavior).
       @settings_store = settings_store
+      # LEARNED concepts, extracted from a turn's transcript after it
+      # completes. nil = the loop is off (parity — every write path below is
+      # skipped, zero allocations). Gated per-agent by `profile.knowledge`.
+      @knowledge_store = knowledge_store
       # RubyLLM glue (stages 5-7): chat assembly delegated to ChatBuilder. Its
       # optional deps tool_catalog (Tool Search) and memory_store (cross-session
       # memory) matter only to it — nil = parity (deferred
@@ -84,7 +116,23 @@ module Insika
         # the ChatBuilder wires the spawn_subagent system tool (gated by
         # profile.subagents) and hands it this Executor as the runner. `self` is not
         # yet fully built here, but the ChatBuilder only STORES it (used per-turn).
-        subagent_runner: self
+        subagent_runner: self,
+        # WS9 (saída): the media-generation runner, same shape — the Executor
+        # owns the seams + usage accounting, the builder only wires the tools
+        # the turn's gates allow.
+        media_runner: self,
+        # the builder wires the briefing-write system tools gated by
+        # @session_store + profile.briefing_fields. nil = never wired (parity).
+        session_store: session_store,
+        # the builder wires the schedule/cancel_followup system
+        # tools gated by a parsed policy AND both stores present. nil = never
+        # wired (parity).
+        contact_store: contact_store,
+        followup_store: followup_store,
+        # the builder wires the load_knowledge system tool gated by
+        # @knowledge_store + profile.knowledge["retrieve"]. nil = never
+        # wired (parity — the write path above stays unaffected either way).
+        knowledge_store: knowledge_store
       )
       # Stage-3-tail tool assembly (capability resolution, instantiation,
       # injection, dedup join, ToolEnvelope wrap) — extracted collaborator.
@@ -124,6 +172,32 @@ module Insika
     # the turn supervisor in serving mode (like the tick); nil = no alerts.
     attr_accessor :alert_dispatcher
 
+    # the distillation engine — the tick-duty that finds idle
+    # customer sessions and distills them on its own worker fiber (a child of
+    # the turn supervisor, like the tick). nil = distillation off (parity —
+    # nothing scans, nothing distills).
+    attr_accessor :distill_engine
+
+    # the harvest engine — the tick-duty that finds idle,
+    # unmined sessions and mines them on its own worker fiber (a child of the
+    # turn supervisor, like the tick). nil = harvest off (parity — nothing
+    # scans, nothing mines).
+    attr_accessor :harvest_engine
+
+    # 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
+    # (no live chat) never fires the tick until some unrelated turn happens to
+    # land first — observed live as 16+ minutes of silence after a clean boot.
+    # Call once, right after `supervised = true`, from the composition root
+    # (Server::Boot / config.ru / DSL::ServerBoot). A no-op outside a live
+    # reactor (nothing to bind the supervisor to yet) — the lazy path in
+    # #turn_parent still covers that case, e.g. specs that never enter Async.
+    def start_supervisor!
+      turn_parent if @supervised && Async::Task.current?
+      nil
+    end
+
     # closes the TURN intake for shutdown. Armed by Insika::Shutdown
     # when the process is asked to stop: from here on a new top-level turn is left
     # `:queued` (durable — the next boot's recovery replays it) instead of
@@ -225,12 +299,17 @@ module Insika
 
     # Stage 1 (async part): creates the actor, registers it and fires the fiber.
     # Called by the turn handlers (SendMessage/ResumeTask/TriggerWorkflow).
-    def spawn(task, profile:, resume_from: nil)
+    #
+    # `timing`  is the channel clock a channel turn allocated at 202
+    # acceptance, already carrying `:inbound`; nil means the pipeline allocates its
+    # own (resume, engine-initiated, non-channel). `mark` is first-write-wins, so
+    # re-marking `:inbound` in the pipeline is a no-op on a threaded clock.
+    def spawn(task, profile:, resume_from: nil, timing: nil)
       raise Insika::ValidationError, "task already running: #{task.id}" if running?(task.id)
 
       actor = TaskActor.new(task_id: task.id, parent: turn_parent)
       @running[task.id] = actor
-      actor.run { execute(task, profile: profile, resume_from: resume_from, actor: actor) }
+      actor.run { execute(task, profile: profile, resume_from: resume_from, actor: actor, timing: timing) }
       task.id
     end
 
@@ -238,7 +317,7 @@ module Insika
     # session_id is SERIALIZED in that session's SessionActor queue (one at a
     # time); without a session_id (one-shot/history) it goes straight to spawn
     # (standalone).
-    def spawn_in_session(task, profile:, resume_from: nil)
+    def spawn_in_session(task, profile:, resume_from: nil, timing: nil)
       # the intake is closed. The task is already durable (queued);
       # answering with its id and spawning NOTHING is what "stops accepting new
       # turns" means — the next boot's recovery replays it. Subagent turns are NOT
@@ -252,11 +331,12 @@ module Insika
       # owner awaits the turn). One-shot/history (no session_id)
       # never serialize.
       unless @supervised && task.session_id
-        return spawn(task, profile: profile, resume_from: resume_from)
+        return spawn(task, profile: profile, resume_from: resume_from, timing: timing)
       end
 
       session_actor(task.session_id).enqueue(task, profile: profile, resume_from: resume_from,
-                                                   policy: queue_policy(profile, task.session_id))
+                                                   policy: queue_policy(profile, task.session_id),
+                                                   timing: timing)
     end
 
     # the `collect` door, asked BEFORE a task is created.
@@ -296,7 +376,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 belongs to `collect`, which is a different mode.
+      # 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.
       task = session_actor.current_task
       return nil if task.nil?
       # A workflow turn orchestrates RubyLLM itself and has no Insika chat to append to
@@ -404,13 +485,13 @@ module Insika
     # its completion before returning — that is what serializes the session. A
     # turn error is already mapped to a terminal state inside its own fiber (single
     # capture); here we only ensure the session loop does not die.
-    def run_serial(task, profile:, resume_from: nil)
+    def run_serial(task, profile:, resume_from: nil, timing: nil)
       # a drain that started with turns already queued behind this
       # session's current one must not keep feeding the loop — without this gate
       # the drain would only converge when the whole backlog ran out.
       return defer_turn(task) if @draining
 
-      spawn(task, profile: profile, resume_from: resume_from)
+      spawn(task, profile: profile, resume_from: resume_from, timing: timing)
       @running[task.id]&.wait
     rescue Async::Stop
       raise # shutdown: propagate (ends the session loop)
@@ -505,7 +586,7 @@ module Insika
     end
 
     # Stages 2..9. Runs INSIDE the task's fiber.
-    def execute(task, profile:, actor:, resume_from: nil)
+    def execute(task, profile:, actor:, resume_from: nil, timing: nil)
       # 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
@@ -519,7 +600,7 @@ module Insika
       emit(:task_started, started_data(task, profile), task: task)
 
       actor.drain!
-      run_pipeline(task, profile, actor, resume_from)
+      run_pipeline(task, profile, actor, resume_from, timing)
     # 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.
@@ -541,6 +622,14 @@ module Insika
       # 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)
+    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)
+    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)
     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
@@ -574,6 +663,36 @@ module Insika
       release_steered(task, profile, actor)
     end
 
+    # WS9 (saída), the RUNNER side the generate_image/tts system tools call
+    # (public like run_subagent — a tool reaches back into the Executor):
+    #
+    # -> [part, usage]: resolve the seam (injected or the lazy default) and
+    # run it. The default seams are built on FIRST use, when the turn already
+    # has a chat (ruby_llm loaded), so the load-guard holds.
+    def generate_media_output(kind, content, config)
+      seam = @media_output&.fetch(kind, nil) || Insika::Media::Output.defaults(context: @llm)[kind]
+      raise Insika::MediaError, "no #{kind} output seam" unless seam
+
+      seam.call(content, config)
+    end
+
+    # Accounts a generated part in the turn's usage: the provider's token
+    # counts (images — the merge keeps what the classifier already banked),
+    # plus an honest `media` call counter per part (the speech API reports no
+    # tokens; the part itself carries the model for consumer-side pricing).
+    def account_media_usage(state, part, usage)
+      usage ||= {}
+      tokens = {}
+      tokens[:input_tokens] = usage[:input_tokens].to_i if usage[:input_tokens]
+      tokens[:output_tokens] = usage[:output_tokens].to_i if usage[:output_tokens]
+      tokens[:total_tokens] = tokens[:input_tokens].to_i + tokens[:output_tokens].to_i if tokens.any?
+      unless tokens.empty?
+        tokens[:model] = part["model"] if part["model"]
+        state.usage = merge_usage(tokens, state.usage)
+      end
+      state.usage = (state.usage || {}).merge(media: state.usage&.fetch(:media, 0).to_i + 1)
+    end
+
     private
 
     # resolves session vars > profile.limits > settings["queue"] >
@@ -646,6 +765,12 @@ module Insika
       # the alert dispatcher (WS6) lives on the same supervisor: its consumer
       # answers every alert event for as long as the process serves.
       @alert_dispatcher&.start(parent: @supervisor)
+      # the distillation engine  lives on the same supervisor —
+      # its worker fiber re-scans idle sessions off the turn path.
+      @distill_engine&.start(parent: @supervisor)
+      # the harvest engine  lives on the same supervisor — its
+      # worker fiber re-scans idle sessions off the turn path.
+      @harvest_engine&.start(parent: @supervisor)
       @supervisor
     end
 
@@ -710,8 +835,23 @@ module Insika
     # Stages 2-9, with mailbox drain only at the boundaries and the
     # turn-timeout wrapping everything via Async::Task#with_timeout — NEVER
     # stdlib Timeout.timeout.
-    def run_pipeline(task, profile, actor, resume_from)
-      timing = TurnTiming.new if TurnTiming.enabled?
+    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.
+      #
+      # A channel turn may already carry its clock: `SendMessage` stamped
+      # `:inbound` at 202 acceptance (before the debounce window and the
+      # SessionActor FIFO), so first_balloon_ms includes the wait the customer
+      # actually feels. A turn that reached here without one (boot resume,
+      # 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&.mark(:inbound) if channel_turn
       timing&.mark(:prep_start)
       state = build_turn_state(task, profile, resume_from)
       turn_timeout = turn_timeout_for(profile)
@@ -741,7 +881,7 @@ module Insika
         #   · halt_reason set    -> halt-as-FAILURE (the pre-existing contract).
         #   · neither            -> contract violation (short-circuit with no signal).
         if !terminal_ran && state.halt_response
-          complete_with_halt(task, profile, state)
+          complete_with_halt(task, profile, state, timing)
         elsif state.halt_reason
           raise Insika::Error, "turn halted: #{state.halt_reason}"
         elsif !terminal_ran
@@ -749,7 +889,15 @@ module Insika
         end
 
           state # subject of the :task pair (after_task receives it; the caller discards)
-        end.tap { |st| emit_guardrail_flags(task, st) }
+        end.tap do |st|
+          # flush the evidence ledger HERE — after the after_task
+          # hooks ran, because the :flag validator increments the ungrounded
+          # counter in after_task. The envelope's ids (stage 6) ride the same
+          # flush. AFTER persist_turn (already done), so a flush failure can
+          # never un-commit the turn (the ledger swallows store errors).
+          st.evidence_ledger&.flush!
+          emit_guardrail_flags(task, st)
+        end
       end
     rescue Async::TimeoutError
       raise Insika::TimeoutError.new("turn exceeded #{turn_timeout}s", stage: :turn)
@@ -762,6 +910,7 @@ module Insika
       state = TurnState.new(task: task, profile: profile, turn: turn,
                             message: extract_message(task))
       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
       # resolved for the RUN, not per message, so what the turn accepts cannot
@@ -769,6 +918,12 @@ module Insika
       # SESSION turn: steering needs a session to arrive through, and resolving here for a
       # one-shot would make an unrelated turn fail on a queue key it can never use.
       state.queue_policy = task.session_id ? queue_policy(profile, task.session_id) : nil
+      # the session evidence ledger, built per turn. A nil
+      # session_id (one-shot) is fine — the ledger just never flushes (grounding
+      # on a one-shot is per-turn by definition). The envelope appends ids, the
+      # validator/enforcer read the union, stage 8 flushes.
+      state.evidence_ledger = Insika::EvidenceLedger.new(store: @session_store,
+                                                         session_id: task.session_id)
       state
     end
 
@@ -786,6 +941,17 @@ module Insika
     # -> tool assembly, each followed by a mailbox drain at the boundary. Mutates
     # `state` in place (the TurnState possibly rewritten by before_task).
     def prepare_turn(task, profile, state, actor, resume_from)
+      # WS9 (saída): the CHANNEL's declared output media kinds — read on EVERY
+      # run (including resumes — it is plain config) so the ChatBuilder gate
+      # can re-wire the media tools; the transcription below stays guarded.
+      state.channel_capabilities = Insika::Media.channel_capabilities(
+        rebuild_command(task).payload["channel"]
+      )
+      # WS9: content parts -> turn. Runs BEFORE stage 2's context build so the
+      # transcribed voice text feeds the prompt; a resumed turn was already
+      # transcribed (never re-pay the STT call).
+      run_media_stage(task, state) unless state.resumed
+
       # stage 2: Context. The :prompt hook pair is wrapped INSIDE the
       # ContextBuilder#call — do NOT wrap here (a double-wrap would fire the hooks
       # twice). Hooks is the SAME instance injected into the Builder and here.
@@ -824,8 +990,12 @@ module Insika
 
     # one entry per turn in the ContextTraceStore — tokens per
     # category (the demodulized provider id), the tools-schema estimate and the
-    # budget verdict. Counts and ids ONLY, never content. nil store = off; the
-    # store itself rescues everything (the trace never breaks the turn).
+    # budget verdict. the entry also carries the prefix
+    # fingerprints + the invalidation_reason vs the previous turn, and the
+    # categories gain their cache layer. Counts and ids ONLY, never content.
+    # nil store = off; the store itself rescues everything (the trace never
+    # breaks the turn). -> the sanitized entry (parked on TurnState for the
+    # stage-8 cache stamp).
     def record_context_trace(task, state)
       return unless @context_trace_store && task.session_id
 
@@ -839,6 +1009,10 @@ module Insika
         c[:tokens] += f.tokens || 0
         c[:fragments] += 1
         c[:pinned] += (f.tokens || 0) if f.pinned
+        # the category's cache layer (identity | :volatile —
+        # stamped by the Builder at production, C3).
+        layer = f.layer || :volatile
+        c[:layer] ||= layer
         # WHICH skills/tools the fragment carried and WHY — ids only, still
         # content-free. Without this the trace proves a turn injected N tokens of
         # skill but not which ones, and deterministic activation is unauditable
@@ -846,14 +1020,88 @@ module Insika
         labels = Array(f.labels)
         (c[:labels] ||= []).concat(labels) unless labels.empty?
       end
-      @context_trace_store.record(
-        session_id: task.session_id,
-        entry: { task_id: task.id, turn: state.turn, at: Time.now.utc.iso8601,
-                 cap: package.budget[:cap], used: package.budget[:used],
-                 evicted: package.budget[:evicted], categories: categories,
-                 tools: { count: state.allowed_tools.size,
-                          tokens: estimate_tools_tokens(state.allowed_tools) } }
-      )
+      # the prefix chain over the SYSTEM-placement fragments in
+      # canonical (identity-first) render order + the tool-schema serialization.
+      # The reason is computed against the PREVIOUS trace entry (D3): the first
+      # category, in current chain order, whose bytes changed (or vanished).
+      previous = previous_trace_entry(task, state.turn)
+      fingerprints = Insika::PrefixFingerprint.compute(
+        Array(package.fragments).select { |f| f.placement == :system },
+        tool_serial: serialize_tools(state.allowed_tools))
+      reason = Insika::PrefixFingerprint.invalidation_reason(
+        fingerprints, previous && previous["fingerprints"])
+
+      entry = { task_id: task.id, turn: state.turn, at: Time.now.utc.iso8601,
+                cap: package.budget[:cap], used: package.budget[:used],
+                evicted: package.budget[:evicted], categories: categories,
+                tools: { count: state.allowed_tools.size,
+                         tokens: estimate_tools_tokens(state.allowed_tools) },
+                fingerprints: fingerprints,
+                cache: { invalidation_reason: reason } }
+      # Park the SANITIZED entry (string keys) — the stage-8 stamp merges into
+      # it and re-records the same key; a raw entry would add a SECOND "cache"
+      # key that sanitize would then ignore (the symbol one wins).
+      state.context_trace_entry = @context_trace_store.record(session_id: task.session_id,
+                                                              entry: entry)
+    end
+
+    # the previous turn's trace entry — the session list minus
+    # THIS (task_id, turn) (an approval-resumed turn re-records over its own key
+    # — never compare to self). `turn` is the turn being recorded, passed
+    # explicitly. -> Hash | nil (first turn of the session).
+    def previous_trace_entry(task, turn)
+      @context_trace_store.for_session(task.session_id)
+                           .reject { |x| x["task_id"] == task.id && x["turn"] == turn }
+                           .last
+    end
+
+    # the tool-schema yardstick — the SAME serialization the token
+    # estimate uses (estimate_tools_tokens), so the fingerprint and the estimate
+    # never disagree. The digest covers name + description + parameters.inspect,
+    # 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(" ")
+    end
+
+    # the stage-8 stamp — the usage (cached_tokens,
+    # input_tokens) only exists after the provider answered, so a SECOND
+    # UPSERT with the SAME (task_id, turn) merges the cache fields into the
+    # entry parked at prepare_turn (the start-of-turn write stays: a turn that
+    # dies mid-flight still shows its context on the Studio screen). The same
+    # numbers append one entry to the agent's CacheSeriesStore (C6).
+    def stamp_cache_hit(task, state)
+      usage = state.usage || {}
+      input = usage[:input_tokens].to_i
+      cached = usage[:cached_tokens].to_i
+      creation = usage[:cache_creation_tokens].to_i
+      # A4: the billed prefix is input + cached + cache_creation. RubyLLM's
+      # input_tokens is the FRESH input only — cached_tokens is disjoint, not a
+      # subset — so dividing by input alone yields absurd numbers (22000/500 =
+      # 4400%) and renders a full hit as "—" (fresh=0). The denominator is the
+      # whole billed prompt; hit_pct is then always in [0,100].
+      billed = input + cached + creation
+      hit = billed.positive? ? ((cached * 100.0) / billed).round : nil
+      reason = state.context_trace_entry&.dig("cache", "invalidation_reason")
+
+      # The trace merge needs the entry parked at prepare_turn (the UPSERT
+      # replaces the same (task_id, turn)); a failed trace write leaves it nil
+      # and the cache line simply never lands — never a turn failure.
+      if @context_trace_store && state.context_trace_entry && task.session_id
+        @context_trace_store.record(
+          session_id: task.session_id,
+          entry: state.context_trace_entry.merge("cache" => {
+            "hit_pct" => hit, "cached_tokens" => cached, "prompt_tokens" => billed,
+            "invalidation_reason" => reason }))
+      end
+
+      # The per-agent series is INDEPENDENT of the trace store: a deployment
+      # that wires the series without the trace (or whose trace write failed)
+      # still records its cache-hit numbers — reason is simply nil then.
+      @cache_series_store&.record(agent: state.profile.id, entry: {
+        at: Time.now.utc.iso8601, turn: state.turn,
+        hit_pct: hit, cached_tokens: cached, prompt_tokens: billed,
+        invalidation_reason: reason })
     end
 
     # Skill bodies that reached the prompt WITHOUT a tool call (`triggers:` or
@@ -904,7 +1152,13 @@ module Insika
       # stage 5: assemble chat + check mailbox (send_message only; a workflow does
       # not use the Insika chat — it orchestrates RubyLLM internally).
       drain_and_maybe_suspend(task, actor)
-      unless workflow_turn?(task)
+      # WS4: intent routing, data-gated. Runs BEFORE the agent chat is assembled:
+      # a route that delegates or ends :stuck completes the turn with no ask at
+      # all (routed = true); a plain route is a label + event and the turn
+      # proceeds. Skipped for workflows (no chat to route into) and resumed turns
+      # (already admitted; re-classifying would re-pay the extra call).
+      routed = !workflow_turn?(task) && !st.resumed ? attempt_route(task, profile, st) : false
+      unless workflow_turn?(task) || routed
         st.chat = create_chat(profile, st)
         @chat_builder.assemble(st.chat, st, emit: ->(type, data) { emit(type, data, task: task) })
         # R1: baseline = seeded-history size, before `ask` appends the turn.
@@ -915,21 +1169,57 @@ module Insika
       st.output_filter = @content_filter_factory&.call(st)
 
       # stage 6: the turn's single agent interaction (send_message -> chat.ask;
-      # trigger_workflow -> workflow.call). Returns the turn's final content.
-      content = run_agent_stage(task, st, timing)
+      # trigger_workflow -> workflow.call). A routed turn's content IS its route
+      # action's answer (a delegate's reply or the stuck lead-in).
+      content = routed ? st.response_content : run_agent_stage(task, st, timing)
       st.response_content = content # after_task OutputValidator inspects this
 
+      # the model-visible record — what the provider received this
+      # turn, captured at the boundary BEFORE stage 8 persists the checkpoint
+      # (turn n's provider-visible stream == checkpoint(turn n+1).messages).
+      # Skipped for workflows (they orchestrate RubyLLM inside the workflow
+      # body — the engine cannot see those calls, stated in the conformance
+      # scope) and absent-store runs (parity).
+      record_model_visible(task, st) if !workflow_turn?(task) && st.chat
+
+      # the :enforce boundary — a CUT of the final content BEFORE
+      # persistence/delivery (after_task fires too late to change what is
+      # persisted). The cut text is what persists, delivers and terminates.
+      if @grounding_enforcer
+        content, st = @grounding_enforcer.call(task, st, content)
+        st.response_content = content
+      end
+
       # stage 8: Persistence (fixed order checkpoint->session->task). pure drain!
       # (NEVER suspends at stage 8 — forbidden window): a :pause here arms the flag
       # but is not honored (last stage); :cancel here still raises.
       actor.drain!
-      persist_turn(task, profile, st, content)
+      persist_turn(task, profile, st, content, timing: timing)
+
+      # the cache-hit stamp — the usage exists only now. The
+      # stamped entry is durable before anything is delivered (same slot as the
+      #   enforcer). Best-effort by construction (both stores rescue).
+      stamp_cache_hit(task, st)
 
       # stage 9: Response. usage (tokens) captured at stage 6 travels in the
       # terminal event -> /v1/responses usage + Telemetry (OTEL).
       timing&.mark(:done)
       data = { task_id: task.id, content: content, usage: st.usage }
+      # WS4: the intent route rides the terminal additively (like outcome) — a
+      # consumer aggregating by route does not need the stream.
+      data[:route] = st.route.to_s if st.route
+      # WS9: a turn whose message came from a VOICE note is marked — the
+      # consumer's signal the person spoke (text was transcribed).
+      data[:source] = :voice if st.message_source == :voice
+      # WS9 (saída): media the agent GENERATED this turn (image/audio clips).
+      # 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)
+      # 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)
       # 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
@@ -946,6 +1236,23 @@ module Insika
       command_type(task).to_s == "trigger_workflow"
     end
 
+    # the model-visible record of ONE ask — the chat at the
+    # provider boundary (instructions + tool schemas + the message stream),
+    # persisted under the checkpoint's turn number (turn n's stream ==
+    # checkpoint(turn n+1).messages). Best-effort: the store rescues
+    # everything, and the absent-store path is parity. `chat` defaults to the
+    # turn's own chat; the routing classifier passes its own.
+    def record_model_visible(task, st, chat = nil, part: "turn")
+      return unless @model_visible_trace_store
+
+      c = chat || st.chat
+      return unless c
+
+      @model_visible_trace_store.record(
+        task_id: task.id, turn: st.turn + 1, part: part,
+        payload: Insika::ModelVisible.capture(c))
+    end
+
     # Stage 6: the single agent interaction. Returns the turn's final content.
     def run_agent_stage(task, state, timing = nil)
       if workflow_turn?(task)
@@ -978,6 +1285,13 @@ module Insika
         response = @hooks.around(:agent, state) do |s|
           result = @reliability ? run_reliable_ask(task, s, filter, timing)
                                 : run_single_ask(task, s, filter, timing)
+          # A steered message that no tool batch absorbed (a text-only turn: the
+          # injector only drains at a tool boundary) is still in the mailbox when
+          # RubyLLM's loop returns. ONE extra round, in the SAME turn, answers the
+          # burst coherently -- without it the release would spawn a follow-up
+          # whose answer has no delivery channel under request/response.
+          # Read AFTER it: the extra round replaces both the response and `asked`.
+          absorb_steer_overflow(task, s, timing, result)
           output = result[:output]
           asked = result[:asked]
           result[:response]
@@ -985,7 +1299,13 @@ 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
-        state.usage = with_model_source(usage_of(response), state.model_selection) unless halted?(response)
+        # 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
@@ -1075,6 +1395,231 @@ module Insika
 
     def ref_of(selection) = model_ref(selection)
 
+    # --- WS9 media ------------------------------------------------------
+    #
+    # Content parts on the command -> a turn: audio parts are transcribed (the
+    # text enters the message marked `source: :voice` — the consumer's signal
+    # the person SPOKE), image and document parts become the ask's attachments
+    # (the model sees them; the provider bills them — usage flows) and the
+    # first URL of each kind is deposited as `ctx.image_url` / `ctx.document_url`
+    # for data/HTTP tools. The engine transports media, never meaning: no
+    # speech/vision logic beyond the call itself.
+    def run_media_stage(task, state)
+      # 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"
+
+      parts = Insika::Media.parts(rebuild_command(task).payload["parts"])
+      return if parts.empty?
+
+      voice = Insika::Media.audio_parts(parts)
+      if voice.any?
+        text = voice.map { |p| media_transcribe(p.url, state) }.reject(&:empty?).join(" ")
+        state.message = [state.message.to_s, text].reject(&:empty?).join("\n")
+        state.message_source = :voice
+      end
+
+      images = Insika::Media.image_parts(parts)
+      if images.any?
+        state.image_attachments = images.map { |p| media_attachment(p.url) }
+        state.media_attachments = state.image_attachments
+        # First image URL for data tools (`{{ctx.image_url}}`) — photo analysis
+        # outside the prompt. The model still sees the attachment; the tool
+        # gets the original URL (its own egress applies when it fetches).
+        state.turn_context = (state.turn_context || {}).merge(image_url: images.first.url)
+      end
+
+      # Documents (a prescription, a recipe, an invoice) ride the SAME
+      # attachments array as images — RubyLLM's `ask(with:)` takes both, and
+      # the attachment content-sniffs PDF magic bytes when the URL has no
+      # extension — capped separately (MAX_DOCUMENT_BYTES) since a document
+      # is not a photo.
+      documents = Insika::Media.document_parts(parts)
+      if documents.any?
+        doc_attachments = documents.map { |p| media_attachment(p.url, max_bytes: Insika::Media::MAX_DOCUMENT_BYTES) }
+        state.media_attachments = Array(state.media_attachments) + doc_attachments
+        state.turn_context = (state.turn_context || {}).merge(document_url: documents.first.url)
+      end
+
+      # A media-only turn (a voice note with no caption) is legitimate — the
+      # surfaces admit it — but it must leave this stage with something to ask
+      # about. Empty text AND no attachment means the parts carried nothing the
+      # engine could use (a transcription that came back blank): fail loudly at
+      # :media rather than ask the provider about nothing.
+      return unless state.message.to_s.strip.empty? && state.media_attachments.nil?
+
+      raise Insika::MediaError, "the message parts produced no text and no attachment"
+    end
+
+    # The STT seam: the injected transcriber (specs), else the default
+    # (fetch + RubyLLM::Transcription — lazy require). A failed transcription
+    # fails the turn loudly (MediaError -> :media): a voice message that was
+    # not heard must not become a hallucinated one. The default is rebuilt
+    # PER CALL (never memoized) because its vocabulary `prompt:` is resolved
+    # from THIS turn's profile — a memoized seam would freeze the first
+    # agent's prompt (or its absence) for every agent sharing the executor.
+    def media_transcribe(url, state)
+      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)
+      )
+      transcriber.call(url)
+    end
+
+    # Resolution order: the agent profile's own vocabulary hint
+    # (it knows its catalog) beats the deployment-wide default, which beats
+    # nothing (no prompt: kwarg at all).
+    def resolved_stt_prompt(profile)
+      Insika::Coercion.presence(profile&.stt_prompt) || Insika::EnvSchema.read("INSIKA_STT_PROMPT")
+    end
+
+    # An image/document part -> the ask's attachment (Insika::Media.url_attachment
+    # — egress-guarded, size-capped fetch; the caller picks the ceiling).
+    def media_attachment(url, max_bytes: Insika::Media::MAX_IMAGE_BYTES)
+      Insika::Media.url_attachment(url, max_bytes: max_bytes)
+    end
+
+    # --- WS4 intent routing --------------------------------------------
+    #
+    # The turn's message is classified into one of the profile's routes with a
+    # CHEAP model (data-gated: no `routes` on the profile = byte-identical turn).
+    # -> true when the route took over the turn (delegated / stuck — no ask
+    # happens); false when the turn proceeds normally. Classification happens on
+    # a fresh chat carrying ONLY the auto-generated route prompt (no identity,
+    # no tools — it is a router, not the agent); its tokens ride the turn's
+    # usage, so the trace, the token ceiling and the budget all see the cost.
+    def attempt_route(task, profile, state)
+      meta = Insika::Routing.normalize(profile.routes)
+      return false unless meta
+      return false unless route_model(meta, profile)
+
+      selection = route_selection(meta, profile)
+      classification = classify_route(selection, meta, state.message, task, state)
+      return false if classification.nil? # the classifier call failed — routing is additive
+
+      route = classification[:route]
+      state.route = route
+      # MERGED, not assigned: a WS9 transcription may already have banked its
+      # tokens in state.usage (the classifier call must not erase them).
+      state.usage = merge_usage(with_model_source(usage_of(classification[:response]), selection),
+                                state.usage)
+      emit(:route_classified,
+           { task_id: task.id, agent: profile.id.to_s, route: route.to_s,
+             model: selection.model, usage: state.usage },
+           task: task)
+
+      entry = meta[:entries].find { |e| e.name == route.to_s }
+      apply_route_action(task, profile, state, entry)
+    end
+
+    # The classifier call, its answer parsed back into a route.
+    # -> { route:, response: } | nil (nil = the call failed — the turn proceeds
+    # unrouted rather than paying a wrong label or dying for an additive step).
+    def classify_route(selection, meta, message, task, st)
+      response = route_ask(selection, Insika::Routing.classifier_prompt(meta), message, task, st)
+      { route: Insika::Routing.parse(route_response_text(response), meta), response: response }
+    rescue StandardError
+      nil
+    end
+
+    # The cheap classifier's model: routes["model"] wins, the agent's own model
+    # otherwise. No model anywhere = no routing.
+    def route_model(meta, profile)
+      ref = meta[:model].to_s
+      ref = profile.model.to_s if ref.empty?
+      !ref.empty?
+    end
+
+    def route_selection(meta, profile)
+      ref = meta[:model].to_s
+      ref = profile.model.to_s if ref.empty?
+      parsed = parse_model_ref(ref) || {}
+      provider = parsed[:provider].nil? ? profile.provider : parsed[:provider].to_sym
+      Insika::ModelSelection.new(model: parsed[:model], provider: provider, source: :routing)
+    end
+
+    # A fresh chat for the routing model with ONLY the generated prompt. RubyLLM
+    # required lazily, exactly like create_chat (the load-guard holds).
+    # the classifier is model-visible, so it is logged — the ONE
+    # engine-internal ask the conformance spec adds a record for (part
+    # "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.with_instructions(prompt) if chat.respond_to?(:with_instructions)
+      response = chat.ask(message.to_s)
+      record_model_visible(task, st, chat, part: "routing")
+      response
+    end
+
+    def route_response_text(response)
+      response.respond_to?(:content) ? response.content.to_s : response.to_s
+    end
+
+    # The route's config decides the turn's fate: nothing (a label), a DELEGATE
+    # (an existing agent answers; its reply IS the turn's), or STUCK (WS5 — the
+    # turn ends with the stuck outcome; the consumer interprets it).
+    def apply_route_action(task, profile, state, entry)
+      return false unless entry
+
+      if entry.delegate && !entry.delegate.empty?
+        delegate_route(profile, state, entry.delegate)
+        true
+      elsif entry.stuck
+        message = entry.message.empty? ? entry.description : entry.message
+        state.stuck_outcome = { reason: "route:#{state.route}", message: message }
+        state.response_content = message
+        true
+      else
+        false
+      end
+    end
+
+    # WS4 delegate action: the route names an existing agent — the turn is
+    # handed to it (the sync subagent machinery) and the child's answer IS the
+    # parent's answer. A missing agent or a failed child fails the turn: never
+    # fabricate the customer's reply.
+    #
+    # The depth comes from the PARENT's turn context, +1, and is capped here —
+    # this path does not go through `plan_subagent` (a route has no subagents
+    # allowlist to check against), so a hardcoded depth of 1 made an A -> B -> A
+    # route pair a loop with no floor: every hop reclassifies (a paid ask) and
+    # spawns another child, forever.
+    def delegate_route(profile, state, agent_id)
+      child = @profiles[agent_id.to_s]
+      raise Insika::RoutingError, "route delegate agent '#{agent_id}' not configured" if child.nil?
+
+      depth = (state.turn_context&.dig(:delegation_depth) || 0) + 1
+      cap = SubagentGraph.depth_cap
+      if depth > cap
+        raise Insika::RoutingError,
+              "routed delegate '#{agent_id}' at depth #{depth} exceeds cap #{cap}"
+      end
+
+      result = spawn_and_await_child(child, state.message, depth, state)
+      if result[:error]
+        raise Insika::RoutingError, "routed delegate '#{agent_id}' failed: #{result[:error]}"
+      end
+
+      state.response_content = result[:text].to_s
+    end
+
+    # The WS4 classifier's tokens, summed over the ask's (a call that reported no
+    # usage contributes nothing). The turn's own model/source win for attribution
+    # — the routing model's identity lives on the :route_classified event.
+    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|
+        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
+    end
+
     # "provider/model" for any selection duck (ModelSelection | { model:, provider: }).
     def model_ref(selection)
       model = selection.respond_to?(:model) ? selection.model.to_s : selection[:model].to_s
@@ -1122,7 +1667,39 @@ module Insika
     def wire_chat_output(task, state, output)
       chat = state.chat
       chat.after_message { |message| output.message_ended(message) } if chat.respond_to?(:after_message)
-      install_steer_injector(task, state)
+      state.steer_injector = install_steer_injector(task, state)
+    end
+
+    # The extra round for a steered message that never met a tool boundary (a
+    # text-only turn closes no batch, so `SteerInjector` never got its cue). The
+    # burst is appended to the history and the model answers ALL of it in one go,
+    # inside the SAME turn — without this the release would spawn a follow-up whose
+    # answer has no delivery channel under request/response.
+    #
+    # Skipped when the turn HALTED: there is no next model step by construction.
+    # `release_steered` (execute's ensure) stays the fallback there, as it is for a
+    # failed or cancelled turn, and for a transport that cannot `complete`.
+    #
+    # At most one extra round: if the model ignores the burst, the turn ends anyway.
+    def absorb_steer_overflow(task, state, timing, result)
+      injector = state.steer_injector
+      return unless injector && state.chat.respond_to?(:complete)
+      return unless state.actor&.user_messages_posted&.positive?
+      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))
+      result[:response] = extra
+      result[:asked] = extra
     end
 
     # The ask itself, chunk-by-chunk (WS3 attempts and the plain path share it).
@@ -1132,9 +1709,27 @@ module Insika
     # :ttft on EVERY content chunk (3 chunks = 3 insika.ttft frames); the spec
     # passed because FakeChat emits a single chunk.
     def ask_on(task, state, chat, output, timing)
+      each_chunk = turn_chunk_handler(task, state, output, timing)
+      # WS9: image parts ride the ask as attachments (only then — a chat whose
+      # ask has no `with:` keeps working, and the plain path is byte-identical).
+      # 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)
+      else
+        chat.ask(state.message, &each_chunk)
+      end
+    end
+
+    # The per-round chunk sink. Built FRESH per round: `ttft_sent` is that round's
+    # own bookkeeping, and the steer overflow round is a second round on the same
+    # chat.
+    def turn_chunk_handler(task, state, output, timing)
       public_thinking = state.profile.stream_public?(:thinking)
       ttft_sent = false
-      chat.ask(state.message) do |chunk|
+      lambda do |chunk|
         emit_thinking(chunk, task, public: public_thinking)
         next unless chunk.content
 
@@ -1148,16 +1743,15 @@ module Insika
     end
 
     # The provider's TTFB as a live event (data: ttft_ms) — only under
-    # INSIKA_TURN_TIMING, so absent by default (parity).
+    # INSIKA_TURN_TIMING, so absent by default (parity). Rides the SINGLE
+    # emitter: a hand-built meta here lacked `tenant`, and a tenant-scoped
+    # /v1/events subscription is fail-closed on it — the tenant's own TTFB was
+    # invisible to the tenant.
     def emit_ttft(task, timing)
       ttft = timing.to_h[:ttft_ms]
       return if ttft.nil?
 
-      @event_stream.emit(Insika::Event.new(
-                           type: :ttft, data: { ttft_ms: ttft },
-                           meta: { task_id: task.id, session_id: task.session_id,
-                                   at: Time.now.utc.iso8601 }
-                         ))
+      emit(:ttft, { ttft_ms: ttft }, task: task)
     rescue StandardError
       nil
     end
@@ -1321,9 +1915,11 @@ module Insika
       vars["history"] = hist if hist
       # The single type is Insika::ContextRequest (Data); the explicit `history`
       # travels in vars["history"] (Session provider convention), not in a field
-      # of its own.
+      # of its own. `memory_scope` is the WS8 customer cell (nil = the providers
+      # fall back to tenant || session, today's behavior).
       ContextRequest.new(profile: profile, message: state.message, session: session,
-                         checkpoint: resume_from, tenant: command_tenant(task), vars: vars)
+                         checkpoint: resume_from, tenant: command_tenant(task), vars: vars,
+                         memory_scope: memory_tenant(task))
     end
 
     # task_started payload. Carries the EXPLICIT command tenant so
@@ -1357,8 +1953,57 @@ module Insika
     # Symmetric to the READ path (Memory provider). One-shot with no tenant -> nil
     # (_default). It is NOT the <request_context> tenant (that follows
     # command_tenant, prompt parity) — only the memory read/write scope.
+    #
+    # WS8: a request carrying a CUSTOMER moves the scope to the customer cell —
+    # "[tenant:]customer" when a tenant is present, the bare customer otherwise
+    # (never _default — a tagged customer must never land in the shared cell).
+    # Per-customer memory is the 360 view; per-tenant was the leak.
+    #
+    # the SESSION fallback is MARKED ("chat:<session id>" -> cell
+    # "memory:chat:<session id>"), never a bare cell — a bare "memory:<id>" is
+    # 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)
-      command_tenant(task) || task.session_id
+      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}"
+    end
+
+    # WS8 +  : stamp the customer (WS8 — the `forget_customer`
+    # purge finds the customer's sessions through this var) AND the agent (the
+    # 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.
+    def stamp_customer_session(task, profile)
+      customer = command_customer(task)
+      return if customer.nil? || task.session_id.nil?
+
+      session = @session_store&.find(task.session_id)
+      return if session.nil? || !Coercion.presence(session.vars["customer"]).nil?
+
+      @session_store.update_vars(task.session_id,
+                                 "customer" => customer, "agent" => profile.id)
+    rescue Insika::NotFoundError, ArgumentError
+      nil
+    end
+
+    # The optional customer_key on the command payload (WS8): a String identifying
+    # the person the conversation belongs to — the memory scope's customer half
+    # and the handle `forget_customer` purges by. nil = untagged conversation
+    # (memory stays per-tenant/per-chat, byte-identical to before).
+    def command_customer(task)
+      Coercion.presence(rebuild_command(task).payload["customer"])
     end
 
     # Turn context: the ids the data-tools resolve via
@@ -1373,11 +2018,21 @@ module Insika
       {
         chat_id: task.session_id,
         agent_id: profile.id,
-        tenant: state.tenant, # already = command_tenant || session_id (memory_tenant)
+        # the DATA-TOOL header tenant stays the merchant (or the chat), even when
+        # the memory scope carries a customer — the backend identifies the store,
+        # not the shopper (WS8 keeps the two scopes separate).
+        tenant: command_tenant(task) || task.session_id,
+        # the DECLARED tenant alone (nil in single-tenant). Distinct from
+        # `tenant` for the ownership-binding tools (save_artifact): a report
+        # belongs to the AGENT's tenant — the deployment's tenant in
+        # single-tenant, never the chat that happened to run it.
+        command_tenant: command_tenant(task),
         store_id: profile.store_id,
-        # current delegation depth (0 for a top-level turn). Carried in
-        # the child command's payload by run_subagent; read here so the child's OWN
-        # spawn_subagent tool sees depth+1 and the runtime cap holds down the chain.
+        # the current task id — the save_artifact binding (which run produced
+        # this report), same turn-origin discipline as the rest of ctx.*.
+        task_id: task.id,
+        # current delegation depth (0 for a top-level turn). Set by run_subagent
+        # for children.
         delegation_depth: delegation_depth(task)
       }
     end
@@ -1701,7 +2356,7 @@ module Insika
     # order mirrors a real turn so both the /v1/responses consumer (which reads the
     # text off :content deltas) and the Studio viewer render it: audit -> safe text
     # -> persist -> terminal.
-    def complete_with_halt(task, profile, state)
+    def complete_with_halt(task, profile, state, timing = nil)
       content = state.halt_response.to_s
       state.response_content = content
 
@@ -1722,23 +2377,44 @@ module Insika
       # reading the engine's own canned text (the `safe_reply` finding exists exactly
       # because that text is otherwise indistinguishable in the transcript).
       persist_turn(task, profile, state, content, reply_origin: MessageOrigin::ENGINE,
-                   session: state.guardrail_block&.[](:source) != "edge")
-      emit(:task_completed, { task_id: task.id, content: content, usage: state.usage }, task: task)
+                   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)
+      emit(:task_completed, data, task: task)
     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.
-    def emit_guardrail_flags(task, state)
-      return unless state.respond_to?(:guardrail_flags)
+    # Best-effort write of the turn's timing onto the task record .
+    # 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)
+      return unless timing
 
-      Array(state.guardrail_flags).each do |flag|
-        emit(:guardrail_flagged, {
-               task_id: task.id, category: flag[:category], source: flag[:source], detail: flag[:detail]
-             }, task: task)
-      end
+      hash = timing.to_h
+      return if hash.empty?
+
+      @task_store.record_timing(task.id, hash)
+    rescue Insika::Error
+      nil
     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
+      # :enforce cut rides the SAME event with `action: "cut"` so the audit can
+      # distinguish a cut from a flag.
+      def emit_guardrail_flags(task, state)
+        return unless state.respond_to?(:guardrail_flags)
+
+        Array(state.guardrail_flags).each do |flag|
+          data = { task_id: task.id, category: flag[:category], source: flag[:source],
+                   detail: flag[:detail] }
+          data[:action] = flag[:action] if flag[:action]
+          emit(:guardrail_flagged, data, task: task)
+        end
+      end
+
     # Stage 8: FIXED order checkpoint -> session -> task. If it crashes
     # between writes, the worst case is a new checkpoint with the task :running ->
     # Recovery re-executes the already-saved turn (safe thanks to the side-effect
@@ -1755,7 +2431,7 @@ 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.
-    def persist_turn(task, profile, state, content, session: true, reply_origin: nil)
+    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
 
@@ -1793,7 +2469,13 @@ module Insika
       # if this turn CAME IN through a Shape B channel, its answer
       # has to travel out of band. Same terminal hook, next door to the delegation
       # one, for the same reason: it fires for a fresh turn and a recovered one.
-      finalize_channel_delivery(task, content)
+      finalize_channel_delivery(task, content, state, timing)
+
+      # extracts durable concepts from this turn, off the critical
+      # 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)
     end
 
     # Records the answer in the outbox and dispatches it. The discriminator is the
@@ -1810,31 +2492,133 @@ module Insika
     #
     # Best-effort: the turn is already committed and durable, and a delivery problem
     # must never re-fail it.
-    def finalize_channel_delivery(task, content)
+    #
+    # a PROGRESSIVE channel gets the answer split into balloons —
+    # N outbox rows, dispatched in index order (dispatch_chain). `:at_end` is the
+    # single whole-answer row, byte-identical to today.
+    def finalize_channel_delivery(task, content, state, timing = nil)
       return unless @channel_delivery
 
       channel_id = channel_transport(task)
       return unless channel_id
 
-      delivery = @channel_delivery.record(task: task, channel_id: channel_id, content: content)
-      return unless delivery
+      # 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
+      deliveries = @channel_delivery.record_balloons(
+        task: task, channel_id: channel_id, content: content,
+        progressive: @channel_delivery.progressive?(channel_id),
+        attachments: attachments
+      )
+      return if deliveries.empty?
 
-      dispatch_delivery(delivery.id)
+      timing&.mark(:first_balloon) # C5: inbound -> first outbox row, first-write-wins
+      dispatch_chain(deliveries.map(&:id))
     rescue Insika::Error
       nil
     end
 
-    # The POST goes out on the SUPERVISOR, never on the turn's fiber: a bounded
-    # retry against a third party would otherwise hold the session's FIFO — the
-    # customer's next message would wait on their previous answer's delivery.
-    # Non-serving (boot sweep, specs) delivers inline, where waiting is what the
-    # caller wants.
-    def dispatch_delivery(delivery_id)
-      return @channel_delivery.deliver(delivery_id) unless @supervised
+    # 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.
+    KNOWLEDGE_MIN_CHARS = 200
+
+    # No-op without a knowledge store, without the profile's opt-in
+    # (`knowledge.extract`), without a usable model, or for a trivially short
+    # turn. Otherwise dispatches the extraction off the critical path — the
+    # SAME `dispatch_chain` shape: inline when non-supervised (tests, CLI,
+    # 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)
+      return unless @knowledge_store
+
+      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)
+      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)
+
+      run = lambda { run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator) }
+      return run.call unless @supervised
+
+      turn_parent.async do |t|
+        t.annotate("knowledge:#{task.id}")
+        run.call
+      end
+    end
+
+    def run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator)
+      prompt = knowledge_prompt(config, new_messages)
+      result = extractor.extract(prompt: prompt)
+      result[:concepts].each do |concept|
+        outcome = Knowledge.write_concept(
+          store: @knowledge_store, agent_id: profile.id, concept: concept, session_id: task.session_id,
+          tenant: task_tenant(task), consolidator: consolidator
+        )
+        emit_knowledge_event(outcome, profile, task)
+      end
+    rescue StandardError
+      nil # best-effort: extraction never re-fails an already-committed turn.
+    end
+
+    # :new/:related taught the agent something; :contradicting needs a
+    # human; :same is a silent reinforcement (no event — a popular concept
+    # would otherwise spam the stream every time it's confirmed).
+    def emit_knowledge_event(outcome, profile, task)
+      case outcome[:verdict]
+      when :new, :related
+        emit(:knowledge_learned, { name: outcome[:name], type: outcome[:type], agent: profile.id }, task: task)
+      when :contradicting
+        emit(:knowledge_conflict, { name: outcome[:name], agent: profile.id }, task: task)
+      end
+    end
+
+    def knowledge_prompt(config, new_messages)
+      base = Coercion.presence(config["prompt"]) || Knowledge::DEFAULT_PROMPT
+      <<~PROMPT
+        #{base.rstrip}
+
+        ## 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
+
+    def utility_model
+      return nil unless @settings_store
+
+      @settings_store.get["utility_model"]
+    end
+
+    # ONE supervisor fiber for the whole chain. Sequential deliver
+    # calls, so balloon N+1 cannot overtake balloon N on the wire. Still off the
+    # session's FIFO — the customer's next message does not wait on this turn's
+    # outbound. Non-serving (boot sweep, specs) delivers inline, where waiting is
+    # what the caller wants.
+    def dispatch_chain(ids)
+      run = lambda { ids.each { |id| @channel_delivery.deliver(id) } }
+      return run.call unless @supervised
 
       turn_parent.async do |t|
-        t.annotate("outbox:#{delivery_id}")
-        @channel_delivery.deliver(delivery_id)
+        t.annotate("outbox:#{ids.first}")
+        run.call
       end
     end
 
@@ -1936,16 +2720,25 @@ module Insika
 
     # Stage 6 (factory): the ONLY point that touches the gem. lazy require,
     # confined — not covered by unit (factory line). It also loads the system
-    # builtins (load_skill/tool_search/remember) that the ChatBuilder assembles at
-    # stage 5 — lazy, so the core installs without ruby_llm.
+    # builtins (load_skill/load_knowledge/tool_search/remember) that the
+    # ChatBuilder assembles at stage 5 — lazy, so the core installs without
+    # ruby_llm.
     def create_chat(profile, state)
       require "ruby_llm"
       require_relative "tools/load_skill"
+      require_relative "tools/load_knowledge"
       require_relative "tools/tool_search"
       require_relative "tools/remember"
       require_relative "tools/subagent"
       require_relative "tools/subagents"
       require_relative "tools/stuck_signal"
+      require_relative "tools/generate_image"
+      require_relative "tools/tts"
+      require_relative "tools/update_briefing"
+      # the schedule/cancel_followup builtins — lazy, same
+      # boundary (the ChatBuilder wires them only when a profile declares
+      # followup AND the stores are present).
+      require_relative "tools/schedule_followup"
       # v2 resolution: Chat pin > Agent model > platform default, model_policy
       # enforced, fallback chain resolved. Kept on the state for telemetry (usage).
       selection = @model_resolver.resolve(profile: profile, session: state.session)