insika 0.1.0 → 0.3.0

data/lib/insika/executor.rb

@@ -19,7 +19,10 @@ module Insika
                    event_stream:, workflow_registry: nil, pending_action_store: nil,
                    capability_registry: nil, tool_catalog: nil, memory_store: nil,
                    tool_trace_store: nil, settings_store: nil, content_filter_factory: nil,
-                   delegation_store: nil, channel_delivery: nil, llm: nil)
+                    delegation_store: nil, channel_delivery: nil, llm: nil,
+                    context_trace_store: nil, reliability: nil, media: nil, media_output: nil,
+                    grounding_enforcer: nil, cache_series_store: nil,
+                    contact_store: nil, followup_store: nil, model_visible_trace_store: nil)
       @context_builder = context_builder
       @policy_engine = policy_engine
       @middleware = middleware
@@ -36,31 +39,63 @@ module Insika
       @pending_action_store = pending_action_store # approval gate
       @capability_registry = capability_registry # capability resolution (nil = off)
       @tool_trace_store = tool_trace_store # tool-call trace for Studio debugging (nil = off)
-      # Guardrails output filter (RFC-0009 §3.2): ->(state) { OutputFilter | nil }.
+      # 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
       # for the stream-side redaction the Executor owns.
       @content_filter_factory = content_filter_factory
-      # RFC-0010 Fase 2: durable record of ASYNC delegations. nil = async
+      # durable record of ASYNC delegations. nil = async
       # delegation OFF (only the synchronous spawn_subagent works — parity). When
       # present, run_subagent(async: true) dispatches + returns immediately and the
       # child's result is delivered to the parent session as a NEW turn on completion.
       @delegation_store = delegation_store
-      # RFC-0011 §6.5: outbound delivery for Shape B channels. nil = no channel
+      # outbound delivery for Shape B channels. nil = no channel
       # delivers out of band (parity — every surface today answers on the request's
       # own connection). When present, a turn that CAME IN through a channel writes
       # its answer to the outbox at the terminal and the dispatcher POSTs it.
       @channel_delivery = channel_delivery
-      # RFC-0017 A2: the chat FACTORY this executor asks — a RubyLLM::Context (an
+      # the chat FACTORY this executor asks — a RubyLLM::Context (an
       # isolated config dup) when the graph owns its credentials, nil = the
       # process-wide RubyLLM constant (the historic single-graph deployment).
       # Duck-typed: Context#chat and RubyLLM.chat take the same keywords.
       @llm = llm
-      # LLM config v2 (§10): resolves the model at turn start (Chat > Agent >
+      # stability for the turn's single agent interaction (WS3): retries /
+      # 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)
-      # RFC-0015 §4: the platform layer of the queue policy (nil = per-agent and
+      # 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
       # RubyLLM glue (stages 5-7): chat assembly delegated to ChatBuilder. Its
@@ -71,13 +106,27 @@ module Insika
         tool_registry: tool_registry, skill_catalog: skill_catalog,
         checkpoint_store: checkpoint_store, event_stream: event_stream, hooks: hooks,
         tool_catalog: tool_catalog, memory_store: memory_store,
-        # RFC-0010: the ChatBuilder wires the spawn_subagent system tool (gated by
+        # load_skill is not enveloped, so it records its own trace entry.
+        tool_trace_store: tool_trace_store,
+        # 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, D2
-      # injection, dedup join, ToolEnvelope wrap) — extracted collaborator (§11 B5).
+      # Stage-3-tail tool assembly (capability resolution, instantiation,
+      # injection, dedup join, ToolEnvelope wrap) — extracted collaborator.
       @tool_assembly = ToolAssembly.new(
         tool_registry: tool_registry, capability_registry: capability_registry,
         event_stream: event_stream, checkpoint_store: checkpoint_store,
@@ -88,7 +137,7 @@ module Insika
       @supervised = false      # serving mode? — see #turn_parent
       @supervisor = nil        # lazy long-lived supervisor (created when serving)
       @session_actors = {}     # session_id => SessionActor (FIFO queue)
-      @draining = false        # shutdown drain (RFC-0016 A3) — see #begin_drain!
+      @draining = false        # shutdown drain — see #begin_drain!
     end
 
     # Turns on SERVING mode: the composition root's serving arm (serve.rb /
@@ -102,7 +151,31 @@ module Insika
     # concurrency).
     attr_accessor :supervised
 
-    # RFC-0016 A3: closes the TURN intake for shutdown. Armed by Insika::Shutdown
+    # the periodic tick (outbox drain + stale recovery sweep), wired
+    # by the graph AFTER the bus exists (the tick's recovery half dispatches
+    # through it). nil = no tick (parity — recovery stays boot-only). When
+    # present and serving, it starts as a child of the turn supervisor (see
+    # #turn_parent).
+    attr_accessor :tick
+
+    # The WS6 alert dispatcher: answers budget_warning / breaker_open /
+    # delivery_failed with a durable webhook delivery. Started as a child of
+    # 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
     # spawning, while the in-flight turns run to their natural end. One-way by
@@ -203,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
 
@@ -216,8 +294,8 @@ 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)
-      # RFC-0016 A3: the intake is closed. The task is already durable (:queued);
+    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
       # gated (they spawn directly): a child of an in-flight parent is part of the
@@ -230,14 +308,15 @@ 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
 
-    # RFC-0015 §5.3 — the `collect` door, asked BEFORE a task is created.
+    # the `collect` door, asked BEFORE a task is created.
     # -> the task id the fragment joined, or nil (create a task and spawn as usual).
     #
     # Asking first is what keeps the store clean: creating a task and then
@@ -255,7 +334,7 @@ module Insika
       actor.collect(text)
     end
 
-    # RFC-0015 §5.1 — the `steer` door: a message for a session whose turn is ALREADY
+    # the `steer` door: a message for a session whose turn is ALREADY
     # running is appended to that run instead of becoming a turn of its own.
     # -> the RUNNING task's id (the turn that will answer it), or nil (create a task and
     # spawn as usual, which is `followup`).
@@ -274,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
@@ -293,7 +373,7 @@ module Insika
       task.id
     end
 
-    # RFC-0015 §6.4 — the `interrupt` door: the turn in flight is answering a question
+    # the `interrupt` door: the turn in flight is answering a question
     # the customer has already replaced, so it is abandoned and the new message becomes an
     # ordinary turn. -> the abandoned task's id, or nil (nothing was running).
     #
@@ -305,7 +385,7 @@ module Insika
     # `:cancel` is observed only at a stage boundary, so a tool call in flight runs to
     # completion and is recorded. Cancelling the not-yet-started calls of a batch would
     # leave it half applied, and fabricating failure results would teach the model that
-    # tools failed when they did not (D7 records the same boundary for `turn_timeout`).
+    # tools failed when they did not (records the same boundary for `turn_timeout`).
     def interrupt_running(session_id, profile:, replaced_by: nil)
       return nil unless @supervised && session_id
 
@@ -329,7 +409,7 @@ module Insika
     # its own, by design — it owns scheduling, not persistence).
     attr_reader :task_store
 
-    # RFC-0015 §8. Emitted by the SessionActor when a window closes having merged
+    # Emitted by the SessionActor when a window closes having merged
     # more than one fragment. `arrivals` are the ISO8601 times each fragment landed
     # — the ONLY record that they were separate messages, since a merged fragment
     # creates no task of its own. Ids and times, never content.
@@ -337,7 +417,7 @@ module Insika
       emit(:turn_coalesced, { task_id: task.id, merged: merged, arrivals: arrivals }, task: task)
     end
 
-    # RFC-0015 §5.2 — a steered message the run could NOT absorb: no tool batch ever
+    # a steered message the run could NOT absorb: no tool batch ever
     # closed (a text-only turn), the batch ended in `halt_when`, the turn failed, or it
     # was cancelled. The message is a person's and must not evaporate, so it is released
     # as the next turn on this session — which is `followup`, arrived at late.
@@ -382,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)
-      # RFC-0016 A3: a drain that started with turns already queued behind this
+    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)
@@ -408,15 +488,15 @@ module Insika
       nil
     end
 
-    # RFC-0010 (item 21): runs a CHILD agent turn (called by Tools::Subagent during
+    # runs a CHILD agent turn (called by Tools::Subagent during
     # stage 6). Isolated context (fresh child session), capability NON-inheritance
     # (child profile resolved fresh), environment inheritance (model/thinking seeded
     # from the parent). NEVER raises: a bad agent/depth/child failure is a message
     # to the model, not a turn-killer.
     #
-    # async:false (default, Fase 1) — SYNCHRONOUS: runs the child inside the parent's
+    # async:false (default) — SYNCHRONOUS: runs the child inside the parent's
     #   fiber and returns { text:, session_id: } (the child result is the tool result).
-    # async:true (Fase 2) — DURABLE dispatch: spawns the child NON-blocking, persists
+    # async:true — DURABLE dispatch: spawns the child NON-blocking, persists
     #   a Delegation, returns { dispatched:, agent:, session_id: } immediately; the
     #   parent turn ends and the child's result is later delivered as a NEW turn on
     #   the parent session (needs a delegation_store — else falls back to sync).
@@ -431,7 +511,7 @@ module Insika
       end
     end
 
-    # RFC-0010 §A (fan-out): runs SEVERAL child turns IN PARALLEL and returns all
+    # (fan-out): runs SEVERAL child turns IN PARALLEL and returns all
     # results together, in the requested order. This is the real latency win — the
     # children overlap their provider waits on the reactor, so wall-clock ≈ the
     # slowest child, not the sum. Always sync-join (a combined result in the parent's
@@ -449,7 +529,7 @@ module Insika
       { results: spawn_all_and_project(plans, parent_state) }
     end
 
-    # RFC-0010 Fase 2 (boot): reconciles ASYNC delegations after a crash so a
+    # (boot): reconciles ASYNC delegations after a crash so a
     # completed child's result is never lost. For each undelivered Delegation:
     #   · child TERMINAL, not captured -> capture + deliver.
     #   · child TERMINAL, captured (completed) -> deliver (crash before delivery).
@@ -471,7 +551,7 @@ module Insika
       { delivered: delivered }
     end
 
-    # RFC-0011 §6.5 (boot): re-drives the outbound replies a previous process
+    # (boot): re-drives the outbound replies a previous process
     # recorded and never claimed. Records left `delivering` are NOT swept — that
     # process may have POSTed before it died, and re-sending is the duplicate the
     # claim exists to prevent. No-op without a channel_delivery.
@@ -483,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
@@ -497,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.
@@ -510,8 +590,25 @@ module Insika
     rescue PolicyDenied => e
       emit(:policy_denied, { policy: e.policy, reason: e.reason }, task: task)
       fail_task(task, e, stage: :policy)
+    rescue BudgetExceeded => e
+      # WS2 hard budget: a typed, retryable failure — the envelope reads
+      # budget_exceeded + retry_after (window roll), never a silent drop.
+      fail_task(task, e, stage: :budget)
+    rescue CircuitOpenError => e
+      # WS3 breaker: the turn died BEFORE the provider call — the envelope
+      # reads circuit_open + retry_after (cooldown remaining). Worth its own
+      # stage: an open breaker is a reliability decision, not an error bug.
+      fail_task(task, e, stage: :reliability)
+    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
-      # Item 22 / §4.4: a workflow OUTPUT that violates its output_schema. Distinct
+      # a workflow OUTPUT that violates its output_schema. Distinct
       # stage so a contract breach is not conflated with an :unknown failure. (INPUT
       # is validated synchronously in TriggerWorkflow -> 422, never reaches here.)
       fail_task(task, e, stage: :workflow_schema)
@@ -526,7 +623,15 @@ module Insika
     rescue TimeoutError => e
       fail_task(task, e, stage: e.stage)
     rescue StandardError => e
-      fail_task(task, e, stage: :unknown)
+      # A provider/transport failure is NOT an :unknown bug: wrap it with its
+      # action classification (B9) so the envelope can quote retryable and the
+      # provider's own retry_after (A8). The classifier is class-name based —
+      # the :ruby_llm stage stays reachable even under the smoke-shim's fake.
+      if ProviderErrorClassifier.provider_error?(e)
+        fail_task(task, ProviderErrorClassifier.wrap(e), stage: :ruby_llm)
+      else
+        fail_task(task, e, stage: :unknown)
+      end
     ensure
       @running.delete(task.id) # ALWAYS deregister (a false-positive running? would break the resume)
       # Deregistered FIRST on purpose: from here on the `steer` door finds no actor for
@@ -535,9 +640,39 @@ 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
 
-    # RFC-0015 §4 — resolves session vars > profile.limits > settings["queue"] >
+    # resolves session vars > profile.limits > settings["queue"] >
     # defaults. One session read plus one settings read per message, the same
     # order of cost the EdgeLimiter already pays per turn. A missing session (or
     # no session store) simply drops the vars layer.
@@ -558,7 +693,7 @@ module Insika
         SessionActor.new(session_id: session_id, executor: self, parent: turn_parent)
     end
 
-    # RFC-0016 A3 — a turn that arrived while the process is draining: left
+    # a turn that arrived while the process is draining: left
     # `:queued` on purpose (recovery replays :queued at the next boot). The event
     # is the deferral's only trace — without it, "why was my message answered
     # only after the deploy" is unanswerable.
@@ -597,9 +732,23 @@ module Insika
       # 2.42): blocks on a dequeue that never arrives. Ends only when the scope is
       # stopped (server shutdown) — then any child turns still running go with it.
       # In a deployment that is the LAST resort, not the plan: Insika::Shutdown
-      # drains first (RFC-0016 A3), so only what outlives the drain deadline dies
+      # drains first, so only what outlives the drain deadline dies
       # here, `:running`, for the next boot's recovery to replay.
       @supervisor = node.async { |t| t.annotate("harness-turn-supervisor"); Async::Queue.new.dequeue }
+      # the periodic tick is a child of the supervisor — it binds to
+      # the serving reactor in every arm with no arm edits, and dies with the
+      # supervisor at shutdown (after Shutdown's drain, like any turn).
+      @tick&.start(parent: @supervisor)
+      # 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
 
     # Deterministic PendingAction id: correlation by task+turn+tool.
@@ -608,7 +757,7 @@ module Insika
     # checkpointing is a future slice. One call per tool is safe.
     def pending_id(task_id, turn, tool) = "#{task_id}:#{turn}:#{tool}"
 
-    # §11 B2: all readings of the persisted command go through rebuild_command
+    # all readings of the persisted command go through rebuild_command
     # (the single normalizer). command_type stays a STRING (the :task_started
     # event and the Telemetry attribute are string-typed).
     def command_type(task)
@@ -641,10 +790,17 @@ module Insika
         return nil
       end
 
-      @task_store.transition(task.id, to: :failed,
-                                      error: { class: error.class.name, message: error.message, stage: stage })
-      emit(:task_failed, { task_id: task.id, error: error.class.name, message: error.message }, task: task)
-      # RFC-0010 Fase 2: a FAILED delegation child still delivers — the parent
+      # The task's error record and the :task_failed event both carry the
+      # classification when the failure is a wrapped ProviderError (B9/A8):
+      # additive fields, absent for every other error.
+      classification = error.respond_to?(:classification) ? error.classification : {}
+      spec = { class: error.class.name, message: error.message, stage: stage }
+      spec = spec.merge(classification) unless classification.empty?
+      @task_store.transition(task.id, to: :failed, error: spec)
+      data = { task_id: task.id, error: error.class.name, message: error.message }
+      data = data.merge(classification) unless classification.empty?
+      emit(:task_failed, data, task: task)
+      # a FAILED delegation child still delivers — the parent
       # receives an error note as a new turn (never left hanging).
       finalize_delegation(task)
       nil
@@ -656,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)
@@ -682,12 +853,12 @@ module Insika
         end
 
         # A Middleware short-circuited (did not call the terminal). Three cases:
-        #   · halt_response set -> GRACEFUL halt (RFC-0009 §3.1): the turn COMPLETES
+        #   · halt_response set -> GRACEFUL halt: the turn COMPLETES
         #     with a safe reply, reusing stages 8-9, without ever touching the LLM.
         #   · 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
@@ -695,26 +866,41 @@ 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)
     end
 
-    # Builds the turn's mutable state (turn number, message, memory tenant, D2
+    # Builds the turn's mutable state (turn number, message, memory tenant,
     # turn context). before_task (hooks.around) may still rewrite it before stage 2.
     def build_turn_state(task, profile, resume_from)
       turn = resume_from ? resume_from.turn : 1
       state = TurnState.new(task: task, profile: profile, turn: turn,
                             message: extract_message(task))
-      state.tenant = memory_tenant(task) # WRITE-path memory scope (`remember`); =chat (D3)
-      state.turn_context = build_turn_context(task, profile, state) # data-tools' ctx.* (D2/G4)
+      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
-      # RFC-0015: resolved for the RUN, not per message, so what the turn accepts cannot
+      # resolved for the RUN, not per message, so what the turn accepts cannot
       # change under it. Same cost as the EdgeLimiter's per-turn resolution. Only for a
       # SESSION turn: steering needs a session to arrive through, and resolving here for a
       # 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
 
@@ -732,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.
@@ -763,41 +960,252 @@ module Insika
       state.requires_approval = resolution.requires_approval
       state.allowed_tools = wrap_tools(assemble_tool_instances(resolution.allowed_tools, state), state, skip)
       state.allowed_skills = resolution.allowed_skills
+      record_context_trace(task, state)
+      announce_context_skills(task, state)
       drain_and_maybe_suspend(task, actor)
     end
 
+    # one entry per turn in the ContextTraceStore — tokens per
+    # category (the demodulized provider id), the tools-schema estimate and the
+    # 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
+
+      package = state.context
+      # A custom builder that does not produce the full package (fragments +
+      # budget) simply has no breakdown to record — never an error.
+      return unless package.respond_to?(:fragments) && package.respond_to?(:budget)
+
+      categories = package.fragments.each_with_object({}) do |f, acc|
+        c = (acc[context_category(f.source)] ||= { tokens: 0, fragments: 0, pinned: 0 })
+        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
+        # after the fact.
+        labels = Array(f.labels)
+        (c[:labels] ||= []).concat(labels) unless labels.empty?
+      end
+      # 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
+    # `skills_eager`) leave no trace in the transcript: there is no load_skill to
+    # render, so an active skill looked exactly like an absent one.
+    #
+    # Emitted HERE rather than in the provider because only the Executor holds the
+    # correlation the Studio's SSE filters on — an event whose meta lacks `task_id`
+    # never reaches a task-scoped subscriber (EventStream::Subscription#matches?).
+    # `skills` (plural, with reasons) marks the CONTEXT path; the load_skill tool
+    # emits the same type with a singular `name`, and the Studio must not conflate them.
+    #
+    # Read from `package.fragments`, which is POST-BUDGET: a body the cut evicted is
+    # not in the prompt, and announcing it as active would make the one surface built
+    # to tell the truth the one that lies. Eviction is reported by the trace's own
+    # `evicted` list, never as an activation.
+    SKILL_BODY_CATEGORY = "skilltrigger"
+
+    def announce_context_skills(task, state)
+      package = state.context
+      return unless package.respond_to?(:fragments)
+
+      skills = Array(package.fragments)
+               .select { |f| context_category(f.source) == SKILL_BODY_CATEGORY }
+               .flat_map { |f| Array(f.labels) }
+               .map { |l| { name: l["name"], reason: l["reason"] || "pack" } }
+               .uniq
+      return if skills.empty?
+
+      emit(:skill_activated, { skills: skills, source: "context" }, task: task)
+    end
+
+    # "Insika::Context::Providers::Prompt" -> "prompt" (a plugin provider keeps
+    # its own demodulized name — still content-free).
+    def context_category(source) = source.to_s.split("::").last.to_s.downcase
+
+    # Same yardstick as the fragments (TokenEstimator), so the categories are
+    # comparable. `parameters` is not guaranteed JSON-safe — inspect it.
+    def estimate_tools_tokens(tools)
+      TokenEstimator.estimate(tools.map { |t| "#{t.name} #{t.description} #{t.parameters.inspect}" }.join(" "))
+    rescue StandardError
+      0
+    end
+
     # Stages 5-9 (inside the Middleware wrap): assemble chat, the single agent
     # interaction, persistence, terminal event. `st` is the Middleware-yielded state.
     def run_turn_body(task, profile, st, actor, timing = nil)
       # 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) })
-        # §11 R1: baseline = seeded-history size, before `ask` appends the turn.
+        # R1: baseline = seeded-history size, before `ask` appends the turn.
         st.chat_baseline = Array(st.chat.messages).size if st.chat.respond_to?(:messages)
       end
 
-      # guardrails (RFC-0009 §3.2): per-turn stream redactor (nil = off).
+      # guardrails: per-turn stream redactor (nil = off).
       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
+      # event (subscribable) and an additive `outcome` sibling on the terminal event.
+      if (stuck = st.stuck_outcome)
+        emit(:turn_stuck, { task_id: task.id, agent: profile.id.to_s,
+                            reason: stuck[:reason], message: content }, task: task)
+        data[:outcome] = :stuck
+      end
       emit(:task_completed, data, task: task)
     end
 
@@ -805,13 +1213,30 @@ 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)
         # workflow = a Ruby callable that orchestrates RubyLLM internally (RubyLLM
         # First). tools: are the SAME instances filtered by the Resolution and
         # enveloped (stage 7) — the workflow inherits timeout/side-effect/skip.
-        # Item 22 / §4.4: the EXPOSED surface — the run (== task.id) is announced on
+        # the EXPOSED surface — the run (== task.id) is announced on
         # the stream (:workflow_started), the RETURN is validated against the
         # output_schema (WorkflowSchemaError -> :workflow_schema stage), and the
         # typed output is published (:workflow_completed).
@@ -826,43 +1251,37 @@ module Insika
         emit(:workflow_completed, { run_id: task.id, workflow: definition.name, output: output }, task: task)
         output
       else
-        filter = state.output_filter # RFC-0009 §3.2: nil = off (stream untouched)
+        filter = state.output_filter # nil = off (stream untouched)
         timing&.mark(:ask)
         # TurnOutput owns what the customer is allowed to read: chunks ride
         # :intermediate live and only the message that ENDS the turn is published as
-        # :content. Registered on the chat (fresh per turn, so no callback leaks).
-        output = TurnOutput.new(filter: filter, emit: ->(type, data) { emit(type, data, task: task) },
-                                public_intermediate: state.profile.stream_public?(:intermediate))
-        state.chat.after_message { |message| output.message_ended(message) } if state.chat.respond_to?(:after_message)
-        # RFC-0015 §5.2: `steer` only. Registered AFTER TurnOutput so the publishing
-        # decision for a message is made before anything is appended after it — the
-        # gem's callbacks are additive and run in registration order.
-        install_steer_injector(task, state)
-
-        # `asked` is what the provider returned, BEFORE the :agent after-hook had a
-        # chance to replace it — the only way to tell an explicit substitution from
-        # the ordinary "the hook returned what it received".
+        # :content. Registered on the chat (fresh per turn/attempt, no leak).
+        # With WS3 reliability the attempts build their own chats + outputs.
+        output = nil
         asked = nil
         response = @hooks.around(:agent, state) do |s|
-          public_thinking = state.profile.stream_public?(:thinking)
-          asked = s.chat.ask(s.message) do |chunk|
-            emit_thinking(chunk, task, public: public_thinking)
-            next unless chunk.content
-
-            timing&.mark(:first_token) # first-write-wins -> the PROVIDER's TTFB
-            output.push(chunk.content)
-          end
+          result = @reliability ? run_reliable_ask(task, s, filter, timing)
+                                : run_single_ask(task, s, filter, timing)
+          output = result[:output]
+          asked = result[:asked]
+          result[:response]
         end
         # 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
         # published — so the customer read the answer of a turn that then terminated
         # `:cancelled` and persisted nothing: text delivered, transcript silent about it.
-        # Honoring it here is what makes `interrupt` (RFC-0015 §6.4) mean anything, and it
+        # Honoring it here is what makes `interrupt` mean anything, and it
         # is a safe boundary: the tool batch is finished and nothing is half applied.
         # A `:pause` is deliberately NOT honored here (drain!, not the suspending form):
         # holding a completed answer for an operator would strand it unpublished.
@@ -872,7 +1291,400 @@ module Insika
       end
     end
 
-    # RFC-0015 §5.2 — wires the tool-batch boundary that lets a message which arrived
+    # stage 6, plain path: the single ask on the assembled chat. Fresh TurnOutput
+    # + steer wiring per interaction (registered on state.chat, which the solve
+    # already assembled). -> { response:, asked:, output: }.
+    def run_single_ask(task, state, filter, timing)
+      output = new_turn_output(task, state, filter)
+      wire_chat_output(task, state, output)
+      asked = ask_on(task, state, state.chat, output, timing)
+      { response: asked, asked: asked, output: output }
+    end
+
+    # stage 6, WS3 path: the Reliability coordinator drives retries, backoff,
+    # circuit breaker and the fallback rotation. Each ATTEMPT gets a fresh chat
+    # + output (a failed `ask` leaves its message in the chat, so re-asking the
+    # same one would double the input) and, on a fallback, state.model_selection
+    # follows — the turn's usage is attributed to the model that actually spoke
+    # ("contabilizado no trace"). -> { response:, asked:, output: }.
+    def run_reliable_ask(task, state, filter, timing)
+      policy = state.profile.respond_to?(:reliability) ? state.profile.reliability : nil
+      return run_single_ask(task, state, filter, timing) if policy.nil? || @reliability.nil?
+
+      attempt_output = nil
+      attempt_asked = nil
+      primary = state.model_selection
+      response = @reliability.call(
+        policy: policy, tenant: task_tenant(task), agent: state.profile.id.to_s,
+        selection: primary, chain: reliability_chain(state)
+      ) do |selection, tries|
+        first_attempt = state.chat && selection == primary && tries == 1
+        if selection != primary
+          state.model_selection = selection # attribution follows the fallback
+        end
+        unless first_attempt
+          chat = build_attempt_chat(state, selection)
+          state.chat = chat
+        end
+        attempt_output = new_turn_output(task, state, filter)
+        wire_chat_output(task, state, attempt_output)
+        attempt_asked = ask_on(task, state, state.chat, attempt_output, timing)
+        attempt_asked
+      end
+      { response: response, asked: attempt_asked, output: attempt_output }
+    end
+
+    # The fallback chain for WS3: profile's `reliability["fallback"]` refs first,
+    # then the platform-resolved fallbacks (ModelSelection). Each node is a
+    # ModelSelection (the SAME duck the primary is — usage attribution and
+    # apply_params just work), source: :fallback, params inherited from the
+    # primary. Deduped by ref, primary excluded.
+    def reliability_chain(state)
+      primary = state.model_selection
+      refs = Array((state.profile.reliability || {})["fallback"]).map(&:to_s)
+      nodes = refs.filter_map { |r| parse_model_ref(r) }.reject { |n| n[:model].to_s.empty? }
+      nodes.concat(Array(primary.fallbacks).map { |f| { model: f[:model], provider: f[:provider] } })
+      seen = { ref_of(primary) => true }
+      nodes.filter_map do |node|
+        ref = model_ref(node)
+        # normalize "model" vs "provider/model": a provider-less ref IS the same
+        # physical model as any known "provider/model" spelling of it — the same
+        # model must never be tried twice just because one spelling omits the
+        # provider (WS3: fallback ["deepseek-v4-flash"] under primary
+        # deepseek/deepseek-v4-flash used to re-ask the dropped primary). A
+        # qualified ref still matches exactly.
+        duplicate = ref.include?("/") ? seen[ref]
+                                      : seen.keys.any? { |known| known.split("/").last == ref }
+        next if duplicate
+
+        seen[ref] = true
+        Insika::ModelSelection.new(model: node[:model], provider: node[:provider],
+                                   source: :fallback, params: primary.params, fallbacks: [])
+      end
+    end
+
+    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
+      provider = selection.respond_to?(:provider) ? selection.provider : selection[:provider]
+      provider ? "#{provider}/#{model}" : model
+    end
+
+    # "provider/model" -> { model:, provider: }; "model" -> { model:, provider: nil }.
+    def parse_model_ref(entry)
+      s = entry.to_s.strip
+      return nil if s.empty?
+
+      if s.include?("/")
+        provider, model = s.split("/", 2)
+        { model: model, provider: presence_or_nil(provider)&.to_sym }
+      else
+        { model: s, provider: nil }
+      end
+    end
+
+    def presence_or_nil(value)
+      v = value.to_s.strip
+      v.empty? ? nil : v
+    end
+
+    # A fresh chat for a retry/fallback attempt: REASSEMBLED from the same turn
+    # state (the seed history is identical), baseline reset -> the transcript
+    # recorded from than point is the attempt that spoke.
+    def build_attempt_chat(state, selection)
+      chat = build_chat(selection, state.model_selection)
+      @chat_builder.assemble(chat, state, emit: ->(type, data) { emit(type, data, task: state.task) })
+      state.chat_baseline = Array(chat.messages).size if chat.respond_to?(:messages)
+      chat
+    end
+
+    def new_turn_output(task, state, filter)
+      TurnOutput.new(filter: filter, emit: ->(type, data) { emit(type, data, task: task) },
+                     public_intermediate: state.profile.stream_public?(:intermediate))
+    end
+
+    # The message-boundary + steer wiring ON the current chat. Registered
+    # AFTER TurnOutput so the publishing decision for a message is made before
+    # anything is appended after it — the gem's callbacks are additive and run
+    # in registration order.
+    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)
+    end
+
+    # The ask itself, chunk-by-chunk (WS3 attempts and the plain path share it).
+    # With INSIKA_TURN_TIMING the FIRST content chunk also emits the live
+    # :ttft event — the streaming envelope's TTFB signal (WS6), additive. The
+    # emit is gated to that first chunk: a probe proved the old code re-emitted
+    # :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)
+      public_thinking = state.profile.stream_public?(:thinking)
+      ttft_sent = false
+      each_chunk = lambda do |chunk|
+        emit_thinking(chunk, task, public: public_thinking)
+        next unless chunk.content
+
+        timing&.mark(:first_token) # first-write-wins -> the PROVIDER's TTFB
+        unless ttft_sent
+          emit_ttft(task, timing) if timing
+          ttft_sent = true
+        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). 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?
+
+      emit(:ttft, { ttft_ms: ttft }, task: task)
+    rescue StandardError
+      nil
+    end
+
+    # wires the tool-batch boundary that lets a message which arrived
     # mid-run enter the conversation. No-op unless the agent asked for `steer`: an
     # unregistered callback is the difference between a feature that is off and one that
     # is on and finds nothing.
@@ -948,9 +1760,9 @@ module Insika
     #
     # Three deliberate omissions:
     # · the guardrail filter is NOT applied — it accumulates the PERSISTED content
-    #   (D3), and pushing reasoning through it would corrupt the turn's answer;
+    # and pushing reasoning through it would corrupt the turn's answer;
     # · `timing.mark(:first_token)` stays on the content chunks — ttft is the
-    #   PROVIDER's first token (item 34's baselines measure that, not the first
+    #   PROVIDER's first token ('s baselines measure that, not the first
     #   thought, and not when TurnOutput publishes the answer);
     # · nothing is persisted — the reasoning is not part of the conversation.
     #
@@ -967,7 +1779,7 @@ module Insika
       emit(:thinking, data, task: task)
     end
 
-    # Annotates the usage with the RESOLVED model-selection source (v2, §10):
+    # Annotates the usage with the RESOLVED model-selection source:
     # where the model came from (:chat/:agent/:platform_default) travels alongside
     # the resolved model id (from the provider) into the terminal event/Telemetry,
     # so billing/telemetry can attribute the turn to a config layer. nil usage
@@ -994,7 +1806,7 @@ module Insika
       if response.respond_to?(:cached_tokens) && response.cached_tokens
         usage[:cached_tokens] = response.cached_tokens.to_i # cache_read_input_tokens
       end
-      # §11 R3: prompt-cache WRITE tokens (Anthropic cache_creation_input_tokens),
+      # R3: prompt-cache WRITE tokens (Anthropic cache_creation_input_tokens),
       # billed at ~1.25x. Reported so the first (write) turn vs later (read) turns
       # are distinguishable in telemetry/usage.
       if response.respond_to?(:cache_creation_tokens) && response.cache_creation_tokens
@@ -1022,7 +1834,7 @@ module Insika
 
     def build_context_request(task, profile, state, resume_from)
       session = task.session_id ? @session_store.find(task.session_id) : nil
-      state.session = session # create_chat reads it for the per-chat model pin (§10)
+      state.session = session # create_chat reads it for the per-chat model pin
       hist = command_history(task)
       # `vars` reconciles the seam (the Request/Session provider already
       # called request.vars): session metadata + the explicit `history` in the
@@ -1031,12 +1843,14 @@ 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 (item 16 / P4) so
+    # task_started payload. Carries the EXPLICIT command tenant so
     # the observability convention can group by it — the one operator-set label that
     # is not derivable from the task itself. Omitted when absent: the terminal
     # events keep their shape and no consumer sees a null it never saw before. NOT
@@ -1062,44 +1876,96 @@ module Insika
       Coercion.presence(rebuild_command(task).payload["origin"])
     end
 
-    # Engine memory scope (D3): the Command's EXPLICIT tenant wins (multi-merchant
+    # Engine memory scope: the Command's EXPLICIT tenant wins (multi-merchant
     # override); otherwise the SESSION (=chat) — engine-owner memory is per-chat.
     # 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 (Phase 6/D2/G4): the ids the data-tools resolve via
+    # Turn context: the ids the data-tools resolve via
     # {{ctx.*}} to emit X-Chat-Id/X-Store-Id/X-Agent-Id to /api/internal/*. They
     # come from the TURN, never from the model args (R2). chat_id = the session
     # (the /v1/responses adapter creates the session with id = user = chat.id);
     # tenant = the Command tenant (memory) OR chat_id (drop-in default); agent_id =
     # profile; store_id = the profile metadata (stable per store, from the pack).
     # Absent fields -> nil (the data-tool emits an empty header; in the pilot the
-    # profile carries store_id). Generic: nothing here mentions achei-b2b (NF1).
+    # profile carries store_id). Generic: nothing here mentions a consumer.
     def build_turn_context(task, profile, state)
       {
         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,
-        # RFC-0010: current delegation depth (0 for a top-level turn). Carried in
+        # 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.
         delegation_depth: delegation_depth(task)
       }
     end
 
-    # Delegation depth of THIS turn (RFC-0010): the value run_subagent stamped in
+    # Delegation depth of THIS turn: the value run_subagent stamped in
     # the child command, or 0 for a top-level turn. Integer-coerced (JSON round-trip
     # of the persisted command may deliver a String).
     def delegation_depth(task)
       rebuild_command(task).payload["delegation_depth"].to_i
     end
 
-    # RFC-0010 R2: environment (model/thinking) inherits as DEFAULT — the child's
+    # R2: environment (model/thinking) inherits as DEFAULT — the child's
     # explicit value wins; when absent, seed from the parent's RESOLVED selection.
     # Capacity fields are untouched (R1: the child profile is used as-is). Returns
     # the child profile unchanged when there is nothing to inherit.
@@ -1120,7 +1986,7 @@ module Insika
       child_profile.with(model: model, provider: provider, params: params)
     end
 
-    # Single validation path for a delegation (RFC-0010) — shared by run_subagent
+    # Single validation path for a delegation — shared by run_subagent
     # and the fan-out run_subagents. `task` is {agent, message} (string OR symbol
     # keys — the model's args arrive string-keyed). Returns a resolved plan
     # { agent:, profile:, message:, depth: } or { agent:, error: } (the agent name is
@@ -1193,7 +2059,7 @@ module Insika
       [child_session_id, child_task]
     end
 
-    # SYNC (Fase 1): spawns the child and AWAITS it on the parent's fiber, then
+    # SYNC: spawns the child and AWAITS it on the parent's fiber, then
     # projects the terminal content. Direct `spawn` (not spawn_in_session): the
     # child session is brand-new, so there is no SessionActor contention — the child
     # is parented at turn_parent and the parent yields cooperatively on `wait`.
@@ -1204,7 +2070,7 @@ module Insika
       project_child_result(child_task.id, child_session_id, child_profile.id, parent_state)
     end
 
-    # ASYNC (Fase 2): persists a Delegation, spawns the child NON-blocking, and
+    # ASYNC: persists a Delegation, spawns the child NON-blocking, and
     # returns a dispatch ack immediately — the parent turn ends without waiting. The
     # child's terminal hook (finalize_delegation) delivers the result later, as a
     # NEW turn on the parent session.
@@ -1253,7 +2119,7 @@ module Insika
       exec.error && (exec.error["message"] || exec.error[:message])
     end
 
-    # RFC-0010 Fase 2 — terminal hook: when a turn ends (success OR failure), if the
+    # terminal hook: when a turn ends (success OR failure), if the
     # task is the child of an ASYNC delegation, capture its result and deliver it to
     # the parent. Fires for both a normal completion and a resumed one (recovery),
     # so it needs no live watcher fiber. No-op without a delegation_store or when the
@@ -1337,12 +2203,14 @@ module Insika
         command: rebuild_command(task),
         context: state.context,
         candidate_tools: @tool_registry.entries,
-        candidate_skills: @skill_catalog.effective(profile.skills)
+        # agent: so a specialized skill reaches the policy as the agent's own version
+        # (same name, its body) instead of the shared one it overrides.
+        candidate_skills: @skill_catalog.effective(profile.skills, agent: profile.id)
       )
     end
 
     # The Task persists the Command as a Hash; the WorkflowAllowlist needs
-    # a Command with #type (Symbol) and #payload. §11 B2: the SINGLE point that
+    # a Command with #type (Symbol) and #payload.: the SINGLE point that
     # reconciles the string||symbol keys of the persisted command — payload/meta
     # keys are stringified ONCE here, so every reader (command_type/workflow_name/
     # extract_message/command_history/command_tenant) works with string keys.
@@ -1362,7 +2230,7 @@ module Insika
       (hash || {}).each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
     end
 
-    # Stage-3-tail tool assembly — delegated to ToolAssembly (§11 B5). Kept as
+    # Stage-3-tail tool assembly — delegated to ToolAssembly. Kept as
     # thin private methods so the existing spec contract (executor.send(:...))
     # stays intact and run_pipeline reads unchanged.
     def resolve_capabilities(profile, context) = @tool_assembly.resolve_capabilities(profile, context)
@@ -1403,13 +2271,13 @@ module Insika
                              ))
     end
 
-    # GRACEFUL halt (RFC-0009 §3.1): a Middleware short-circuited with a safe reply.
+    # GRACEFUL halt: a Middleware short-circuited with a safe reply.
     # The turn COMPLETES — same stages 8-9 as a normal turn — but the "assistant
     # content" is the guardrail's safe response, produced with ZERO LLM calls. The
     # 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
 
@@ -1420,39 +2288,60 @@ module Insika
              }, task: task)
       end
       emit(:content, { delta: content }, task: task) unless content.empty?
-      # An EDGE-blocked turn (rate limit / token ceiling, item 33) completes but
+      # An EDGE-blocked turn (rate limit / token ceiling) completes but
       # stays OUT of the session history: a flood at the wall must not bloat the
       # session nor evict real conversation from the context budget — the
       # :guardrail_blocked event is the audit trail. Content-guardrail blocks
-      # keep persisting (RFC-0009: the refusal is part of the conversation).
+      # keep persisting (the refusal is part of the conversation).
       # The reply is the guardrail's, produced with zero LLM calls — so it is NOT the
       # agent talking, and a report that counts it as the agent repeating itself is
       # 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
     # recording).
     #
-    # CHECKPOINT vs SESSION — the two stores DIVERGE by design (§11 R2c):
+    # CHECKPOINT vs SESSION — the two stores DIVERGE by design (R2c):
     #   · Checkpoint.messages = flatten_history(context.history) + new_messages,
     #     i.e. "what the model actually SAW this turn" AFTER budget eviction
     #     (context.history is the post-budget assembly). It is the deterministic
@@ -1463,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
 
@@ -1493,22 +2382,22 @@ module Insika
 
       emit(:checkpoint_created, { task_id: task.id, turn: state.turn + 1 }, task: task)
 
-      # RFC-0010 Fase 2: if this completed turn is an ASYNC delegation child,
+      # if this completed turn is an ASYNC delegation child,
       # deliver its result to the parent as a NEW turn. No-op for a normal turn
       # (not a delegation child) or without a delegation_store.
       finalize_delegation(task)
 
-      # RFC-0011 §6.5: if this turn CAME IN through a Shape B channel, its answer
+      # 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
     # turn's TRANSPORT (`channel:<id>` on the persisted command), not the session:
     # a session belongs to the channel forever, but a message an operator types into
     # the Studio playground against that same session must not reach the customer.
-    # Human handoff is not a product feature (`FOLLOWUP §14.6`), and it would be a
+    # Human handoff is not a product feature (``), and it would be a
     # surprising way to acquire one.
     #
     # The consequence, stated rather than discovered later: a turn the ENGINE
@@ -1518,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
 
@@ -1553,15 +2455,15 @@ module Insika
       transport.start_with?("channel:") ? transport.delete_prefix("channel:") : nil
     end
 
-    # Truncation cap for a persisted `role: tool` content (§11 R1): the transcript
+    # Truncation cap for a persisted `role: tool` content (R1): the transcript
     # keeps the loop coherent; the FULL result lives in the ToolTraceStore (viewer).
     TOOL_CONTENT_CAP = 4_000
 
-    # The turn's messages in the ADDITIVE string-keyed format (§11 R1). Prefers the
+    # The turn's messages in the ADDITIVE string-keyed format (R1). Prefers the
     # real chat transcript (`chat.messages.drop(baseline)`) so tool calls/results
     # survive between turns; falls back to the {user, assistant} pair when the chat
     # did not record the turn (workflow, graceful halt, or the specs' FakeChat).
-    # The final assistant text is the REDACTED `content` (output_filter, RFC-0009 D3),
+    # The final assistant text is the REDACTED `content` (output_filter),
     # never the raw text the gem stored.
     # `origin` (MessageOrigin) travels on the turn's Command and is stamped on the
     # message it describes: the INCOMING one. It is absent for an ordinary turn, and
@@ -1637,7 +2539,7 @@ module Insika
     end
 
     # context.history may carry "eviction units" (an assistant+tool_results cycle
-    # grouped as one Array by the Session provider, §11 R1). Checkpoints store a
+    # grouped as one Array by the Session provider, R1). Checkpoints store a
     # FLAT list — the provider regroups on read. Flatten one level; message Hashes
     # are untouched.
     def flatten_history(history) = Array(history).flatten(1)
@@ -1653,28 +2555,58 @@ module Insika
       require_relative "tools/remember"
       require_relative "tools/subagent"
       require_relative "tools/subagents"
-      # v2 resolution (§10): Chat pin > Agent model > platform default, model_policy
+      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)
       state.model_selection = selection
+      build_chat(selection, selection)
+    end
+
+    # The gem boundary: one chat for a model selection (the resolved primary or
+    # a WS3 fallback node). The primary's generation params apply to the whole
+    # chain (params_source: ModelSelection#apply_params).
+    def build_chat(selection, params_source)
+      model = selection.respond_to?(:model) ? selection.model : selection[:model]
+      provider = selection.respond_to?(:provider) ? selection.provider : selection[:provider]
       chat = (@llm || RubyLLM).chat(
-        model: selection.model,
-        provider: selection.provider,
-        assume_model_exists: selection.assume_model_exists?
+        model: model,
+        provider: provider,
+        assume_model_exists: !provider.nil?
       )
-      selection.apply_params(chat) # temperature/max_tokens/thinking (per-agent, §10)
+      params_source.apply_params(chat) # temperature/max_tokens/thinking (per-agent)
       chat
     end
 
     # Single emitter: an Event with meta and a monotonic seq per task. @seqs is not
     # cleared at the end of the task — the resume (new Execution) continues the
-    # numbering (reliable replay).
+    # numbering (reliable replay). A task WITH a tenant (WS1) tags every event it
+    # emits — the tenant-scoped /v1/events subscription filters on it (a control
+    # event without a task has no tenant and never matches a tenant stream);
+    # absent tenant -> the meta is byte-identical to before.
     def emit(type, data, task:)
-      @event_stream.emit(Insika::Event.new(
-                           type: type, data: data,
-                           meta: { task_id: task.id, session_id: task.session_id,
-                                   seq: (@seqs[task.id] += 1), at: Time.now.utc.iso8601 }
-                         ))
+      meta = { task_id: task.id, session_id: task.session_id,
+               seq: (@seqs[task.id] += 1), at: Time.now.utc.iso8601 }
+      tenant = task_tenant(task)
+      meta[:tenant] = tenant unless tenant.nil?
+      @event_stream.emit(Insika::Event.new(type: type, data: data, meta: meta))
+    end
+
+    # The tenant stamped on the task's command (WS1), nil when the request was
+    # operator-made. Cheap read on the persisted command hash — never rebuilds.
+    def task_tenant(task)
+      command = task.respond_to?(:command) ? task.command : nil
+      return nil unless command.is_a?(Hash)
+
+      meta = command["meta"] || command[:meta] || {}
+      meta["tenant"] || meta[:tenant]
     end
   end
 end