insika 0.1.0 → 0.2.0

data/lib/insika/executor.rb

@@ -19,7 +19,8 @@ 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)
       @context_builder = context_builder
       @policy_engine = policy_engine
       @middleware = middleware
@@ -36,31 +37,38 @@ 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
+      # 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
+      # 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 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 +79,15 @@ 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
       )
-      # 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 +98,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 +112,19 @@ 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
+
+    # 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
@@ -217,7 +239,7 @@ module Insika
     # 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);
+      # 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
@@ -237,7 +259,7 @@ module Insika
                                                    policy: queue_policy(profile, task.session_id))
     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 +277,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`).
@@ -293,7 +315,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 +327,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 +351,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 +359,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.
@@ -383,7 +405,7 @@ module Insika
     # 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
+      # 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
@@ -408,15 +430,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 +453,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 +471,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 +493,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.
@@ -510,8 +532,17 @@ 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::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 +557,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
@@ -537,7 +576,7 @@ module Insika
 
     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 +597,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 +636,17 @@ 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)
+      @supervisor
     end
 
     # Deterministic PendingAction id: correlation by task+turn+tool.
@@ -608,7 +655,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 +688,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
@@ -682,7 +736,7 @@ 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).
@@ -701,16 +755,16 @@ module Insika
       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
+      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.
@@ -763,9 +817,87 @@ 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. Counts and ids ONLY, never content. nil store = off; the
+    # store itself rescues everything (the trace never breaks the turn).
+    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
+        # 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
+      @context_trace_store.record(
+        session_id: task.session_id,
+        entry: { task_id: task.id, turn: state.turn, at: Time.now.utc.iso8601,
+                 cap: package.budget[:cap], used: package.budget[:used],
+                 evicted: package.budget[:evicted], categories: categories,
+                 tools: { count: state.allowed_tools.size,
+                          tokens: estimate_tools_tokens(state.allowed_tools) } }
+      )
+    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)
@@ -775,11 +907,11 @@ module Insika
       unless workflow_turn?(task)
         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;
@@ -798,6 +930,15 @@ module Insika
       timing&.mark(:done)
       data = { task_id: task.id, content: content, usage: st.usage }
       data[:timing] = timing.to_h if timing # opt-in TTFB breakdown (INSIKA_TURN_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
 
@@ -811,7 +952,7 @@ module Insika
         # 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,32 +967,20 @@ 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.
@@ -862,7 +991,7 @@ module Insika
         # 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 +1001,168 @@ 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)
+
+    # "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
+      chat.ask(state.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
+        unless ttft_sent
+          emit_ttft(task, timing) if timing
+          ttft_sent = true
+        end
+        output.push(chunk.content)
+      end
+    end
+
+    # The provider's TTFB as a live event (data: ttft_ms) — only under
+    # INSIKA_TURN_TIMING, so absent by default (parity).
+    def emit_ttft(task, timing)
+      ttft = timing.to_h[:ttft_ms]
+      return if ttft.nil?
+
+      @event_stream.emit(Insika::Event.new(
+                           type: :ttft, data: { ttft_ms: ttft },
+                           meta: { task_id: task.id, session_id: task.session_id,
+                                   at: Time.now.utc.iso8601 }
+                         ))
+    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 +1238,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 +1257,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 +1284,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 +1312,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
@@ -1036,7 +1326,7 @@ module Insika
                          checkpoint: resume_from, tenant: command_tenant(task), vars: vars)
     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,7 +1352,7 @@ 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
@@ -1071,35 +1361,35 @@ module Insika
       command_tenant(task) || task.session_id
     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)
         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 +1410,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 +1483,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 +1494,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 +1543,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 +1627,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 +1654,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,7 +1695,7 @@ 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
@@ -1420,11 +1712,11 @@ 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
@@ -1452,7 +1744,7 @@ module Insika
     # 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
@@ -1493,12 +1785,12 @@ 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)
@@ -1508,7 +1800,7 @@ module Insika
     # 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
@@ -1553,15 +1845,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 +1929,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 +1945,51 @@ 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"
+      # 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