insika 0.9.0 → 1.0.1

data/lib/insika/dsl/runtime.rb

@@ -114,7 +114,8 @@ module Insika
           edge_limiter: c[:edge_limiter],
           executor_extra: { settings_store: c[:settings_store], tool_trace_store: c[:tool_trace_store],
                             context_trace_store: c[:context_trace_store],
-                            cache_series_store: c[:cache_series_store], llm: @llm }
+                            cache_series_store: c[:cache_series_store], llm: @llm,
+                            llm_refresh: -> { c[:configurator].refresh } }
         )
         register_authoring_commands(graph, c)
         register_workflows(graph)
@@ -153,7 +154,8 @@ module Insika
         end
 
         graph.bus.register(:trigger_workflow, Insika::Commands::TriggerWorkflow.new(
-                                                profiles: graph.profiles, session_store: graph.session_store,
+                                                profiles: Insika::AgentDefaults.for_turns(graph.profiles, @components[:settings_store]),
+                                                session_store: graph.session_store,
                                                 task_store: graph.task_store, executor: graph.executor,
                                                 workflow_registry: graph.workflow_registry
                                               ))
@@ -180,9 +182,35 @@ module Insika
             attrs[:headers] = existing["headers"]
           end
           mcp_store.upsert(attrs)
+          list_tools_once(c, attrs[:name])
         end
       end
 
+      # A CODE-DECLARED server whose tools were never listed offers the agent
+      # NOTHING: the registry's `entries` reads the cached descriptors, so an empty
+      # cache means the model is never told those tools exist and answers out of its
+      # own head instead — silently, which is the worst shape a missing tool can
+      # take (a bench run caught exactly that: an agent with no catalogue invented
+      # one). So the FIRST boot lists them.
+      #
+      # A failure to list does NOT stop the boot — a stdio server behind a closed
+      # gate and a server that is momentarily down are both ordinary, and a
+      # deployment that refuses to start over either would be worse than the problem.
+      # It is said out loud instead, naming the consequence, because the failure this
+      # exists to end is the silent one.
+      #
+      # Only when the cache is empty. A later boot is free, and an operator who
+      # refreshed by hand is not overruled.
+      def list_tools_once(c, name)
+        record = c[:mcp_store].get_raw(name.to_s)
+        return unless record && record["enabled"] && Array(record["tools_cache"]).empty?
+
+        c[:mcp_tool_registry].refresh(name.to_s)
+      rescue StandardError => e
+        warn "insika: mcp \"#{name}\" was declared in code but its tools could not be listed " \
+             "(#{e.message}). The agent runs WITHOUT them until `insika mcp refresh #{name}` succeeds."
+      end
+
       def build_components(backend, spine)
         config_store = Insika::ConfigStore.new(store: backend)
         settings_store = Insika::SettingsStore.new(config_store: config_store)
@@ -235,11 +263,12 @@ module Insika
           Insika::Context::Providers::Skill.new(catalog: c[:skill_catalog]),
           Insika::Context::Providers::SkillTrigger.new(catalog: c[:skill_catalog]),
           Insika::Context::Providers::ToolSearch.new(catalog: c[:tool_catalog]),
-          Insika::Context::Providers::Memory.new(store: spine.memory_store),
-          Insika::Context::Providers::Knowledge.new(store: spine.knowledge_store),
+          Insika::Context::Providers::Memory.new(store: spine.memory_store, llm: @llm),
+          Insika::Context::Providers::Knowledge.new(store: spine.knowledge_store, llm: @llm),
           # Session briefing: read path. Inert for agents without briefing_fields.
           # Before Session, so the durable head renders above the transcript and
           # the tail recitation lands after it.
+          Insika::Context::Providers::PendingConfirmation.new(pending_action_store: spine.pending_action_store),
           Insika::Context::Providers::Briefing.new(session_store: spine.session_store),
           Insika::Context::Providers::Session.new(session_store: spine.session_store)
         ] # NOT frozen: load_plugins appends plugin providers at boot
@@ -268,6 +297,8 @@ module Insika
         # the LGPD access right — the Studio Customers drill exports.
         bus.register(:export_customer_memory, Insika::Commands::ExportCustomerMemory.new(memory_store: mem, event_stream: es))
         bus.register(:update_settings, Insika::Commands::UpdateSettings.new(settings_store: c[:settings_store], event_stream: es))
+        bus.register(:write_kit, Insika::Commands::WriteKit.new(settings_store: c[:settings_store], event_stream: es))
+        bus.register(:delete_kit, Insika::Commands::DeleteKit.new(settings_store: c[:settings_store], event_stream: es))
         bus.register(:upsert_llm_provider, Insika::Commands::UpsertLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))
         bus.register(:delete_llm_provider, Insika::Commands::DeleteLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))
         bus.register(:upsert_mcp, Insika::Commands::UpsertMcp.new(mcp_store: c[:mcp_store], mcp_registry: c[:mcp_tool_registry], event_stream: es))
@@ -310,6 +341,7 @@ module Insika
         return nil unless RubyLLM.respond_to?(:context)
 
         primary = provider_name
+        # Preserve the host instrumenter; Executor wraps a copy for each task chat.
         RubyLLM.context do |cfg|
           provider_names.each do |provider|
             # The explicit api_key/api_base belong to the PRIMARY provider; the

data/lib/insika/dsl/server_boot.rb

@@ -95,6 +95,8 @@ module Insika
           session_store: @graph.session_store,
           settings_store: @rt.component(:settings_store), llm_provider_store: @rt.component(:provider_store),
           mcp_store: @rt.component(:mcp_store), system_file_store: @rt.component(:system_file_store),
+          llm_trace_store: @graph.llm_trace_store,
+          model_metrics_store: @graph.model_metrics_store,
           tool_trace_store: @rt.component(:tool_trace_store),
           context_trace_store: @rt.component(:context_trace_store),
           # the per-agent cache-hit series (agent-detail card).
@@ -134,20 +136,10 @@ module Insika
           # config (nil without INSIKA_ARTIFACT_SIGNING_KEY) decides whether a
           # signed sharing link exists at all.
           artifact_store: @graph.artifact_store,
-          artifact_signing: artifact_signing
+          artifact_signing: Insika::ArtifactSigning.studio_config
         )
       end
 
-      # -> { key:, ttl:, base_url: } | nil (no signing key -> no signed surface).
-      def artifact_signing
-        key = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_KEY")
-        return nil if key.to_s.empty?
-
-        { key: key,
-          ttl: (Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_TTL") || 604_800).to_i,
-          base_url: Insika::Coercion.presence(Insika::EnvSchema.read("INSIKA_PUBLIC_URL")).to_s }
-      end
-
       # The frozen criterion — best-effort at boot: a bare install
       # without the env var renders the ruler's hole instead of
       # crashing the Studio.
@@ -166,7 +158,7 @@ module Insika
       end
 
       def persistence
-        @graph.durable? ? "durable (sqlite)" : "ephemeral (memory)"
+        @graph.durable? ? "durable (#{@graph.backend.class.name.split("::").last.downcase})" : "ephemeral (memory)"
       end
 
       def banner(telemetry = nil)

data/lib/insika/dsl.rb

@@ -122,13 +122,13 @@ module Insika
       # `agent { }` block that needs it instead, where `Builder#mcp` auto-adds
       # "mcp:<name>" to THAT agent's `tools_allow_groups` (below).
       def mcp(name, transport: nil, command: nil, args: nil, url: nil,
-              headers: nil, env: nil, description: nil, enabled: true)
+              headers: nil, env: nil, description: nil, enabled: true, tools: nil)
         n = name.to_s
         raise ArgumentError, "duplicate mcp instance in system: #{n}" if @mcp_instances.any? { |m| m[:name] == n }
 
         @mcp_instances << { name: n, transport: transport&.to_s, command: command, args: args,
                              url: url, headers: headers, env: env, description: description,
-                             enabled: enabled }
+                             enabled: enabled, tools: tools }
         n
       end
     end
@@ -251,20 +251,22 @@ module Insika
       # gives its own tool name; `deny_tools` has no group-string equivalent
       # yet, so a whole MCP group cannot be denied by name today.
       def mcp(name, transport: nil, command: nil, args: nil, url: nil,
-              headers: nil, env: nil, description: nil, enabled: true)
+              headers: nil, env: nil, description: nil, enabled: true, tools: nil)
         n = name.to_s
         raise ArgumentError, "duplicate mcp instance in agent: #{n}" if @mcp_instances.any? { |m| m[:name] == n }
 
         @mcp_instances << { name: n, transport: transport&.to_s, command: command, args: args,
                              url: url, headers: headers, env: env, description: description,
-                             enabled: enabled }
+                             enabled: enabled, tools: tools }
         group = "mcp:#{n}"
         (@config[:tools_allow_groups] ||= []) << group unless Array(@config[:tools_allow_groups]).include?(group)
         n
       end
 
       # --- knobs -----------------------------------------------------------
+      def shared_conversations(on = true) = @config[:shared_conversations] = on
       def memory(on = true) = @config[:memory] = on
+      def memory_retrieval(hash) = (@config[:memory_retrieval] ||= {}).merge!(hash.transform_keys(&:to_s))
 
       # Spend caps per calendar window (WS2): daily/monthly token budgets for
       # this agent, per (tenant, agent) when multi-tenant. HARD is the default:
@@ -403,7 +405,7 @@ module Insika
       # the transcriber should expect on THIS agent's voice notes — passed
       # straight through to the Whisper-family provider's `prompt:`. Falls
       # back to INSIKA_STT_PROMPT (deployment default) when unset.
-      #   stt_prompt "Ocean Drop, tênis, boné trucker, chinelo"
+      #   stt_prompt "Acme Surf, tênis, boné trucker, chinelo"
       def stt_prompt(text) = @config[:stt_prompt] = text.to_s
 
       # The engine's "Tool discipline" block in the system prompt (retry a
@@ -423,6 +425,12 @@ module Insika
       #   fencing true
       def fencing(on = true) = @config[:fencing] = on
 
+      # Tools the CUSTOMER confirms. The call is held, the reply asks, and the
+      # next message decides through confirm_pending / cancel_pending. Unlike an
+      # operator approval the turn ENDS instead of suspending.
+      #   customer_confirm "create_order"
+      def customer_confirm(*names) = @config[:customer_confirm] = names.flatten.map(&:to_s)
+
       # Content-safety guardrails — opt-in and configurable per agent.
       # Pure config-over-code: the hash is stored on the profile and consumed by
       # Safety::Config.from_profile. Merges, so repeated calls accumulate.

data/lib/insika/edge_limiter.rb

@@ -57,7 +57,7 @@ module Insika
       @event_stream = event_stream
     end
 
-    def call(state, &nxt)
+    def call(state, prepare: nil, &nxt)
       edge = platform_edge
       limits = state.profile.limits || {}
       # A resume (crash/pause recovery) re-enters the pipeline for a turn that was
@@ -100,9 +100,12 @@ module Insika
       # turn  rides the same rule: the follow-up policy is the
       # volume control, not the budget wall.
       budget_on = budget_configured?(state)
-      budget_enforce(state) unless resumed || scheduled
+      budget_notes = []
+      budget_enforce(state, notes: budget_notes) unless resumed || scheduled
 
       result = begin
+        prepare&.call(state)
+        budget_notes.each { |note| inject_budget_note(state, note) }
         nxt.call(state)
       ensure
         # A turn that FAILED after burning tokens still SPENT them: record the
@@ -154,14 +157,22 @@ module Insika
     # blind. Same billed-spend rule as `Evals::Runner#billed_tokens`.
     # nil usage (workflow turn / provider without counts) records nothing.
     def record_usage(state, window)
-      usage = state.usage || {}
-      tokens = usage[:total_tokens].to_i + usage[:cached_tokens].to_i +
-               usage[:cache_creation_tokens].to_i
+      tokens = billed_tokens(state)
       return if tokens.zero?
 
       @ledger.add(TOKENS_KIND, state.profile.id.to_s, window: window, by: tokens)
     end
 
+    # Native rerank counts remain separate from chat usage and retain unknown
+    # fields. Only reported token buckets contribute to spend enforcement.
+    def billed_tokens(state)
+      usage = state.usage || {}
+      usage[:total_tokens].to_i + usage[:cached_tokens].to_i + usage[:cache_creation_tokens].to_i +
+        Array(state.rerank_usage).sum do |entry|
+          %w[input_tokens output_tokens cache_read_tokens cache_write_tokens].sum { |key| entry[key].to_i }
+        end
+    end
+
     # Graceful halt: safe reply + audit metadata, short-circuit (no nxt).
     # `detail` carries only ids/counters — never message content.
     def block(state, edge, category:, detail:)
@@ -187,7 +198,7 @@ module Insika
 
     # -> truthy (the budget hash) when budget checks ran. Raises BudgetExceeded
     # on a HARD cap breach.
-    def budget_enforce(state, now: Time.now)
+    def budget_enforce(state, notes:, now: Time.now)
       budget = state.profile.respond_to?(:budget) ? state.profile.budget : nil
       return nil if budget.nil? || @budget_ledger.nil?
 
@@ -202,9 +213,9 @@ module Insika
               retry_after: @budget_ledger.reset_in(w[:window], now: now)
             )
           end
-          warn_budget(state, tenant, agent, w, spent, now, level: "cap")
+          warn_budget(state, tenant, agent, w, spent, now, level: "cap", notes: notes)
         elsif spent >= w[:alert_at]
-          warn_budget(state, tenant, agent, w, spent, now, level: "alert_at")
+          warn_budget(state, tenant, agent, w, spent, now, level: "alert_at", notes: notes)
         end
       end
       budget
@@ -240,10 +251,9 @@ module Insika
     # (window) cell: the `alert_at` crossing and the real soft-cap crossing are
     # separate markers, so the cap event is never swallowed by the 80% one that
     # fired earlier (WS2).
-    def warn_budget(state, tenant, agent, w, spent, now, level:)
-      inject_budget_note(state,
-                         "[budget: agent '#{agent}' is at #{spent}/#{w[:cap]} tokens this " \
-                         "#{w[:window]} window — keep this turn cheap]")
+    def warn_budget(state, tenant, agent, w, spent, now, level:, notes:)
+      notes << "[budget: agent '#{agent}' is at #{spent}/#{w[:cap]} tokens this " \
+               "#{w[:window]} window — keep this turn cheap]"
       return if @budget_ledger.mark_alert(tenant: tenant, agent: agent, window: w[:window],
                                           level: level, now: now)
 
@@ -280,9 +290,7 @@ module Insika
     # The turn's REAL billed spend (input + output + cached + cache_creation —
     # the A4 rule) on the calendar windows.
     def record_budget_usage(state, now: Time.now)
-      usage = state.usage || {}
-      tokens = usage[:total_tokens].to_i + usage[:cached_tokens].to_i +
-               usage[:cache_creation_tokens].to_i
+      tokens = billed_tokens(state)
       return if tokens.zero?
 
       @budget_ledger.add(tenant: budget_tenant(state), agent: state.profile.id.to_s,

data/lib/insika/egress_guard.rb

@@ -31,7 +31,11 @@ module Insika
     module_function
 
     # -> nil (allowed) | String (block reason).
-    def violation(url, allow_http: false, host_allowlist: nil, allow_private: false)
+    #
+    # `pin_private_only:` applies the allowlist to private destinations only, for
+    # a URL the operator fixed and the model cannot shape (an MCP server): a
+    # public host passes, a private one still needs allow_private AND the list.
+    def violation(url, allow_http: false, host_allowlist: nil, allow_private: false, pin_private_only: false)
       uri = begin
         URI.parse(url.to_s)
       rescue URI::InvalidURIError
@@ -43,13 +47,17 @@ module Insika
 
       host = uri.host
       return "missing host" if host.nil? || host.empty?
-      return "host not in allowlist" if host_allowlist && !host_allowlist.include?(host)
+      listed = host_allowlist.nil? || host_allowlist.include?(host)
+      return "host not in allowlist" unless listed || pin_private_only
 
       addrs = resolve(host)
       return "host did not resolve" if addrs.empty?
+      return nil unless addrs.any? { |ip| blocked?(ip) }
+
       # allow_private skips the private-network block (trusted internal API,
       # Without it, a private/loopback/metadata target is always blocked.
-      return "private-network destination blocked" if !allow_private && addrs.any? { |ip| blocked?(ip) }
+      return "private-network destination blocked" unless allow_private
+      return "host not in allowlist" unless listed
 
       nil
     end

data/lib/insika/env_schema.rb

@@ -9,7 +9,7 @@ module Insika
   #   · `validate(env)` — returns structured Findings: a value that fails its type
   #     (INSIKA_PORT=abc), an UNKNOWN key inside a namespace the engine owns
   #     (INSIKA_EGRES_ALLOW_HTTP — a typo the runtime would otherwise ignore in
-  #     silence), and a DEPRECATED legacy key still set under the old HARNESS_ prefix.
+  #     silence), and a REMOVED legacy key still set under the old HARNESS_ prefix.
   #     Unknown-key detection is scoped to the OWNED prefixes only, so the platform's
   #     own vars (Railway's RAILWAY_*, PORT, PATH, the litestream sidecar's
   #     LITESTREAM_*, the deployment's DEEPSEEK_*/CONSUMER_*) are never flagged.
@@ -19,12 +19,10 @@ module Insika
   #     RAISES ConfigError only when strictness is on (INSIKA_CONFIG_STRICT truthy,
   #     or `strict: true`).
   #
-  # RENAME (env pass 2): the engine's owned prefix is now INSIKA_. The old HARNESS_
-  # names still work — `reconcile_legacy!` backfills INSIKA_* from any HARNESS_* alias
-  # at boot (new name wins), and `read` gives the same dual-read to the self-contained
-  # readers (Telemetry, TurnTiming, SubagentGraph) that receive an env hash directly.
-  # A legacy name in use surfaces as a `:deprecated` warning (never fatal) so operators
-  # get a clear "rename to INSIKA_*" without a broken boot.
+  # RENAME: the engine's owned prefix is INSIKA_. The old HARNESS_ names were removed
+  # in 1.0 and are no longer read. HARNESS_ stays an OWNED prefix only so a forgotten
+  # legacy name is reported (`:removed`, an error) instead of ignored in silence — a
+  # stale HARNESS_DB would otherwise boot the engine on the ephemeral memory backend.
   #
   # Insika::Doctor reuses `validate` for its `env:*` checks; the boot roots call
   # `enforce!`. A deployment layers its own keys on via `extra:` (see
@@ -66,13 +64,13 @@ module Insika
       def to_h = { "key" => key, "kind" => kind.to_s, "severity" => severity.to_s, "message" => message }
     end
 
-    # The engine's owned prefix and its deprecated predecessor.
+    # The engine's owned prefix and its removed predecessor.
     PREFIX = "INSIKA_"
     LEGACY_PREFIX = "HARNESS_"
 
     # Prefixes the engine fully OWNS: an unknown key under one of these is a typo, not
-    # a foreign var. INSIKA_ (current) and HARNESS_ (legacy, still honored during the
-    # deprecation window). Deliberately NOT OPENCLAW_ (the OpenClaw gateway product
+    # a foreign var. INSIKA_ (current) and HARNESS_ (removed in 1.0, reported so it is
+    # not silently ignored). Deliberately NOT OPENCLAW_ (the OpenClaw gateway product
     # sets its own OPENCLAW_HOME/_STATE_DIR/… on the same host; the engine reads none
     # of them), nor LITESTREAM_ (the sidecar owns it), nor OTEL_ (the OpenTelemetry
     # SDK owns its env).
@@ -95,19 +93,26 @@ module Insika
     # The engine's own keys. Deployment/app keys (DEEPSEEK_*, CONSUMER_*, …) are NOT
     # here — a root passes them as `extra:`.
     DEFAULT = [
+      spec(name: "INSIKA_DATABASE_URL", type: :string, secret: true, description: "Postgres URL for the store (postgres://...). Set, it replaces INSIKA_DB: N workers write without SQLite's single file lock. Needs the pg gem."),
+      spec(name: "INSIKA_DATABASE_POOL", type: :integer, description: "Postgres connections per process (default 10)."),
       spec(name: "INSIKA_DB", type: :path, description: "SQLite path; durable config+state. Unset -> ephemeral memory."),
       spec(name: "INSIKA_BIND", description: "Bind address for the transport server."),
       spec(name: "INSIKA_PORT", type: :integer, description: "Port for the transport server."),
+      spec(name: "INSIKA_CONVERSATIONS_URL", type: :url, description: "Required central history URL for shared_conversations profiles."),
+      spec(name: "INSIKA_CONVERSATIONS_TOKEN", secret: true, description: "Scoped central history bearer token."),
       spec(name: "INSIKA_PUBLIC_URL", type: :url, description: "Public base URL (A2A agent card, links)."),
       spec(name: "INSIKA_ENV", description: "Environment name shown in the Studio (falls back to RACK_ENV)."),
       spec(name: "INSIKA_A2A_AGENT", description: "Agent id to expose over inbound A2A (opt-in)."),
       spec(name: "INSIKA_A2A_REMOTES", type: :csv, description: "Comma-separated remote A2A endpoints."),
       spec(name: "INSIKA_EGRESS_ALLOW_HTTP", type: :boolean, description: "Allow plain http egress from data-tools, channel callbacks and media fetches (default: https only)."),
       spec(name: "INSIKA_EGRESS_ALLOW_PRIVATE", type: :boolean, description: "Allow egress to private/loopback ranges (SSRF guard off)."),
-      spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress (media fetches are NOT pinned by it)."),
+      spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress (media fetches are NOT pinned by it; MCP servers only when they resolve to a private address)."),
       spec(name: "INSIKA_OTEL", type: :boolean, description: "Turn on OpenTelemetry export (opt-in)."),
+      spec(name: "INSIKA_MODEL_REFRESH_HOURS", type: :integer, description: "Hours between refreshes of RubyLLM's model catalog (ids, prices), kept in the store and shared by every worker. Default 24; 0 disables (the gem's bundled catalog stays)."),
       spec(name: "INSIKA_MODEL_PRICING", description: "JSON rates table (USD per million tokens) for the estimated-cost attribute; unset -> no cost reported."),
-      spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Emit per-turn TTFB breakdown in responses (opt-in)."),
+      spec(name: "INSIKA_SLOW_STORE_MS", type: :integer, description: "Log every SQLite store call that takes at least this many ms, with its caller (off when unset)."),
+      spec(name: "INSIKA_MODEL_VISIBLE_TRACES", type: :boolean, description: "Record the full model request per turn (model_visible_traces). Default on; 0 stops the write (heavy on SQLite)."),
+      spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Expose the per-turn TTFB breakdown in responses (opt-in; Studio always records it)."),
       spec(name: "INSIKA_SUBAGENT_DEPTH_CAP", type: :integer, description: "Max delegation depth in the subagent graph (default 5)."),
       spec(name: "INSIKA_SUBAGENT_FANOUT_CAP", type: :integer, description: "Max parallel children in spawn_subagents (default 8)."),
       spec(name: "INSIKA_ARTIFACT_SIGNING_KEY", secret: true, description: "HMAC key for signed artifact links (INSIKA_ARTIFACT_SIGNING_TTL). Unset -> no signed artifact surface."),
@@ -139,6 +144,8 @@ module Insika
       spec(name: "INSIKA_ROUTER_BACKEND_PORT", type: :integer, description: "the engine port on every DNS-resolved backend pod (required with INSIKA_ROUTER_BACKENDS_DNS)."),
       spec(name: "INSIKA_ROUTER_DNS_INTERVAL", type: :integer, description: "seconds between `insika-router` DNS re-resolves (default 15)."),
       spec(name: "INSIKA_ROUTER_BODY_MAX_BYTES", type: :integer, description: "size cap `insika-router` will parse looking for a session key before falling back to round-robin (default 262144; never bounds what is forwarded)."),
+      spec(name: "INSIKA_WORKERS", type: :integer, description: "Engine processes behind the session-sticky `insika-router` in one container (deploy/workers.sh). Unset or 1 = one process, no router."),
+      spec(name: "INSIKA_WORKER_BASE_PORT", type: :integer, description: "First local port for the INSIKA_WORKERS processes (default 9300)."),
       spec(name: "INSIKA_ROUTER_BACKEND_TIMEOUT", type: :integer, description: "`insika-router`'s connect/read timeout to a backend, in seconds (default 10)."),
       spec(name: "INSIKA_ROUTER_HOST", description: "bind address for `insika-router` itself (default 0.0.0.0)."),
       spec(name: "INSIKA_ROUTER_PORT", type: :integer, description: "listen port for `insika-router` itself (default 9090)."),
@@ -150,54 +157,12 @@ module Insika
       spec(name: "OTEL_SERVICE_NAME", description: "Service name for OTEL spans (default: insika).")
     ].freeze
 
-    # -- dual-read (rename compat) -------------------------------------
-
-    # HARNESS_X -> INSIKA_X for the deprecated alias of a canonical key; nil if `name`
-    # is not an INSIKA_ key.
-    def legacy_alias(name)
-      s = name.to_s
-      s.start_with?(PREFIX) ? LEGACY_PREFIX + s[PREFIX.length..] : nil
-    end
-
-    # The current (canonical) name for any owned key: HARNESS_X -> INSIKA_X; an INSIKA_
-    # key or any non-owned key is returned unchanged.
-    def canonical(name)
-      s = name.to_s
-      s.start_with?(LEGACY_PREFIX) ? PREFIX + s[LEGACY_PREFIX.length..] : s
-    end
-
     def legacy?(name) = name.to_s.start_with?(LEGACY_PREFIX)
     def owned?(name) = OWNED_PREFIXES.any? { |p| name.to_s.start_with?(p) }
 
-    # Reads a canonical INSIKA_* key, falling back to the deprecated HARNESS_* alias
-    # (new name wins). For the self-contained readers that get an env hash directly and
-    # so never see `reconcile_legacy!`'s process-wide backfill. -> value | nil.
-    def read(canonical_name, env = ENV)
-      value = env[canonical_name]
-      return value if present?(value)
-
-      (legacy = legacy_alias(canonical_name)) ? env[legacy] : value
-    end
-
-    # BOOT backfill: copies every still-set HARNESS_* var to its INSIKA_* name (new name
-    # wins if both are set) so the process ENV speaks the new names before any read.
-    # Generic (not schema-bound) so plugin/deployment HARNESS_* keys migrate too. WARNS
-    # once with the migrated list. -> [migrated legacy names]. Idempotent.
-    def reconcile_legacy!(env = ENV, warn: method(:default_warn))
-      migrated = env.keys.map(&:to_s).select { |k| k.start_with?(LEGACY_PREFIX) }.sort.each_with_object([]) do |legacy, acc|
-        canonical = PREFIX + legacy[LEGACY_PREFIX.length..]
-        next if present?(env[canonical]) # the new name already wins
-        next if env[legacy].nil?
-
-        env[canonical] = env[legacy]
-        acc << legacy
-      end
-      unless migrated.empty?
-        warn.call("deprecation: #{migrated.join(', ')} — HARNESS_* env vars are renamed to INSIKA_*; " \
-                  "honored via the new names this run, please update your environment (legacy names removed in a future release)")
-      end
-      migrated
-    end
+    # Reads an INSIKA_* key from `env`. The single reader for the self-contained
+    # readers (Telemetry, TurnTiming, SubagentGraph) that get an env hash directly.
+    def read(name, env = ENV) = env[name]
 
     # -- validation ----------------------------------------------------
 
@@ -208,33 +173,28 @@ module Insika
       findings = []
 
       # VALUE + required checks over the KNOWN specs (owned or not — DEEPSEEK_API_KEY
-      # is not prefixed). Dual-read: the canonical name wins, the legacy alias is honored.
+      # is not prefixed).
       specs.each_value do |s|
-        legacy = legacy_alias(s.name)
-        set_name = if env.key?(s.name) then s.name
-                   elsif legacy && env.key?(legacy) then legacy
-                   end
-
-        if set_name.nil?
+        unless env.key?(s.name)
           findings << Finding.new(key: s.name, kind: :missing_required, severity: :error,
                                   message: "#{s.name} is required (unset)") if s.required?
           next
         end
 
-        msg = s.error_for(env[set_name])
-        findings << Finding.new(key: set_name, kind: :invalid, severity: :error, message: "#{set_name} #{msg}") if msg
+        msg = s.error_for(env[s.name])
+        findings << Finding.new(key: s.name, kind: :invalid, severity: :error, message: "#{s.name} #{msg}") if msg
       end
 
-      # OWNED-PREFIX scan: a legacy alias of a known key is DEPRECATED (warn); any other
-      # owned key with no matching spec is UNKNOWN (a typo the runtime would ignore).
+      # OWNED-PREFIX scan: a HARNESS_ key is REMOVED (no longer read); any other owned
+      # key with no matching spec is UNKNOWN (a typo the runtime would ignore).
       env.each_key do |raw|
         key = raw.to_s
         next unless owned?(key)
 
-        if legacy?(key) && specs.key?(canonical(key))
-          findings << Finding.new(key: key, kind: :deprecated, severity: :warn,
-                                  message: "#{key} is deprecated — rename to #{canonical(key)}")
-        elsif !specs.key?(canonical(key)) && !specs.key?(key)
+        if legacy?(key)
+          findings << Finding.new(key: key, kind: :removed, severity: :error,
+                                  message: "#{key} was removed in 1.0 and is ignored — rename to #{PREFIX}#{key.delete_prefix(LEGACY_PREFIX)}")
+        elsif !specs.key?(key)
           findings << Finding.new(key: key, kind: :unknown, severity: :error,
                                   message: "#{key} is not a known config key (typo? unknown key in an owned namespace)")
         end
@@ -248,7 +208,7 @@ module Insika
 
     # BOOT GATE. Validates the environment, WARNS every finding via `warn` (a callable
     # taking a String), and RAISES ConfigError only when strict. `strict` defaults to
-    # the INSIKA_CONFIG_STRICT flag (HARNESS_CONFIG_STRICT still honored). -> [Finding]
+    # the INSIKA_CONFIG_STRICT flag. -> [Finding]
     # (also on the happy path). The root keeps booting on warnings (last-known-good).
     def enforce!(env = ENV, extra: [], strict: nil, warn: method(:default_warn))
       strict = truthy?(read("INSIKA_CONFIG_STRICT", env)) if strict.nil?