collavre 0.23.0 → 0.24.0

data/app/services/collavre/ai_agent/a2a_dispatcher.rb

@@ -15,6 +15,10 @@ module Collavre
       # Dispatch A2A events if the response mentions any AI agents
       def dispatch
         return unless @reply_comment&.content.present?
+        # An approval-action message (approve button / approved) is a human decision
+        # surface and must never reach an AI agent — not even via an @mention in
+        # another agent's reply. Same invariant as Comment#dispatch_to_orchestration.
+        return if @reply_comment.approval_action?
 
         mentioned_agents = find_mentioned_agents
         return if mentioned_agents.empty?

data/app/services/collavre/ai_agent/message_builder.rb

@@ -146,7 +146,7 @@ module Collavre
         history_chars = 0
         count = 0
 
-        Comment.public_only.where(creative_id: creative_id)
+        Comment.public_only.without_approval_action.where(creative_id: creative_id)
                .where(topic_id: topic_id)
                .where.not(user_id: nil)
                .includes(:user)

data/app/services/collavre/ai_agent/session_provisioner.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Collavre
+  module AiAgent
+    # Provisions the identities a Claude Code registration needs:
+    #   - one shared ai_user per (human, agent_name) — the Agent identity
+    #   - one Topic per (agent, session_id) — the Session identity
+    #
+    # Extracted from Api::V1::AgentsController#register so the action stays a
+    # thin orchestration of provisioning + inbox share. Behavior is identical to
+    # the inlined controller methods it replaces.
+    class SessionProvisioner
+      def initialize(user)
+        @user = user
+      end
+
+      # One ai_user per (user, agent_name) so a human's sessions share one Agent
+      # identity. Same agent_name re-registering reuses the existing row —
+      # idempotent retries (and every additional session) don't proliferate
+      # agents.
+      #
+      # Returns nil when a row with the deterministic email already exists but is
+      # owned by someone else or isn't a Claude Channel ai_user. The email format
+      # is human-derivable (user.id + slug + digest), so a foreign row could be
+      # planted by signup/import; silently reusing it would attach the caller's
+      # inbox feedback share to that foreign User and leave the plugin's
+      # AgentChannel subscription rejected on ownership mismatch. Caller renders
+      # 409 in that case.
+      def find_or_create_agent(agent_name)
+        email = session_agent_email(agent_name)
+
+        existing = User.find_by(email: email)
+        return verified_agent(existing) if existing
+
+        # routing_expression: nil so the new ai_user is not matchable until the
+        # client claims the per-agent stream via AgentChannel. See the comment on
+        # verified_agent.
+        User.create!(
+          email: email,
+          name: "Claude Channel (#{agent_name})",
+          password: SecureRandom.hex(32),
+          llm_vendor: "anthropic",
+          llm_model: "claude-code",
+          created_by_id: @user.id,
+          searchable: false,
+          routing_expression: nil
+        )
+      rescue ActiveRecord::RecordNotUnique
+        # A concurrent registration for the same (user, agent_name) won the
+        # users.email unique race. The desired row now exists — re-find and
+        # re-verify ownership instead of surfacing a 500 that aborts one of the
+        # two simultaneously launching plugin instances.
+        verified_agent(User.find_by(email: email))
+      end
+
+      # One Topic per (agent, session_id). On re-register (including --resume from
+      # the same cwd, which yields the same session_id) the existing topic is
+      # reused — even if archived — so the conversation persists instead of
+      # orphaning. A fresh session gets a new topic under the same shared agent,
+      # which is how one agent fans out to many sessions.
+      def find_or_create_topic(inbox, ai_user, session_id, session_label)
+        existing = inbox.topics.find_by(primary_agent_id: ai_user.id, session_id: session_id)
+        return existing if existing
+
+        label = session_label.to_s.strip.presence || session_id
+        inbox.topics.create!(
+          name: unique_topic_name(inbox, "Claude #{label}"),
+          user: @user,
+          primary_agent_id: ai_user.id,
+          session_id: session_id
+        )
+      end
+
+      private
+
+      # Deterministic, collision-free email key for a (user, agent_name) agent.
+      # The readable slug is lossy — "qa/bot", "qa bot" and "qa--bot" all squeeze
+      # to "qa-bot", and any all-symbol name collapses to "session" — so a short
+      # digest of the normalized raw name disambiguates distinct configured names
+      # that would otherwise alias onto ONE shared agent identity (ActionCable
+      # stream, routing state, tasks, creative shares). The slug stays for human
+      # readability; the digest decides identity. Same normalized name -> same
+      # key, so idempotent re-register/reuse is preserved. Normalization
+      # (strip+downcase) keeps case/whitespace-only differences folded, matching
+      # the prior behavior — only the lossy punctuation/spacing collapse is fixed.
+      def session_agent_email(agent_name)
+        normalized = agent_name.to_s.strip.downcase
+        slug = normalized.gsub(/[^a-z0-9-]+/, "-").squeeze("-").gsub(/\A-|-\z/, "")
+        slug = "session" if slug.blank?
+        digest = Digest::SHA256.hexdigest(normalized)[0, 10]
+        "claude-channel-#{@user.id}-#{slug}-#{digest}@agent.collavre.local"
+      end
+
+      # Returns the agent only when it is the current user's own Claude Channel
+      # agent; nil otherwise (the caller renders :conflict). Routing activation
+      # stays deferred to AgentChannel#subscribe_to_agent_stream so the agent
+      # becomes matchable only once a WebSocket subscriber exists for
+      # agent:user:<id> — otherwise comments matched between register returning
+      # and the client's subsequent cable subscribe would broadcast into an empty
+      # stream, stranding delegated tasks until stuck recovery.
+      def verified_agent(ai_user)
+        return nil unless ai_user &&
+                          ai_user.created_by_id == @user.id &&
+                          ai_user.ai_user? &&
+                          ai_user.claude_channel_agent?
+
+        ai_user
+      end
+
+      # Topics carry a UNIQUE (creative_id, name) index, so two sessions whose
+      # friendly labels collide (e.g. both rooted at a dir named "src") cannot
+      # share a name. Append the smallest numeric suffix that is free.
+      def unique_topic_name(inbox, desired)
+        return desired unless inbox.topics.exists?(name: desired)
+
+        n = 2
+        loop do
+          candidate = "#{desired} (#{n})"
+          return candidate unless inbox.topics.exists?(name: candidate)
+
+          n += 1
+        end
+      end
+    end
+  end
+end

data/app/services/collavre/ai_agent/task_claim_service.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Collavre
+  module AiAgent
+    # Atomically claims and finalizes a delegated task on behalf of a Claude
+    # Channel /reply. Extracted from Api::V1::AgentsController#reply so the
+    # controller only sequences: claim -> save comment -> finalize. Behavior is
+    # identical to the inlined controller methods it replaces.
+    class TaskClaimService
+      # Atomically claim a delegated task for completion. Two-step:
+      #   1. Find a candidate task in delegated state, scoped to this agent +
+      #      topic. With task_id supplied, exact match (required under topic
+      #      concurrency > 1 where multiple delegated tasks coexist; the client
+      #      echoes the dispatch's task_id). Without task_id (legacy clients),
+      #      oldest-first.
+      #   2. Inside a transaction: SELECT FOR UPDATE the row, re-check
+      #      status == 'delegated' under the lock, then update! to 'done'.
+      #      Concurrent claimers block on the lock; the loser sees the
+      #      already-flipped status post-lock and returns nil so the caller can
+      #      refuse the duplicate.
+      # update_all (NOT update!) is required to skip Task's after_update_commit
+      # callbacks at claim time. The callbacks fire check_trigger_loop_completion
+      # (which enqueues TriggerLoopCheckJob) and broadcast_stop_button_removal
+      # (which reads reply_comment). Both depend on the reply comment already
+      # existing — but reply() claims BEFORE comment.save to win the race against
+      # concurrent /reply calls. If update! fired the trigger-loop check here, the
+      # job could run (cooldown_seconds: 0) before comment.save commits, find no
+      # agent comment, and leave the loop stuck in "running". #finalize replays
+      # both callbacks after the comment is persisted via
+      # Task#fire_completion_callbacks_after_external_claim.
+      def claim(agent:, topic:, requested_task_id:)
+        scope = Task.where(agent_id: agent.id, topic_id: topic.id, status: "delegated")
+        candidate =
+          if requested_task_id.present?
+            scope.find_by(id: requested_task_id)
+          else
+            scope.order(:created_at).first
+          end
+        return nil unless candidate
+
+        claimed = nil
+        Task.transaction do
+          locked = Task.lock.find_by(id: candidate.id)
+          next unless locked && locked.status == "delegated"
+
+          Task.where(id: locked.id).update_all(status: "done", pending_tool_call: nil, updated_at: Time.current)
+          claimed = locked.reload
+        end
+        claimed
+      end
+
+      # Post-claim side effects, run only after the reply comment is saved. Links
+      # the comment to the claimed task, releases the ResourceTracker slot the
+      # AiAgentJob held under task.id, advances the parent workflow (if any), and
+      # drains the topic queue — mirroring AiAgentJob#perform's success path for
+      # non-delegated runs.
+      def finalize(agent:, task:, comment:)
+        comment.update_column(:task_id, task.id)
+
+        Orchestration::ResourceTracker.for(agent).release!(task.id)
+
+        if task.parent_task_id.present?
+          Collavre::Comments::WorkflowExecutor.new(task.parent_task).complete_subtask!(task)
+        end
+
+        Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
+
+        # Replay the after_update_commit callbacks that were bypassed by
+        # update_all in #claim — now that the reply comment is linked,
+        # TriggerLoopCheckJob can read it and decide whether to advance/await/
+        # complete the drop-trigger loop, and the stop-button broadcast has a
+        # comment to render.
+        task.fire_completion_callbacks_after_external_claim
+
+        # Clear the typing indicator immediately on reply. ClaudeChannelPresenceJob
+        # would also stop on its next beat (task no longer "delegated"), but that
+        # is up to HEARTBEAT_SECONDS away — broadcast idle now so the indicator
+        # drops the moment Claude's reply lands.
+        broadcast_claude_idle(agent, task, comment)
+      end
+
+      private
+
+      # Clear the chat typing indicator via the canonical status broadcaster (the
+      # same one AiAgentService uses for every other agent), so the Claude path
+      # emits an identical "idle" agent_status payload.
+      def broadcast_claude_idle(agent, task, comment)
+        creative = comment.creative&.effective_origin
+        return unless creative
+
+        AiAgent::AgentLifecycleManager.new(task: task, agent: agent, creative: creative)
+                                      .broadcast_status("idle")
+      end
+    end
+  end
+end

data/app/services/collavre/ai_client.rb

@@ -10,6 +10,49 @@ module Collavre
 
     attr_reader :last_input_tokens, :last_output_tokens
 
+    # Vendor <select> options for AI-agent config. Core ships only its built-in
+    # (stateless) providers; vendor engines append their own through
+    # register_vendor_option, so core never names a vendor engine.
+    BASE_VENDOR_OPTIONS = [
+      [ "Google (Gemini)", "google" ],
+      [ "OpenAI", "openai" ],
+      [ "Anthropic", "anthropic" ]
+    ].freeze
+
+    class << self
+      def registered_vendor_options
+        @registered_vendor_options ||= []
+      end
+
+      # Append a vendor <select> option ([label, value]). Idempotent by value.
+      def register_vendor_option(label, value)
+        value = value.to_s
+        return if BASE_VENDOR_OPTIONS.any? { |_l, v| v == value }
+        return if registered_vendor_options.any? { |_l, v| v == value }
+
+        registered_vendor_options << [ label, value ]
+      end
+
+      def vendor_options
+        BASE_VENDOR_OPTIONS + registered_vendor_options
+      end
+
+      # Vendors that use stateful/incremental sessions. Base providers are
+      # stateless; vendor engines that add session support register here so core
+      # never string-matches a vendor name to decide session behavior.
+      def session_vendors
+        @session_vendors ||= Set.new
+      end
+
+      def register_session_vendor(vendor)
+        session_vendors << vendor.to_s.downcase
+      end
+
+      def vendor_supports_session?(vendor)
+        session_vendors.include?(vendor.to_s.downcase)
+      end
+    end
+
     # log_interactions: persist each call to ActivityLog. Default true. Pass false
     # for ephemeral, high-frequency calls on text the user has not submitted (e.g.
     # inline typo correction on debounced typing) so private drafts are never
@@ -41,8 +84,16 @@ module Collavre
       add_messages(@conversation, contents)
 
       response = @conversation.complete do |chunk|
-        delta = extract_chunk_content(chunk)
-        next if delta.blank?
+        delta = extract_chunk_content(chunk).to_s
+        # Deliberately NOT `blank?`. A delta of exactly "\n\n" — the paragraph
+        # break, which providers routinely emit as a token of its own — is
+        # blank? == true, so skipping blanks deletes it. And the deleted delta is
+        # never yielded, so it is gone from the caller's stream too: AiAgentService
+        # persists ResponseStreamer#content, which is built only from the yielded
+        # deltas, and the reply lands in the database with its paragraphs glued
+        # together. Only truly empty deltas (role-only / tool-call chunks carry no
+        # content) are skippable.
+        next if delta.empty?
 
         response_content << delta
         yield delta if block_given?

data/app/services/collavre/auto_theme_generator.rb

@@ -57,7 +57,20 @@ module Collavre
     end
 
     def generate(prompt)
-      system_prompt = <<~PROMPT
+      parse_response(request_theme(prompt))
+    end
+
+    private
+
+    def request_theme(prompt)
+      @client.chat([
+        { role: :system, parts: [ { text: system_prompt } ] },
+        { role: :user, parts: [ { text: "Create a theme description: #{prompt}" } ] }
+      ])
+    end
+
+    def system_prompt
+      <<~PROMPT
         You are a color theme designer for a workspace app.
         Generate a JSON with ONLY these keys: #{REQUIRED_VARIABLES.join(', ')}.
 
@@ -181,17 +194,8 @@ module Collavre
              For dark/accent themes, h1 can use a subtle darker surface. Must not clash with text.
            - For playful themes, vary heading colors. For minimal themes, keep sizes uniform.
       PROMPT
-
-      response = @client.chat([
-        { role: :system, parts: [ { text: system_prompt } ] },
-        { role: :user, parts: [ { text: "Create a theme description: #{prompt}" } ] }
-      ])
-
-      parse_response(response)
     end
 
-    private
-
     def default_client
       AiClient.new(
         vendor: "google",

data/app/services/collavre/creatives/children_index.rb

@@ -0,0 +1,86 @@
+module Collavre
+module Creatives
+  # Per-level batch answer to "which children does this node show?" for the
+  # browse tree, replacing a per-node `children_with_permission` call.
+  #
+  # Presence (`has_children?`) is resolved for every node in a level with one
+  # plucked scan plus one batched PermissionFilter; the full child rows are
+  # materialized only for the nodes that actually render them (expanded, or a
+  # filter forcing the subtree open). Presence and content are derived from the
+  # same candidate set, so an expand toggle can never open an empty branch or
+  # hide a reachable subtree — a drift that would also leak the existence of
+  # children the user cannot see.
+  #
+  # Children of a linked shell live under its effective origin, so every lookup
+  # resolves the shell to its origin first. Preload `:origin` on the level before
+  # indexing it, or that resolution costs a query per shell.
+  class ChildrenIndex
+    def initialize(user:, show_archived:, allowed_creative_ids: nil)
+      @user = user
+      @show_archived = show_archived
+      @allowed_creative_ids = allowed_creative_ids
+      @child_ids_by_creative = {}
+      @rows_by_child_id = {}
+    end
+
+    # Scans a level. Only creatives not seen before cost anything, so the
+    # recursive descent pays two queries per level, not per node.
+    def index(creatives)
+      pending = creatives.reject { |c| @child_ids_by_creative.key?(c.id) }
+      return if pending.empty?
+
+      origin_id_by_id = pending.to_h { |c| [ c.id, c.effective_origin.id ] }
+
+      candidates = Creative.where(parent_id: origin_id_by_id.values.uniq)
+      candidates = candidates.where(archived_at: nil) unless show_archived
+      rows = candidates.order(:sequence).pluck(:id, :parent_id)
+
+      visible_by_origin = visible_child_ids_by_origin(rows)
+      pending.each do |creative|
+        @child_ids_by_creative[creative.id] = visible_by_origin[origin_id_by_id[creative.id]] || []
+      end
+    end
+
+    def has_children?(creative)
+      child_ids(creative).any?
+    end
+
+    # Materializes the child rows of `creatives` in a single query. Called only
+    # for the nodes whose children actually render.
+    def load(creatives)
+      wanted = creatives.flat_map { |c| child_ids(c) }.uniq - @rows_by_child_id.keys
+      return if wanted.empty?
+
+      Creative.where(id: wanted).each { |child| @rows_by_child_id[child.id] = child }
+    end
+
+    # Sequence-ordered, permission- and archive-filtered children. Empty unless
+    # `load` has materialized them.
+    def children_for(creative)
+      child_ids(creative).filter_map { |id| @rows_by_child_id[id] }
+    end
+
+    private
+
+    attr_reader :user, :show_archived, :allowed_creative_ids
+
+    # `rows` arrive in sequence order, so the per-origin lists inherit it.
+    def visible_child_ids_by_origin(rows)
+      return {} if rows.empty?
+
+      readable = PermissionFilter.new(user: user).readable_ids(rows.map(&:first)).to_set
+
+      rows.each_with_object({}) do |(child_id, origin_id), acc|
+        next unless readable.include?(child_id)
+        next if allowed_creative_ids && !allowed_creative_ids.include?(child_id.to_s)
+
+        (acc[origin_id] ||= []) << child_id
+      end
+    end
+
+    def child_ids(creative)
+      @child_ids_by_creative.fetch(creative.id, [])
+    end
+  end
+end
+end

data/app/services/collavre/creatives/comment_badge_index.rb

@@ -0,0 +1,73 @@
+module Collavre
+module Creatives
+  # Batches the browse tree's comment badge. Per node this was two queries — a
+  # read-pointer lookup and an unread COUNT — which is what made the badge cost
+  # scale with the size of the rendered tree.
+  #
+  # Keyed by *origin*: a linked shell shows its origin's comments.
+  class CommentBadgeIndex
+    def initialize(user:)
+      @user = user
+      @unread_by_origin_id = {}
+    end
+
+    def index(origins)
+      pending = origins.uniq(&:id).reject { |o| @unread_by_origin_id.key?(o.id) }
+      return if pending.empty?
+
+      watermarks = read_watermarks(pending.map(&:id))
+
+      # No read pointer means nothing has been read yet, so every comment counts
+      # as unread — including private ones, matching the counter cache.
+      pending.each do |origin|
+        @unread_by_origin_id[origin.id] = origin.comments_count unless watermarks.key?(origin.id)
+      end
+
+      counts = unread_counts(watermarks)
+      watermarks.each_key { |origin_id| @unread_by_origin_id[origin_id] = counts.fetch(origin_id, 0) }
+    end
+
+    # nil when the origin was never indexed, which tells the caller to fall back
+    # to the single-creative path rather than silently render a zero badge.
+    def unread_count_for(origin)
+      @unread_by_origin_id[origin.id]
+    end
+
+    private
+
+    attr_reader :user
+
+    # `user_id: nil` for an anonymous visitor is the lookup the un-batched path
+    # made too, so the two agree on which pointer (if any) applies.
+    def read_watermarks(origin_ids)
+      return {} if origin_ids.empty?
+
+      CommentReadPointer
+        .where(user_id: user&.id, creative_id: origin_ids)
+        .where.not(last_read_comment_id: nil)
+        .pluck(:creative_id, :last_read_comment_id)
+        .to_h
+    end
+
+    # One grouped COUNT for the whole level. Each origin carries its own read
+    # watermark, so the thresholds are OR-ed together rather than shared. Built
+    # from relations rather than a SQL fragment: a hand-built string here would
+    # be safe (literal template, bound values) but unprovably so to a scanner.
+    def unread_counts(watermarks)
+      return {} if watermarks.empty?
+
+      newer_than_watermark = watermarks
+        .map { |origin_id, last_read_id| unread_scope(origin_id, last_read_id) }
+        .reduce { |combined, scope| combined.or(scope) }
+
+      Comment.where(private: false).merge(newer_than_watermark).group(:creative_id).count
+    end
+
+    def unread_scope(origin_id, last_read_id)
+      Comment
+        .where(creative_id: origin_id)
+        .where(Comment.arel_table[:id].gt(last_read_id))
+    end
+  end
+end
+end

data/app/services/collavre/creatives/creative_tree_serializer.rb

@@ -0,0 +1,122 @@
+module Collavre
+module Creatives
+  # Serializes a flat collection of creatives into the lightweight JSON payload
+  # consumed by the picker popup (simple mode) and the plain browse list.
+  #
+  # Extracted from CreativesController#index so the controller action stays thin.
+  # Depends only on the acting user and the request params (read-only), never on
+  # view_context, so the whole responsibility lives outside the controller.
+  class CreativeTreeSerializer
+    def initialize(user:, params:)
+      @user = user
+      @params = params
+    end
+
+    def serialize(collection)
+      if params[:simple].present?
+        serialize_simple(collection)
+      else
+        collection.map { |c| { id: c.id, description: c.effective_description, progress: c.progress } }
+      end
+    end
+
+    private
+
+    attr_reader :user, :params
+
+    def serialize_simple(collection)
+      # Preload origins so effective_origin (used per linked-shell row in both
+      # children_presence_set and the origin_id mapping below) resolves from
+      # memory instead of firing a query per shell. Only browse can hold shells;
+      # search is scoped to origin_id: nil, so this is a no-op there.
+      ActiveRecord::Associations::Preloader.new(records: collection.to_a, associations: :origin).call
+      children_ids = children_presence_set(collection)
+      searching = params[:search].present?
+      breadcrumbs = searching ? BreadcrumbResolver.new(collection.map(&:id), user: user, include_archived: params[:show_archived].present?).call : {}
+      # For hits routed through a linked shell, the path to expand in the
+      # user's own tree (local folders -> shell) so a breadcrumb jump can
+      # reach a shell nested under a collapsed folder.
+      reveal_paths = searching ? RevealPathResolver.new(collection.map(&:id), user: user, include_archived: params[:show_archived].present?).call : {}
+      collection.map do |c|
+        item = {
+          id: c.id,
+          description: c.effective_description(nil, false),
+          progress: c.progress,
+          has_children: children_ids.include?(c.id)
+        }
+        reveal = reveal_paths[c.id]
+        path = breadcrumbs[c.id]
+        if path.present?
+          item[:path] = mask_unreachable_crumbs(path, reveal)
+        end
+        item[:reveal_path] = reveal if reveal.present?
+        # For linked shells, expose the effective origin id so the picker can
+        # map a search breadcrumb (origin ids) back to the rendered shell node.
+        item[:origin_id] = c.effective_origin.id if c.origin_id
+        item
+      end
+    end
+
+    # A breadcrumb jump expands the tree from a rendered root (or, for a shared
+    # subtree, a linked shell) down to the clicked crumb. If an ancestor above a
+    # crumb is itself unrenderable (unreadable, or archived while archived rows
+    # aren't shown) and no linked shell re-roots the path at/below it, the
+    # descendant can't be expanded either — so mask it too. BreadcrumbResolver
+    # masks the unrenderable ancestor itself; this masks everything downstream of
+    # it on the plain origin chain, matching exactly what the tree can render.
+    #
+    # `reveal` is RevealPathResolver's per-origin map: a crumb whose origin id is
+    # a key re-roots navigation through its own shell (the client anchors at the
+    # nearest reveal entry at/above the clicked crumb), so it clears the block for
+    # itself and its descendants regardless of an archived/unreadable origin
+    # above it.
+    def mask_unreachable_crumbs(path, reveal)
+      blocked = false
+      path.map do |crumb|
+        if reveal&.key?(crumb[:id])
+          blocked = false
+          crumb
+        elsif crumb[:restricted]
+          blocked = true
+          crumb
+        elsif blocked
+          crumb.merge(restricted: true, description: nil)
+        else
+          crumb
+        end
+      end
+    end
+
+    # Batched "does this node have a child the user can actually browse to?"
+    # lookup so the picker tree renders expand toggles without an N+1.
+    #
+    # Must match exactly what expanding the node shows (IndexQuery#handle_id_query
+    # -> children_with_permission, minus archived unless show_archived), or the
+    # toggle either hides a reachable subtree or opens to an empty branch (and
+    # leaks that hidden children exist). Two alignments are needed:
+    #   1. Linked shells (origin_id set) store children under the effective
+    #      origin (redirect_parent_to_origin + children->origin migration), so
+    #      resolve each row to its effective origin before the lookup.
+    #   2. Apply the same archived + read-permission filters as the browse path.
+    def children_presence_set(collection)
+      return Set.new if collection.empty?
+
+      origin_id_by_id = collection.to_h { |c| [ c.id, c.effective_origin.id ] }
+
+      candidates = Creative.where(parent_id: origin_id_by_id.values.uniq)
+      candidates = candidates.where(archived_at: nil) unless params[:show_archived]
+      child_rows = candidates.pluck(:id, :parent_id) # [child_id, origin_id]
+      return Set.new if child_rows.empty?
+
+      readable = PermissionFilter
+        .new(user: user).readable_ids(child_rows.map(&:first)).to_set
+      origins_with_visible_children = child_rows
+        .each_with_object(Set.new) { |(child_id, origin_id), set| set << origin_id if readable.include?(child_id) }
+
+      collection.each_with_object(Set.new) do |c, set|
+        set << c.id if origins_with_visible_children.include?(origin_id_by_id[c.id])
+      end
+    end
+  end
+end
+end

data/app/services/collavre/creatives/effective_creative_resolution.rb

@@ -0,0 +1,37 @@
+module Collavre
+module Creatives
+  # Single source of truth for "which creative's cache/ownership actually
+  # governs permission for this creative?".
+  #
+  # A linked creative (origin_id present) borrows its origin's permission: it
+  # has no cache entries of its own and its ownership is the origin's ownership.
+  # PermissionChecker (single-item) and PermissionFilter (batch) MUST resolve
+  # the effective creative through this module so a single check and a batch
+  # filter can never diverge for the same user + linked creative.
+  module EffectiveCreativeResolution
+    module_function
+
+    # For a single loaded creative: returns the creative whose cache/ownership
+    # governs permission. Non-linked creatives resolve to themselves.
+    def effective_creative(creative)
+      creative.origin_id.nil? ? creative : creative.origin
+    end
+
+    # For a batch of creative ids: returns { original_id => effective_id }.
+    # Linked creatives map to their origin_id; every other id (including ids
+    # not found in the table) maps to itself. This mirrors
+    # +effective_creative+ so the batch reader resolves origin identically.
+    def effective_creative_ids(ids)
+      # Coerce to Integer: origin_by_id is keyed by integer ids from pluck, so a
+      # string id (e.g. sourced from request params) would miss origin lookup
+      # and later miss the integer-keyed readable Set. Non-numeric ids can't
+      # identify a Creative, so drop them.
+      ids = ids.to_a.filter_map { |id| Integer(id, exception: false) }.uniq
+      return {} if ids.empty?
+
+      origin_by_id = Creative.where(id: ids).pluck(:id, :origin_id).to_h
+      ids.index_with { |id| origin_by_id[id] || id }
+    end
+  end
+end
+end