insika 0.2.0 → 0.3.0

data/lib/insika/executor.rb

@@ -20,7 +20,9 @@ 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)
       @context_builder = context_builder
       @policy_engine = policy_engine
       @middleware = middleware
@@ -40,6 +42,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,10 +70,31 @@ 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
@@ -84,7 +111,19 @@ 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
       )
       # Stage-3-tail tool assembly (capability resolution, instantiation,
       # injection, dedup join, ToolEnvelope wrap) — extracted collaborator.
@@ -124,6 +163,18 @@ 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
+
     # 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 +276,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 +294,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 +308,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 +353,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 +462,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 +563,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 +577,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 +599,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 +640,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 +742,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 +812,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 +858,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 +866,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 +887,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 +895,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 +918,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 +967,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 +986,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 +997,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 +1129,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 +1146,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 +1213,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)
@@ -985,7 +1269,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 +1365,228 @@ 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 parts become the ask's attachments (the model
+    # sees them; the provider bills them — usage flows) and the first URL is
+    # deposited as `ctx.image_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) }.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.media_attachments = images.map { |p| media_attachment(p.url) }
+        # 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
+
+      # 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.
+    def media_transcribe(url)
+      transcriber = @media || (@default_transcriber ||= Insika::Media.default_transcriber(
+        stt_model: Insika::EnvSchema.read("INSIKA_STT_MODEL"),
+        stt_language: Insika::EnvSchema.read("INSIKA_STT_LANGUAGE")
+      ))
+      transcriber.call(url)
+    end
+
+    # An image part -> the ask's attachment. RubyLLM required lazily (load-guard).
+    #
+    # The bytes come through OUR fetch (`Media.fetch_binary`), which is
+    # egress-guarded — the URL is CONSUMER input, so a private/metadata target
+    # fails the turn loudly at :media — and SIZE-CAPPED. Handing the raw URL to
+    # `RubyLLM::Attachment` instead left the fetch to the gem, whose
+    # `fetch_content` reads the whole response with no ceiling: a hostile URL
+    # answering an endless body grows this process until it dies. An io-like
+    # source (StringIO) is the branch of Attachment that takes bytes we already
+    # hold; the provider then gets base64 rather than the URL, which every
+    # vision provider accepts.
+    def media_attachment(url)
+      require "ruby_llm"
+      require "stringio"
+
+      bytes = Insika::Media.fetch_binary(url, max_bytes: Insika::Media::MAX_IMAGE_BYTES)
+      RubyLLM::Attachment.new(StringIO.new(bytes), filename: media_filename(url))
+    end
+
+    # The URL's basename, for the attachment's mime sniff (".png" -> image/png;
+    # a URL with no filename falls back to the content sniff RubyLLM does).
+    def media_filename(url)
+      name = File.basename(URI.parse(url).path.to_s)
+      name.empty? ? nil : name
+    rescue URI::InvalidURIError
+      nil
+    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
@@ -1134,7 +1646,7 @@ module Insika
     def ask_on(task, state, chat, output, timing)
       public_thinking = state.profile.stream_public?(:thinking)
       ttft_sent = false
-      chat.ask(state.message) do |chunk|
+      each_chunk = lambda do |chunk|
         emit_thinking(chunk, task, public: public_thinking)
         next unless chunk.content
 
@@ -1145,19 +1657,29 @@ module Insika
         end
         output.push(chunk.content)
       end
+      # 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 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 +1843,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 +1881,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,7 +1946,10 @@ 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,
         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
@@ -1701,7 +2277,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 +2298,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 +2352,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 +2390,7 @@ 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)
     end
 
     # Records the answer in the outbox and dispatches it. The discriminator is the
@@ -1810,31 +2407,44 @@ 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
+    # 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
 
@@ -1946,6 +2556,13 @@ module Insika
       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)