collavre 0.24.0 → 0.25.0

data/app/jobs/collavre/ai_agent_job.rb

@@ -1,51 +1,91 @@
 module Collavre
   class AiAgentJob < ApplicationJob
-    queue_as :default
+    queue_as :ai_agents
 
     # Allow resuming a task that was pending approval
     def perform(agent_id_or_task, event_name = nil, context = nil)
       if agent_id_or_task.is_a?(Task)
         # Resume existing task
         task = agent_id_or_task
-        return if task.reload.status == "cancelled"
+        if task.reload.status == "cancelled"
+          # A cancelled task can still be holding the topic slot. Promotion moves
+          # a waiter queued -> pending and enqueues this job, and the whole gap
+          # from that claim until this line is one where deleting the comment it
+          # answers cancels it (Comment#cancel_pending_tasks covers `pending`).
+          # Returning bare hands the slot to nobody, so the waiters behind it sit
+          # queued until orphan recovery. Same reason the fold's own cancelled
+          # branch below drains — this is the earlier door onto it.
+          if task.trigger_event_payload&.key?("topic")
+            Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
+          end
+          return
+        end
 
         agent = task.agent
 
         # Guard: same offline-session check as the agent_id branch below.
         # Queued Claude Channel tasks resumed via Orchestration::AgentOrchestrator
         # .dequeue_next_for_topic enter this branch as AiAgentJob.perform_later(task).
-        # If AgentChannel#unsubscribed cleared routing_expression while the
+        # If AgentChannel#unsubscribed removed the last presence row while the
         # task was queued (WS drop without DELETE /agent/:id, e.g. SIGKILL or
         # network blip past the reconnect grace), and another completion later
         # drains the queue, this task would otherwise be promoted to running →
         # delegated and broadcast to a clientless agent:user:<id> stream —
         # held until stuck recovery.
-        if agent.claude_channel_agent? && agent.routing_expression.blank?
+        if agent.claude_channel_agent? && !agent.claude_channel_online?
           Rails.logger.info(
             "[AiAgentJob] Skipping resumed Claude Channel task #{task.id}: " \
-            "session offline (routing_expression blank)"
+            "session offline (no live presence)"
           )
-          # Workflow subtasks created by WorkflowExecutor carry parent_task_id and
-          # no topic. If we only cancel the child and return, the parent workflow
-          # stays "running" with its current/pending creative state forever — no
-          # rescue path runs because we never raise. Mirror the StandardError
-          # rescue below: fail the child and notify the parent so the workflow
-          # transitions to "failed" with a failure_reason.
-          if task.parent_task_id.present?
-            task.update!(status: "failed")
-            Collavre::Comments::WorkflowExecutor.new(task.parent_task).fail_subtask!(
-              task,
-              error_message: "Claude Channel session offline before dispatch"
-            )
-          else
-            task.update!(status: "cancelled")
-          end
+          task.update!(status: "cancelled")
           if task.trigger_event_payload&.key?("topic")
             Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
           end
           return
         end
 
+        # A claimed task holds the topic slot as `pending` from promotion until
+        # this line, and a comment arriving in that window parks a waiter that
+        # enqueue-time coalescing cannot fold into a non-`queued` sibling. Both
+        # turns are still un-started here, so this is the last place the fold
+        # can happen — and it must run before the assignment guard below, which
+        # reads the payload this may re-anchor.
+        Orchestration::AgentOrchestrator.coalesce_at_start!(task)
+        if task.reload.status == "cancelled"
+          # The fold's re-anchor found no comment left to answer. A `pending`
+          # task holds no ResourceTracker reservation yet (reserve! is below),
+          # but it does hold the topic slot — drain or the queue stalls.
+          Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
+          return
+        end
+
+        # Guard: an exclusive primary-agent assignment can also land after a task
+        # has already been cleared for execution, so checking at enqueue time is
+        # not sufficient. AgentOrchestrator.dequeue_next_for_topic revalidates and
+        # then enqueues asynchronously — a pin created in that window is missed —
+        # and approval resumption (Comments::ActionExecutor) re-enqueues a
+        # pending_approval task with no check at all, after a pause that can last
+        # as long as the human takes to approve. Re-check at the moment of
+        # execution so a demoted agent cannot answer in a topic that is now
+        # exclusively someone else's.
+        resumed_context = task.trigger_event_payload
+        if resumed_context&.key?("topic") &&
+           !Orchestration::Matcher.permits_assignment?(resumed_context, agent)
+          Rails.logger.info(
+            "[AiAgentJob] Cancelling resumed task #{task.id}: topic #{task.topic_id} " \
+            "is now assigned to another agent (agent=#{agent.id})"
+          )
+          task.update!(status: "cancelled")
+          # A pending_approval task kept its slot across the pause (the
+          # ApprovalPendingError rescue sets should_release = false), and this
+          # early return skips the ensure block that would give it back, so
+          # release explicitly. release! is idempotent, so a queued task that
+          # never reserved one is unaffected.
+          Orchestration::ResourceTracker.for(agent).release!(task.id)
+          Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
+          return
+        end
+
         task.update!(status: "running")
       else
         # Create new task
@@ -53,17 +93,33 @@ module Collavre
 
         # Guard: skip if the Claude Channel session has unregistered (or its WS
         # dropped) during the window between Scheduler enqueue and this job
-        # firing. AgentsController#destroy / AgentChannel#unsubscribed clear
-        # routing_expression on the per-session ai_user, so a blank value here
-        # means there is no live MCP client to receive the dispatch. Without
+        # firing. AgentsController#destroy / AgentChannel#unsubscribed remove
+        # the last presence row, so no live presence here means there is no MCP
+        # client to receive the dispatch. Without
         # this guard, a :delayed (busy / rate-limited) enqueue from
         # Scheduler#evaluate would materialize a fresh Task, flip it to
         # "delegated", and broadcast to a clientless agent:user:<id> stream
         # — holding the topic/agent slot until stuck recovery.
-        if agent.claude_channel_agent? && agent.routing_expression.blank?
+        if agent.claude_channel_agent? && !agent.claude_channel_online?
           Rails.logger.info(
             "[AiAgentJob] Skipping Claude Channel job for agent #{agent.id}: " \
-            "session offline (routing_expression blank, event=#{event_name})"
+            "session offline (no live presence, event=#{event_name})"
+          )
+          return
+        end
+
+        # Guard: an exclusive primary-agent assignment created (or moved) after
+        # this dispatch was scheduled must still bind it. A :delayed decision
+        # (agent busy / rate limited) sits in the job queue with its agent already
+        # chosen and is never re-matched, so without this a demoted agent speaks
+        # in a topic that now belongs to someone else. Unlike a queued waiter
+        # there is no Task yet to cancel, so cancelling on assignment change
+        # cannot cover this path — the check has to happen here.
+        if context && !Orchestration::Matcher.new(context).assignment_permits?(agent)
+          Rails.logger.info(
+            "[AiAgentJob] Skipping job for agent #{agent.id}: topic " \
+            "#{context.dig('topic', 'id')} is now assigned to another agent " \
+            "(event=#{event_name})"
           )
           return
         end
@@ -78,25 +134,31 @@ module Collavre
           return
         end
 
-        task = Task.create!(
-          name: "Response to #{event_name}",
-          status: "running",
-          trigger_event_name: event_name,
-          trigger_event_payload: context,
-          agent: agent,
-          topic_id: context&.dig("topic", "id"),
-          creative_id: context&.dig("creative", "id")
-        )
-
-        # Record task for loop breaker tracking (per-topic, skip user-initiated)
-        creative_id = context&.dig("creative", "id")
-        if creative_id
-          from_ai = context&.dig("comment", "from_ai") == true
-          topic_id = context&.dig("topic", "id")
-          Orchestration::LoopBreaker.new(context).record_task(
-            creative_id, agent.id, topic_id: topic_id, triggered_by_user: !from_ai
+        # Guard: the same question the orchestrator asks before enqueueing, asked
+        # again where the answer is authoritative. This job can sit in the queue
+        # while the covering turn assembles its payload, so a dispatch that was
+        # not droppable at enqueue time can be droppable by the time it runs —
+        # and the enqueue door alone would leave that window open.
+        #
+        # As at the enqueue door, the drop only happens if the covering turn
+        # records it — otherwise this dispatch has nobody to restore it.
+        covering = Orchestration::DeliveryRecord.covering_task(agent, comment_id, context, event_name)
+        if covering && Orchestration::DeliveryRecord.claim_drop!(covering, comment_id)
+          Rails.logger.info(
+            "[AiAgentJob] Skipping dispatch: comment #{comment_id} was already delivered to " \
+            "agent #{agent.id} by in-flight task #{covering.id} (event=#{event_name})"
           )
+          return
         end
+
+        # Guard: the Scheduler's topic-concurrency check counts Task rows, but
+        # the row for an :immediate decision is only created *here*. A burst of
+        # comments dispatched before the first job runs therefore all see an
+        # empty topic and are all judged :immediate — several turns run at once
+        # in a topic limited to one. Re-check at the moment the row is created,
+        # where the answer is authoritative, and defer into the queue instead.
+        task = admit_or_defer!(agent, event_name, context)
+        return if task.nil?
       end
 
       # Reserve resources before starting work
@@ -138,60 +200,188 @@ module Collavre
           task.reload
         end
 
-        response_content = AiAgentService.new(task).call
+        AiAgentService.new(task).call
 
         # Claude Channel agents delegate via MCP; no immediate response expected
         if is_claude_channel_agent
           # Hold agent capacity until reply / cancel / stuck-recovery releases it.
           should_release = false
-        # Workflow subtasks with empty responses should retry, then fail
-        elsif task.parent_task_id.present? && response_content.blank?
-          max_retries = 2
-          current_retry = task.retry_count || 0
-
-          if current_retry < max_retries
-            task.update!(retry_count: current_retry + 1, status: "pending")
-            Rails.logger.warn(
-              "[AiAgentJob] Workflow subtask #{task.id} returned empty response, " \
-              "retrying (#{current_retry + 1}/#{max_retries})"
-            )
-            AiAgentJob.set(wait: 5.seconds).perform_later(task)
-          else
-            task.update!(status: "failed")
-            Collavre::Comments::WorkflowExecutor.new(task.parent_task).fail_subtask!(
-              task, error_message: "Agent returned empty response after #{max_retries} retries"
-            )
-          end
         else
-          task.update!(status: "done")
-          # Advance workflow (release happens in ensure block)
-          if task.parent_task_id.present?
-            Collavre::Comments::WorkflowExecutor.new(task.parent_task).complete_subtask!(task)
-          end
+          transition_running_task!(task, status: "done")
         end
       rescue ApprovalPendingError
         # Task status already set to pending_approval by AiAgentService
         # Don't release resources yet - task will resume
         should_release = false
         Rails.logger.info("AiAgentJob paused for task #{task.id}: awaiting tool approval")
+      rescue TurnDeadlineError
+        # AgentLifecycleManager already wrote the terminal status inside this
+        # call stack. Restore/settle of dropped dispatches needs nothing extra:
+        # fail_while_worker_settles! marked the row, and the ensure below
+        # settles it.
+        Rails.logger.info("AiAgentJob turn deadline exceeded for task #{task.id}")
       rescue CancelledError
         # Task status already set to "cancelled" by Comment callback
         Rails.logger.info("AiAgentJob cancelled for task #{task.id}: trigger message deleted")
+        # Where a turn stopped mid-answer settles. The cancel was committed in
+        # another process while this worker was inside the provider call, so
+        # Task's status callback declined to decide
+        # (Task#ended_while_worker_settles?) and this is the first moment either
+        # answer exists: AiAgentService's ensure has recorded whether the
+        # payload got there on the way up to here.
+        # Reloaded because the status was written to the row by somebody else.
+        Orchestration::DeliveryRecord.restore_if_undelivered!(task.reload)
       rescue StandardError => e
         task.update!(status: "failed")
-        # Fail workflow if this is a sub-task
-        if task.parent_task_id.present?
-          Collavre::Comments::WorkflowExecutor.new(task.parent_task).fail_subtask!(task, error_message: e.message)
-        end
         Rails.logger.error("AiAgentJob failed for task #{task.id}: #{e.message}")
         raise e
       ensure
         # Guarantee resource release for all paths except pending_approval
         tracker.release!(resource_id, tokens_used: 0) if should_release && tracker && resource_id
-        if task&.trigger_event_payload&.key?("topic") && %w[done failed cancelled escalated].include?(task.reload.status)
-          Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
+        settled_task = task&.reload
+        if settled_task &&
+           Orchestration::DeliveryRecord.worker_settling?(settled_task.trigger_event_payload)
+          # StuckDetector failed this row while this worker was still in the
+          # provider call. The worker is out now, so remove the deferral and ask
+          # the restore question from the handoff evidence AiAgentService wrote.
+          Orchestration::DeliveryRecord.settle_worker!(settled_task)
+          Orchestration::DeliveryRecord.restore_if_undelivered!(settled_task.reload)
+        end
+        if settled_task&.trigger_event_payload&.key?("topic") &&
+           %w[done failed cancelled escalated].include?(settled_task.status)
+          Orchestration::AgentOrchestrator.dequeue_next_for_topic(settled_task.topic_id, settled_task.creative_id)
         end
       end
     end
+
+    private
+
+    # A terminal status can be written by Stop/StuckDetector after the service's
+    # last lifecycle checkpoint but before this job records its outcome. Lock
+    # and re-check the row so normal completion/retry cannot overwrite that
+    # external winner.
+    def transition_running_task!(task, **attributes)
+      task.with_lock do
+        raise CancelledError unless task.status == "running"
+
+        task.update!(attributes)
+      end
+    end
+
+    # Create this dispatch's Task row, either admitted (`running`) or parked as
+    # a `queued` waiter when the topic's concurrency slot is already taken.
+    #
+    # Returns the admitted task, or nil when the dispatch was deferred.
+    def admit_or_defer!(agent, event_name, context)
+      attrs = {
+        name: "Response to #{event_name}",
+        trigger_event_name: event_name,
+        trigger_event_payload: context,
+        agent: agent,
+        topic_id: context&.dig("topic", "id"),
+        creative_id: context&.dig("creative", "id")
+      }
+      unless topic_admission_scoped?(context)
+        return Task.create!(attrs.merge(status: "running")).tap { record_loop_breaker_turn(agent, context) }
+      end
+
+      task, admitted, current_context = nil, false, false
+      # A queued row here is a waiter, and what speaks for it is settled now, with
+      # the row — not later, from whichever notices happen to be visible. Its
+      # notice is posted in a separate transaction below, so between the two this
+      # waiter is queued with nothing naming it, and a shared notice deleted in
+      # that window would read an opted-out waiter as one of its own and cancel a
+      # turn that was only deferred.
+      # Counting occupants and claiming the slot must be ONE step. Two workers
+      # starting within the same millisecond — the exact burst this job defends
+      # against — otherwise both read an occupancy below the limit before either
+      # inserts its `running` row, and the re-check reproduces the very TOCTOU
+      # race it exists to close. Serialize admission on the topic row: every
+      # admission for a topic takes the same lock, so the loser reads the
+      # winner's committed row.
+      Task.transaction do
+        next unless Orchestration::TopicSlot.lock_matches_context?(attrs[:topic_id], attrs[:creative_id])
+
+        current_context = true
+        admitted = Orchestration::TopicSlot.available_for?(agent.id, attrs[:topic_id], attrs[:creative_id], context)
+        task = Task.create!(attrs.merge(
+          status: admitted ? "running" : "queued",
+          # Left nil on an admitted row: it is not waiting, so no notice speaks
+          # for it and there is nothing for a stop control to represent.
+          waiting_notice_scope: admitted ? nil : waiter_notice_scope(agent, context)
+        ))
+      end
+      return unless current_context
+
+      park_deferred_waiter(task, agent, event_name, context, attrs[:topic_id], attrs[:creative_id]) unless admitted
+      # Count where the row is created, before an admitted turn starts and after
+      # a deferred turn is parked. A stale context creates no row and no count.
+      record_loop_breaker_turn(agent, context)
+      task if admitted
+    end
+
+    # Record a created turn for the loop breaker's creative-retry count.
+    # User-initiated messages are not loop material — a person typing twice is
+    # not a runaway — and LoopBreaker skips those itself.
+    def record_loop_breaker_turn(agent, context)
+      creative_id = context&.dig("creative", "id")
+      return unless creative_id
+
+      Orchestration::LoopBreaker.new(context).record_task(
+        creative_id, agent.id,
+        topic_id: context&.dig("topic", "id"),
+        triggered_by_user: context&.dig("comment", "from_ai") != true
+      )
+    end
+
+    # Which notice will speak for a waiter parked by this dispatch: the topic's
+    # shared one when this agent coalesces, its own per-deferral one when it has
+    # opted out. Resolved once, at the moment the waiter is created, so the fold,
+    # the notice and the shared notice's stop button all read one answer.
+    def waiter_notice_scope(agent, context)
+      if Orchestration::PolicyResolver.new(context).coalesce_pending_tasks_for?(agent)
+        Comment::WAITING_NOTICE_TOPIC
+      else
+        Comment::WAITING_NOTICE_TASK
+      end
+    end
+
+    # Is this dispatch subject to the topic concurrency limit at all?
+    # Topic-less dispatches are not.
+    def topic_admission_scoped?(context)
+      context.is_a?(Hash) && context.key?("topic")
+    end
+
+    # Finish parking a waiter created by #admit_or_defer!: fold it together with
+    # any waiters already parked for the same agent/topic/creative, and surface
+    # one "⏳" notice for the topic.
+    def park_deferred_waiter(waiter, agent, event_name, context, topic_id, creative_id)
+      # Read off the waiter rather than resolved again: folding and the notice are
+      # the same policy answer, and asking twice is how they come to disagree
+      # about a wait whose policy changed in between.
+      if waiter.waiting_notice_scope == Comment::WAITING_NOTICE_TOPIC
+        Orchestration::TaskCoalescer.coalesce!(waiter)
+      end
+      Orchestration::AgentOrchestrator.post_topic_concurrency_notice(
+        creative_id, topic_id, context, agent: agent, waiter: waiter
+      )
+
+      Rails.logger.info(
+        "[AiAgentJob] Deferred agent #{agent.id} into topic #{topic_id} queue as task " \
+        "#{waiter.id}: slot already occupied (event=#{event_name})"
+      )
+
+      # A holder may have finished between the admission check and this point,
+      # leaving a waiter with nobody left to drain it (its
+      # dequeue_next_for_topic already ran). Drain unconditionally: this
+      # deferral is not proof the topic is full — with topic_max > 1 an agent
+      # defers because *it* is busy while a slot sits free for someone else, and
+      # gating on "no occupants at all" would strand that waiter until the
+      # unrelated holder finishes. dequeue_next_for_topic re-checks capacity and
+      # eligibility under the admission lock, so an over-eager call is a no-op.
+      Orchestration::AgentOrchestrator.dequeue_next_for_topic(topic_id, creative_id)
+
+      nil
+    end
   end
 end

data/app/jobs/collavre/cancel_offline_delegated_tasks_job.rb

@@ -5,15 +5,15 @@ module Collavre
   # session whose WebSocket dropped without DELETE /api/v1/agent/:id.
   #
   # AgentChannel#unsubscribed makes the agent unroutable, but a task already
-  # in "delegated" still holds its ResourceTracker slot and (for workflow
-  # subtasks) blocks the parent workflow. The dispatch was broadcast to a
-  # now-dead stream, so no client remains to call /reply — without this job
+  # in "delegated" still holds its ResourceTracker slot. The dispatch was
+  # broadcast to a now-dead stream, so no client remains to call /reply —
+  # without this job
   # the slot stays held until StuckDetectorJob times out (minutes to hours).
   #
   # The grace delay lets transient WS blips self-heal: if the client
   # reconnects before the job fires, AgentChannel#subscribe_to_agent_stream
-  # restores routing_expression to "true" and writes a fresh subscription
-  # token. The job's online-state recheck then no-ops.
+  # creates a fresh live presence row and writes a fresh subscription token.
+  # The job's online-state recheck then no-ops.
   class CancelOfflineDelegatedTasksJob < ApplicationJob
     queue_as :default
 
@@ -31,10 +31,6 @@ module Collavre
       # when a sibling remains; mirrors the destroy path's cancel_tasks_for_topic.
       return cancel_dropped_session_tasks(agent, session_id) if session_id.present?
 
-      # Agent came back online during the grace window — the same MCP
-      # session (or a new one) is subscribed and can answer /reply.
-      return if agent.routing_expression.present?
-
       # A session (reconnect or a still-live sibling sharing this agent) holds
       # a LIVE presence row — the agent is online, its delegated work is still
       # owned. Presence is the authority now that one agent fans out to many
@@ -87,21 +83,11 @@ module Collavre
 
       tracker = Orchestration::ResourceTracker.for(agent)
       tasks.find_each do |task|
-        was_running = task.status == "running"
-        task.update!(status: "cancelled")
-        tracker.release!(task.id) if was_running
+        previous_status = task.cancel_if_active!(statuses: %w[queued pending running])
+        next unless previous_status
 
-        next if task.parent_task_id.blank?
-
-        begin
-          Collavre::Comments::WorkflowExecutor.new(task.parent_task).fail_subtask!(
-            task, error_message: "Claude Channel session lost connection before dispatch"
-          )
-        rescue StandardError => e
-          Rails.logger.error(
-            "[CancelOfflineDelegatedTasksJob] fail_subtask! failed for queued task #{task.id}: #{e.message}"
-          )
-        end
+        was_running = previous_status == "running"
+        tracker.release!(task.id) if was_running
       end
     end
 
@@ -110,20 +96,9 @@ module Collavre
 
       tracker = Orchestration::ResourceTracker.for(agent)
       tasks.find_each do |task|
-        task.update!(status: "cancelled")
-        tracker.release!(task.id)
+        next unless task.cancel_if_active!(statuses: %w[delegated])
 
-        if task.parent_task_id.present?
-          begin
-            Collavre::Comments::WorkflowExecutor.new(task.parent_task).fail_subtask!(
-              task, error_message: "Claude Channel session lost connection before reply"
-            )
-          rescue StandardError => e
-            Rails.logger.error(
-              "[CancelOfflineDelegatedTasksJob] fail_subtask! failed for task #{task.id}: #{e.message}"
-            )
-          end
-        end
+        tracker.release!(task.id)
 
         if task.topic_id.present?
           Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)

data/app/jobs/collavre/comment_badges_broadcast_job.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Recomputes and rebroadcasts the per-participant comment badges of a creative.
+  #
+  # The arithmetic is O(comment history) x O(participants): a total count, an
+  # unread count per distinct read watermark, and a private count per user. Run
+  # inline from Comment's after_commit it made writing a message cost more the
+  # longer the conversation was — and an inbox notification wrote a second
+  # comment into an inbox creative, paying the same price again over that
+  # inbox's own history.
+  #
+  # Badges are eventually-consistent UI: the recipient already got the comment
+  # itself over its own Turbo stream, so recounting a beat later is invisible.
+  class CommentBadgesBroadcastJob < ApplicationJob
+    queue_as :default
+    discard_on ActiveJob::DeserializationError
+
+    def perform(creative_id)
+      creative = Creative.find_by(id: creative_id)
+      # Deleting a creative destroys its comments, so the enqueued job can
+      # outlive its subject. Nothing to recount, and nobody to tell.
+      return unless creative
+
+      Comment.broadcast_badges(creative)
+    end
+  end
+end

data/app/jobs/collavre/comment_link_preview_job.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Collavre
+  class CommentLinkPreviewJob < ApplicationJob
+    queue_as :default
+
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3
+    discard_on ActiveRecord::RecordNotFound
+
+    def perform(comment_id, expected_content, expected_revision)
+      comment = Comment.find(comment_id)
+      return unless comment.content == expected_content
+      return unless comment.notification_revision == expected_revision
+
+      formatted_content = CommentLinkFormatter.new(expected_content).format
+      return if formatted_content == expected_content
+
+      Comment.transaction do
+        comment = Comment.lock.find(comment_id)
+        return unless comment.content == expected_content
+        return unless comment.notification_revision == expected_revision
+
+        # This is a derived representation of the same logical comment revision.
+        # Save normally so every Comment after_update_commit integration observes
+        # the formatted content, while suppressing only notification revision
+        # advancement and another preview job.
+        comment.skip_link_preview = true
+        comment.skip_notification_revision = true
+        comment.update!(content: formatted_content)
+      end
+    end
+  end
+end

data/app/jobs/collavre/comment_notification_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Collavre
+  class CommentNotificationJob < ApplicationJob
+    queue_as :default
+
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3
+    discard_on ActiveRecord::RecordNotFound
+
+    def perform(comment_id, kind, event)
+      Comment.find(comment_id).deliver_notifications(kind, event)
+    end
+  end
+end

data/app/jobs/collavre/comment_push_delivery_sweep_job.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Collavre
+  class CommentPushDeliverySweepJob < ApplicationJob
+    queue_as :default
+
+    def perform
+      CommentNotificationDelivery.ready_for_push.find_each do |delivery|
+        delivery.enqueue_push!
+      rescue StandardError => e
+        Rails.logger.error(
+          "[CommentPushDeliverySweepJob] Failed delivery #{delivery.id}: #{e.class}: #{e.message}"
+        )
+      end
+    end
+  end
+end