insika 0.0.1 → 0.2.0

data/lib/insika/commands/gate_refinement.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: takes a CANDIDATE for a completed
+    # refinement run, validates it against the agent's write allowlist, and scores it
+    # by actually running it — clone the agent, apply the edits to the clone, replay
+    # the golden set, compare to the accepted baseline.
+    #
+    # Synchronous like `run_refinement`, and for the same reason: it is operator-paced
+    # work with a human waiting on the answer. It is NOT cheap — the replay is a real
+    # conversation per golden case — so it is fired deliberately, never on a timer
+    # (the engine has no scheduler and this RFC does not add one).
+    #
+    # Payload:
+    #   run_id     (required) a run in :completed — the evidence the candidate answers
+    #   candidate  { proposer?, rationale?, edits: [ {file, op, anchor?, before, after,
+    #              addresses?} ] } — or omit it and pass `propose: true` to have the
+    #              configured model(s) write one from the run's findings.
+    #   propose    truthy — write the candidate with the agent's proposer PANEL.
+    #   tolerance  Float — overrides the configured judge-score tolerance for this gate
+    #
+    # -> the Run, now :awaiting_approval (gate passed), :applied (`mode: auto_apply`
+    # and the candidate cleared the extra bar) or :rejected (the gate said no).
+    #
+    # **`propose: true` is required rather than inferred from a missing candidate.**
+    # Both a proposal and a gate cost real provider money, and a caller who simply
+    # forgot the candidate should get an error, not a bill.
+    #
+    # Two refusals happen BEFORE anything is cloned, because both mean the operator
+    # has not actually enabled this: an agent still in `mode: report` (writing
+    # is opt-in and an absent config is report-only), and a candidate whose every edit
+    # was dropped (stale, off-allowlist, over budget). Neither is worth a provider bill.
+    #
+    # makes the proposal a PANEL and the run's spend a BUDGET. The
+    # command's shape does not change: N models write N candidates, the gate scores
+    # each, and the best survivor is the one proposal a human is shown. A deployment
+    # with one proposer and no budget behaves exactly as did.
+    class GateRefinement
+      WRITE_MODES = %w[propose auto_apply].freeze
+
+      # An unattended write is held to a SMALLER bar than an approved one: one edit,
+      # by default. `auto_apply` exists so a well-understood, well-golden'd agent can
+      # fix a typo'd instruction overnight — not so it can rewrite three files while
+      # nobody is looking. The operator raises it deliberately.
+      DEFAULT_AUTO_APPLY_MAX_EDITS = 1
+
+      # proposer_factory: ->(refinement_config) { [Refinement::Proposer] | Proposer | nil }.
+      # Optional — a deployment with none can still gate a candidate that arrives from
+      # the API, which is exactly what shipped before the proposer existed.
+      # resolver: the :resolve_refinement handler, used ONLY for `mode: auto_apply`.
+      # Reusing it rather than writing files here is what keeps auto-apply honest: it
+      # goes through the same staleness re-check, the same versioned write and the
+      # same `:refinement_applied` event a human approval does.
+      def initialize(profiles:, refinement_store:, agent_file_store:, gate:, event_stream:,
+                     proposer_factory: nil, resolver: nil)
+        @profiles = ProfileSource.coerce(profiles)
+        @runs = refinement_store
+        @agent_files = agent_file_store
+        @gate = gate
+        @event_stream = event_stream
+        @proposer_factory = proposer_factory
+        @resolver = resolver
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        run_id = AgentPayload.presence(p[:run_id])
+        raise Insika::ValidationError, "run_id is required" if run_id.nil?
+
+        run = @runs.find(run_id) || (raise Insika::NotFoundError, "refinement run not found: #{run_id}")
+        profile = @profiles[run.agent_id] ||
+                  (raise Insika::NotFoundError, "agent '#{run.agent_id}' not configured")
+        config = refinement_config(profile)
+        require_write_mode!(config, run.agent_id)
+        require_completed!(run)
+
+        result = run_panel(run, config, p)
+        report = (result.winner || Refinement::Panel.best_refusal(result.entries)).report
+
+        gated = @runs.gated(run.id, report: report, panel: result.entries,
+                                    cost: result.budget)
+        emit(:refinement_gated, gated, passed: report.passed, reason: report.reason,
+                                       cases: report.cases, passed_cases: report.passed_cases,
+                                       regressions: report.regressions.size,
+                                       candidates: result.entries.size,
+                                       tokens: result.budget.to_h["spent"])
+        auto_apply(gated, config, report) || gated
+      end
+
+      private
+
+      # Propose (a panel, or the caller's own candidate), build, gate, rank. The
+      # `gating` status and the `:refinement_proposed` event land BEFORE any scoring,
+      # because the scoring is minutes of real replay and a run that says nothing
+      # until it finishes looks hung.
+      def run_panel(run, config, payload)
+        panel = Refinement::Panel.new(
+          gate: @gate, proposers: proposers_for(run, config, payload),
+          budget: Refinement::Budget.new(tokens: budget_tokens(config))
+        )
+
+        panel.run(agent_id: run.agent_id, run_id: run.id, findings: run.findings,
+                  files: writable_files(run.agent_id, config),
+                  allowlist: allowlist!(run.agent_id, config),
+                  contents: current_files(run.agent_id), limits: config,
+                  raw: payload[:candidate], tolerance: payload[:tolerance]) do |entries|
+          @runs.gating(run.id, candidates: entries)
+          emit(:refinement_proposed, run, candidates: entries.size,
+                                          proposers: entries.flat_map(&:proposers).uniq,
+                                          edits: entries.sum { |e| e.candidate.edits.size })
+        end
+      end
+
+      def budget_tokens(config)
+        budget = config["budget"]
+        budget.is_a?(Hash) ? budget["tokens"] : nil
+      end
+
+      def refinement_config(profile)
+        raw = profile.respond_to?(:refinement) ? profile.refinement : nil
+        raw.is_a?(Hash) ? Coercion.deep_stringify(raw) : {}
+      end
+
+      # Editing an agent's instructions is opt-in, explicitly, per agent — the whole
+      # point of is that the reachable surface is small and declared. An absent
+      # or `report` config is not "not configured yet", it is a NO.
+      def require_write_mode!(config, agent_id)
+        mode = Coercion.presence(config["mode"]) || "report"
+        return if WRITE_MODES.include?(mode)
+
+        raise Insika::ValidationError,
+              "agent '#{agent_id}' is in refinement mode '#{mode}' — set `refinement.mode` to " \
+              "propose (and list the writable files) before gating a candidate"
+      end
+
+      # `RefinementStore#gating` refuses a run that is not :completed — but it is
+      # called AFTER the proposal, so the refusal used to arrive with the provider
+      # bill already paid. Found live: a run_id pointing at an :awaiting_approval run
+      # burned a minute and two model calls to learn the run could not be gated.
+      # Same rule as mode and allowlist: everything the engine can refuse for free
+      # is refused before a model is asked anything.
+      def require_completed!(run)
+        return if run.status == :completed
+
+        raise ArgumentError, "run #{run.id} is #{run.status}, expected completed"
+      end
+
+      # The model(s) write the candidates. Each is shown the run's findings
+      # and the CURRENT content of the allowlisted files only — the same allowlist the
+      # builder then enforces, so a proposal cannot even name a file it may not touch.
+      #
+      # A caller who supplied their own candidate needs no proposer at all; that path
+      # is what an API client and the phase-C Studio button use.
+      def proposers_for(run, config, payload)
+        return [] if payload[:candidate]
+
+        unless Insika::EnvSchema.truthy?(payload[:propose])
+          raise Insika::ValidationError,
+                "candidate is required (or pass propose: true to have the configured model write one)"
+        end
+
+        panel = Array(@proposer_factory&.call(config))
+        if panel.empty?
+          raise Insika::ValidationError,
+                "no proposer is configured for '#{run.agent_id}' — set `refinement.proposers` " \
+                "(or `refinement.proposer`, or a platform utility_model) to a model that can " \
+                "write the candidate"
+        end
+
+        panel
+      end
+
+      # The allowlist ∩ what the agent actually has. A configured file the agent never
+      # got is not shown and not editable — the builder would drop the edit anyway
+      # ("does not exist for this agent"), and paying a model to write one is waste.
+      def writable_files(agent_id, config)
+        allow = allowlist!(agent_id, config)
+        current_files(agent_id).select { |name, _| allow.include?(name) }
+      end
+
+      # Checked before the proposer runs as well as before the gate: an empty
+      # allowlist is `mode: propose` with nothing switched on, and it is the one
+      # refusal that must land before a provider call, not after it.
+      def allowlist!(agent_id, config)
+        allow = Array(config["files"]).map(&:to_s)
+        if allow.empty?
+          raise Insika::ValidationError,
+                "agent '#{agent_id}' has an empty refinement.files allowlist — nothing is writable"
+        end
+
+        allow
+      end
+
+      # `mode: auto_apply` — the ONE path where a prompt changes with no
+      # human in the loop. Off by default and deliberately narrow: it needs the mode,
+      # a gate PASS with zero regressions, and a diff under `auto_apply_max_edits`.
+      # Everything else parks at :awaiting_approval, which is the product.
+      #
+      # A candidate that passed but is too large is NOT rejected — it waits for a
+      # person. "Too big to apply unattended" and "wrong" are different verdicts, and
+      # collapsing them would throw away a proposal the gate already paid to score.
+      #
+      # Without a wired resolver this returns nil and the run stays awaiting approval:
+      # a deployment that cannot apply must not record that it did.
+      # -> the applied Run, or nil when nothing was applied.
+      def auto_apply(run, config, report)
+        return nil unless Coercion.presence(config["mode"]) == "auto_apply"
+        return nil unless run.awaiting_approval? && report.passed && report.regressions.empty?
+        return nil if @resolver.nil?
+
+        max = (config["auto_apply_max_edits"] || DEFAULT_AUTO_APPLY_MAX_EDITS).to_i
+        edits = run.edits.size
+        if edits > max
+          emit(:refinement_auto_apply_skipped, run, edits: edits, max_edits: max)
+          return nil
+        end
+
+        @resolver.call(Insika::Command.build(:resolve_refinement,
+                                             { run_id: run.id, decision: "approved",
+                                               operator: "auto_apply",
+                                               note: "auto_apply: gate passed #{report.passed_cases}/" \
+                                                     "#{report.cases} with no regression" }))
+      end
+
+      def current_files(agent_id)
+        @agent_files.list(agent_id).each_with_object({}) do |name, acc|
+          acc[name] = @agent_files.read(agent_id, name).to_s
+        end
+      end
+
+      # Counts and ids only, never file content: these events reach the operator
+      # stream and the same rule the findings follow applies here.
+      def emit(type, run, **data)
+        @event_stream.emit(Insika::Event.new(
+                             type: type,
+                             data: { agent: run.agent_id, run_id: run.id, status: run.status.to_s, **data },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/import_mcp_tools.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: LIVE MCP ingestion. Receives the NAME of
+    # an MCP instance, delegates to McpToolIngestor (discovers via an injectable client
+    # -> builds the manifest -> reuses :import_tools: batch upsert + hot reload)
+    # and returns the per-tool report in the shape of :import_tools, plus
+    # `instance:`. Idempotent (re-ingesting reconciles). A per-tool failure is isolated
+    # in `errors[]` (R4); an absent/disabled/url-less instance raises.
+    #   -> { instance, version, created: [names], updated: [names], errors: [{tool,error}] }
+    class ImportMcpTools
+      def initialize(ingestor:, event_stream:)
+        @ingestor = ingestor
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = symbolize(command.payload)
+        name = Insika::Coercion.presence(p[:name]) ||
+               (raise Insika::ValidationError, "import_mcp_tools: 'name' (MCP instance) is required")
+
+        report = @ingestor.ingest(name)
+        emit(report)
+        report
+      end
+
+      private
+
+      # Emits only COUNTS + the instance name (never headers/env/secrets): 0 leakage.
+      def emit(report)
+        @event_stream.emit(Insika::Event.new(
+                             type: :mcp_tools_imported,
+                             data: { instance: report[:instance],
+                                     created: report[:created].size, updated: report[:updated].size,
+                                     errors: report[:errors].size },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      def symbolize(payload)
+        (payload || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+    end
+  end
+end

data/lib/insika/commands/import_tools.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # BATCH ingestion of data-tools from a manifest.
+    # Normalizes each tool (defaults + envelope adapter + endpoint→url + secret/
+    # env) via ToolManifest, UPSERTs it into the ToolStore, and RELOADS the overlay +
+    # catalog ONCE at the end — takes effect without a restart. Idempotent
+    # (re-importing reconciles). Injects the deployment's `{{secret.*}}`/`{{env.*}}`
+    # resolvers: the secret NEVER comes in the manifest.
+    #
+    # ISOLATED PARTIAL FAILURE (R4): a malformed tool (invalid envelope, missing
+    # endpoint, unconfigured secret, collision with a code tool, invalid url)
+    # does NOT bring down the batch — it becomes an entry in `errors[]`. Only a STRUCTURAL error in the
+    # manifest (defaults/tools of the wrong type) raises (transport -> 422).
+    # Per-tool report in the shape of the pack importer.
+    #   -> { version, created: [names], updated: [names], errors: [{tool,error}] }
+    class ImportTools
+      def initialize(tool_store:, registry:, tool_catalog:, event_stream:, secrets: ENV, env: ENV)
+        @tool_store = tool_store
+        @registry = registry
+        @tool_catalog = tool_catalog
+        @event_stream = event_stream
+        @secrets = secrets
+        @env = env
+      end
+
+      def call(command)
+        manifest = Insika::ToolManifest.from_h(command.payload) # structural -> 422
+        report = { version: manifest.version, created: [], updated: [], errors: [] }
+
+        manifest.tools.each_with_index do |raw, i|
+          import_one(manifest, raw, i, report)
+        end
+
+        reload_hot unless report[:created].empty? && report[:updated].empty?
+        emit(report)
+        report
+      end
+
+      private
+
+      def import_one(manifest, raw, index, report)
+        defn = manifest.definition_for(raw, secrets: @secrets, env: @env)
+        name = defn["name"].to_s
+        raise Insika::ValidationError, "'#{name}' is already a code tool" if @registry.code_tool?(name)
+
+        existed = !@tool_store.get(name).nil?
+        @tool_store.write(defn)
+        (existed ? report[:updated] : report[:created]) << name
+      rescue Insika::Error => e
+        report[:errors] << { tool: tool_label(raw, index), error: e.message }
+      end
+
+      def reload_hot
+        @registry.reload
+        @tool_catalog.reload
+      end
+
+      # Tool name for the error report; falls back to the index when the envelope
+      # didn't even carry a name (keeps the error entry from being anonymous).
+      def tool_label(raw, index)
+        h = raw.is_a?(Hash) ? raw : {}
+        name = h["name"] || h[:name] || h.dig("function", "name") || h.dig(:function, :name)
+        Insika::Coercion.presence(name) || "#<tool ##{index}>"
+      end
+
+      # Emits only COUNTS + names (never headers/secrets): 0 leakage.
+      def emit(report)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tools_imported,
+                             data: { created: report[:created].size, updated: report[:updated].size,
+                                     errors: report[:errors].size },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/issue_tenant_token.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # WS1: issues a PER-TENANT token (multi_tenant mode). Operator-only BY
+    # CONSTRUCTION: the edge refuses a tenant principal on POST /v1/commands
+    # (403), and an internal command stamped with a tenant is refused here —
+    # a tenant can never mint credentials. The plaintext token is the response
+    # and exists nowhere else; the store keeps only its hash. -> Issue.to_h.
+    class IssueTenantToken
+      def initialize(token_store:, event_stream:)
+        @token_store = token_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        raise Insika::ValidationError, "token commands are operator-only" if command.meta[:tenant]
+
+        tenant_id = Insika::Coercion.presence(
+          command.payload[:tenant_id] || command.payload["tenant_id"]
+        )
+        raise Insika::ValidationError, "tenant_id is required" if tenant_id.nil?
+
+        label = command.payload[:label] || command.payload["label"] || "default"
+        issue = @token_store.issue(tenant_id: tenant_id, label: label)
+        emit(issue.id, tenant_id)
+        { token: issue.token, id: issue.id, tenant_id: tenant_id, label: label.to_s }
+      end
+
+      private
+
+      def emit(token_id, tenant_id)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_token_issued,
+                             data: { token_id: token_id, tenant_id: tenant_id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/memory_add_note.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: appends a free-form note
+    # (append-only) to the agent's memory (MemoryStore, `notes` layer). Scoped
+    # by `tenant`. Synchronous; does not create a Task. -> Note.
+    class MemoryAddNote
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        text = AgentPayload.presence(p[:text])
+        raise Insika::ValidationError, "text is required" if text.nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        note = @memory_store.add_note(tenant: tenant, text: text)
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_note_added,
+                             data: { tenant: tenant, note_id: note.id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        note
+      end
+    end
+  end
+end

data/lib/insika/commands/memory_forget_fact.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: forgets (removes) a fact from the
+    # agent's memory. Idempotent: forgetting something that doesn't exist is not an error
+    # (`existed: false`). Scoped by `tenant`. -> { existed: bool }.
+    class MemoryForgetFact
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        key = AgentPayload.presence(p[:key])
+        raise Insika::ValidationError, "key is required" if key.nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        existed = @memory_store.forget_fact(tenant: tenant, key: key)
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_fact_forgotten,
+                             data: { tenant: tenant, key: key, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/memory_put_fact.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes a stable fact to the agent's
+    # memory (MemoryStore, `profile` layer). Until now memory was only written
+    # from WITHIN the turn (the `remember` tool); this Command is the HTTP surface the
+    # Studio uses to edit facts directly. Scoped by `tenant` (nil = _default).
+    # Synchronous; does not create a Task. -> Fact.
+    class MemoryPutFact
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        key = AgentPayload.presence(p[:key])
+        raise Insika::ValidationError, "key is required" if key.nil?
+        raise Insika::ValidationError, "value is required" if p[:value].nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        fact = @memory_store.put_fact(tenant: tenant, key: key, value: p[:value])
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_fact_put,
+                             data: { tenant: tenant, key: key },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        fact
+      end
+    end
+  end
+end

data/lib/insika/commands/pause_task.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Control command: posts `:pause` to the Task's in-process
+    # mailbox and responds synchronously. Payload `{ task_id: String }` -> returns Task.
+    #
+    # Cooperative: the one that transitions `running -> paused` and emits
+    # `:task_paused` is the task's fiber when it drains at the next boundary — NEVER this
+    # handler. Pausing a task with no live fiber (terminal/orphaned) is an idempotent no-op.
+    class PauseTask
+      def initialize(task_store:, executor:)
+        @task_store = task_store
+        @executor = executor
+      end
+
+      def call(command)
+        task_id = command.payload[:task_id] || command.payload["task_id"]
+        raise Insika::ValidationError, "task_id is required" if task_id.to_s.empty?
+
+        task = @task_store.find(task_id)
+        raise Insika::NotFoundError, "task '#{task_id}' not found" unless task
+
+        @executor.pause(task_id) # no-op if there is no live fiber in this process
+        @task_store.find(task_id) # current state after the post
+      end
+    end
+  end
+end

data/lib/insika/commands/resolve_refinement.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: the human's answer to a gated proposal.
+    #
+    #   approve -> each edit is written through `AgentFileStore#write`, which pushes
+    #              the previous content into `history`. Rollback is therefore already
+    #              built: `restore_agent_file` with index 0, the same button the file
+    #              editor has had since the Studio existed.
+    #   reject  -> recorded on the run with the operator's note. The finding must
+    #              re-surface with new evidence before anything is proposed again;
+    #              nothing retries on its own.
+    #
+    # Payload `{ run_id:, decision: "approved"|"rejected", operator?, note? }`.
+    # -> the resolved Run.
+    #
+    # **The candidate is re-validated against the CURRENT files before anything is
+    # written.** The gate scored a snapshot; an operator approves minutes or days
+    # later, and in between a human may have edited the same file in the Studio.
+    # Applying an edit whose `before` no longer matches would silently overwrite that
+    # person's work — the exact failure the anchored format exists to prevent, thrown
+    # away at the last step. A stale approval is refused and the operator re-gates.
+    class ResolveRefinement
+      def initialize(profiles:, refinement_store:, agent_file_store:, event_stream:)
+        @profiles = ProfileSource.coerce(profiles)
+        @runs = refinement_store
+        @agent_files = agent_file_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        run_id = AgentPayload.presence(p[:run_id])
+        decision = AgentPayload.presence(p[:decision]).to_s
+        raise Insika::ValidationError, "run_id is required" if run_id.nil?
+
+        run = @runs.find(run_id) || (raise Insika::NotFoundError, "refinement run not found: #{run_id}")
+        operator = p[:operator] || command.meta[:operator]
+
+        case decision
+        when "rejected"
+          resolved = @runs.resolve(run.id, decision: :rejected, operator: operator, note: p[:note])
+          emit(:refinement_rejected, resolved, files: [])
+          resolved
+        when "approved"
+          apply(run, operator: operator, note: p[:note])
+        else
+          raise Insika::ValidationError, "invalid decision: #{decision} (approved|rejected)"
+        end
+      end
+
+      private
+
+      def apply(run, operator:, note:)
+        unless run.awaiting_approval?
+          raise ArgumentError, "run #{run.id} is #{run.status}, expected awaiting_approval"
+        end
+
+        config = refinement_config(run.agent_id)
+        contents = current_files(run.agent_id)
+        candidate = rebuild(run, config, contents)
+
+        written = candidate.apply(contents)
+        written.each { |file, body| @agent_files.write(run.agent_id, file, body) }
+
+        # Recorded AFTER the writes land: a crash in between leaves the run awaiting
+        # approval and the operator approves again. Re-approving re-validates against
+        # the (now edited) files and refuses as stale, which is a confusing message but
+        # a safe outcome — recording `applied` before writing would be a lie the
+        # history could not correct.
+        resolved = @runs.resolve(run.id, decision: :applied, operator: operator, note: note)
+        emit(:refinement_applied, resolved, files: written.keys, edits: candidate.edits.size)
+        resolved
+      end
+
+      # Re-runs the SAME validator the gate used, against the files as they are now.
+      # Anything that drifted comes back as a drop, and any drop at all refuses the
+      # apply: a partial application would land some edits and silently skip others,
+      # leaving a prompt in a state no one reviewed and the gate never scored.
+      def rebuild(run, config, contents)
+        allowlist = Array(config["files"]).map(&:to_s)
+        raw = { "proposer" => (run.candidate || {})["proposer"],
+                "rationale" => (run.candidate || {})["rationale"],
+                "edits" => run.edits }
+        candidate = Refinement::CandidateBuilder.build(raw, allowlist: allowlist,
+                                                            contents: contents, limits: config)
+
+        if candidate.dropped.any? || candidate.edits.size != run.edits.size
+          reasons = candidate.dropped.map { |d| "#{d.file}: #{d.reason}" }
+          raise Insika::ValidationError,
+                "the files changed since this proposal was gated, so it no longer applies " \
+                "(#{reasons.join('; ')}). Re-run the gate against the current files."
+        end
+
+        candidate
+      end
+
+      def refinement_config(agent_id)
+        profile = @profiles[agent_id] ||
+                  (raise Insika::NotFoundError, "agent '#{agent_id}' not configured")
+        raw = profile.respond_to?(:refinement) ? profile.refinement : nil
+        raw.is_a?(Hash) ? Coercion.deep_stringify(raw) : {}
+      end
+
+      def current_files(agent_id)
+        @agent_files.list(agent_id).each_with_object({}) do |name, acc|
+          acc[name] = @agent_files.read(agent_id, name).to_s
+        end
+      end
+
+      # File NAMES are fine on the stream (the operator needs to know what changed);
+      # their content is not, and never appears here.
+      def emit(type, run, **data)
+        @event_stream.emit(Insika::Event.new(
+                             type: type,
+                             data: { agent: run.agent_id, run_id: run.id, status: run.status.to_s,
+                                     by: run.decision && run.decision["by"], **data },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end