collavre 0.24.0 → 0.25.0

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

@@ -11,6 +11,22 @@ module Collavre
       CANCEL_CHECK_INTERVAL = 1.0
       # Interval (in seconds) between agent_status heartbeats during streaming
       AGENT_STATUS_HEARTBEAT_INTERVAL = 3.0
+      # Statuses written to the row by another process while this worker is
+      # inside the provider call: user Stop -> cancelled, StuckDetectorJob ->
+      # failed. Both must stop this worker — a row already settled externally
+      # has nobody waiting on this turn, and streaming on holds a worker
+      # thread for the rest of the provider call.
+      TERMINAL_STATUSES = %w[cancelled failed].freeze
+
+      def self.topic_id_for(task:, creative:)
+        task.topic_id ||
+          task.trigger_event_payload&.dig("topic", "id") ||
+          Comment.where(
+            id: task.trigger_event_payload&.dig("comment", "id"),
+            creative_id: creative.id
+          ).pick(:topic_id) ||
+          creative.main_topic.id
+      end
 
       def initialize(task:, agent:, creative:)
         @task = task
@@ -18,6 +34,10 @@ module Collavre
         @creative = creative
         @last_cancel_check_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         @last_heartbeat_at = @last_cancel_check_at
+        # Captured once so a setting changed mid-turn cannot make the deadline
+        # and the message that reports crossing it disagree about what fired.
+        @turn_deadline_seconds = SystemSetting.ai_agent_turn_deadline_seconds
+        @deadline_at = @last_cancel_check_at + @turn_deadline_seconds
       end
 
       # Broadcast agent status change
@@ -30,18 +50,55 @@ module Collavre
           agent_id: @agent.id,
           agent_name: @agent.display_name,
           task_id: @task.id,
+          topic_id: self.class.topic_id_for(task: @task, creative: @creative),
           content: content,
           source_creative_id: @creative.id
         )
       end
 
-      # Check if task was cancelled, raise Collavre::CancelledError if so
-      def check_cancelled!
+      # Check if task reached a terminal status or overran its turn deadline,
+      # raise Collavre::CancelledError / Collavre::TurnDeadlineError if so
+      def check_cancelled!(force: false)
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        return if (now - @last_cancel_check_at) < CANCEL_CHECK_INTERVAL
+        return if !force && (now - @last_cancel_check_at) < CANCEL_CHECK_INTERVAL
 
         @last_cancel_check_at = now
-        raise Collavre::CancelledError if @task.reload.status == "cancelled"
+        raise Collavre::CancelledError if TERMINAL_STATUSES.include?(@task.reload.status)
+
+        return if now < @deadline_at
+
+        # This worker is the only process that knows the turn overran, so it
+        # writes the terminal status itself before leaving through the
+        # cancellation path (which never overwrites a terminal status).
+        #
+        # Written the same way StuckDetector fails a row from outside its
+        # worker: mark_handed_off! has not run yet (it runs later, in
+        # execute_llm_conversation's ensure), so a bare `update!` would let
+        # Task's status callback decide off evidence this attempt has not
+        # written down yet and restore dispatches this turn actually
+        # delivered. fail_while_worker_settles! marks the row so the callback
+        # defers, and AiAgentJob's ensure settles it once the real handoff
+        # evidence exists.
+        deadline_transitioned = Orchestration::DeliveryRecord.fail_while_worker_settles!(@task)
+        # Another process may have moved the row to a terminal status after
+        # the reload above but before the locked transition. Preserve that
+        # winner as an ordinary cancellation; classifying it as our deadline
+        # would make AiAgentJob fail a parent workflow that was just cancelled.
+        raise Collavre::CancelledError unless deadline_transitioned
+
+        Rails.logger.warn(
+          "[AgentLifecycleManager] Task #{@task.id} exceeded turn deadline " \
+          "(#{@turn_deadline_seconds}s); failing"
+        )
+        raise Collavre::TurnDeadlineError.new(@turn_deadline_seconds)
+      end
+
+      # Bound a single silent provider request by the remaining wall-clock
+      # budget. Keep a tiny positive floor for transport APIs that reject zero;
+      # check_cancelled! remains the authority once that request returns.
+      def remaining_deadline_seconds
+        remaining = @deadline_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        [ remaining, 0.001 ].max
       end
 
       # Send heartbeat if interval passed
@@ -54,7 +111,7 @@ module Collavre
       end
 
       # Handle cancellation cleanup
-      def handle_cancelled(reply_comment:, response_content:)
+      def handle_cancelled(reply_comment:, response_content:, action_type: "cancelled", message: "Task cancelled by user")
         if reply_comment
           if response_content.present?
             reply_comment.content_will_change!
@@ -71,7 +128,7 @@ module Collavre
         end
 
         broadcast_status("idle")
-        log_action("cancelled", { message: "Task cancelled by user" })
+        log_action(action_type, { message: message })
       end
 
       private

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

@@ -16,10 +16,10 @@ module Collavre
       def handle(error, summary: nil)
         cleanup_placeholder
 
-        broadcast_idle
-
         update_task(error)
 
+        broadcast_pending_approval
+
         log_action(error)
 
         create_approval_comment(error, summary: summary)
@@ -31,15 +31,23 @@ module Collavre
         @reply_comment&.destroy! if @reply_comment&.content == Comment::STREAMING_PLACEHOLDER_CONTENT
       end
 
-      def broadcast_idle
+      # The agent has stopped producing output, but the task has not finished:
+      # it holds its topic slot until the tool call is approved or rejected, and
+      # TasksController#cancel still accepts it. Broadcasting "idle" here made
+      # the client drop the task and stop polling, so the pending_approval status
+      # this method announces was never observed and Stop disappeared on the one
+      # turn that is waiting on the user. Sent after update_task so a client that
+      # reacts by polling reads the status this payload claims.
+      def broadcast_pending_approval
         return unless @creative
 
         CommentsPresenceChannel.broadcast_agent_status(
           @creative.effective_origin.id,
-          status: "idle",
+          status: "pending_approval",
           agent_id: @agent.id,
           agent_name: @agent.display_name,
           task_id: @task.id,
+          topic_id: @task.topic_id || @task.trigger_event_payload&.dig("topic", "id"),
           source_creative_id: @creative.id
         )
       end

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

@@ -17,10 +17,9 @@ module Collavre
 
       def deliver
         unless @topic_id
-          # Workflow subtasks build context without a topic (see
-          # WorkflowExecutor#build_subtask_context). A Claude Channel agent
-          # cannot service those — raise so AiAgentJob fails the task and the
-          # parent workflow advances via fail_subtask! instead of hanging.
+          # A Claude Channel agent has no place to deliver a dispatch that
+          # carries no topic — raise so AiAgentJob fails the task instead of
+          # broadcasting into nowhere.
           raise UndeliverableError,
                 "Claude Channel delivery requires a topic_id (agent=#{@agent.id})"
         end
@@ -43,7 +42,13 @@ module Collavre
           session_topic: session_topic?,
           comment: {
             id: @context.dig("comment", "id"),
-            content: @context.dig("comment", "content"),
+            # This payload is the agent's ONLY input — the MCP client gets no
+            # chat history — so comments that Orchestration::TaskCoalescer
+            # folded into this turn have to be rendered inline here or they
+            # never reach the agent at all.
+            content: MergedTriggerComments.prepend_to(
+              @context.dig("comment", "content"), @context, agent: @agent
+            ),
             author_id: @context.dig("sender", "id") || @context.dig("comment", "user_id"),
             author_name: @context.dig("sender", "name") || comment&.user&.display_name,
             topic_id: @topic_id,

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

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Collavre
+  module AiAgent
+    # Renders the comments that Orchestration::TaskCoalescer folded into a task.
+    #
+    # When a burst of comments collapses into one turn, the superseded comments
+    # survive only as ids in the payload's "merged_comment_ids". Every delivery
+    # path that carries a trigger has to render them, because none of them can
+    # fall back to chat history:
+    #
+    # - ClaudeChannelAdapter sends *only* comment.content to the MCP client.
+    # - SessionContextResolver#incremental_payload sends *only* the :trigger
+    #   message for session-backed agents.
+    #
+    # Blocks are chronological and labelled with their speaker, matching how
+    # MessageBuilder labels chat history.
+    class MergedTriggerComments
+      Block = Struct.new(:comment, :text, :images, keyword_init: true)
+
+      TRUNCATION_SUFFIX = "…[truncated]"
+
+      def self.for(context, agent:)
+        new(context, agent: agent).blocks
+      end
+
+      # The comments a payload's merged ids still refer to *in this turn*.
+      #
+      # The merged ids were captured when the burst was folded; they are not a
+      # standing claim on those rows. CommentMoveService#perform_move reassigns
+      # creative_id, so a comment moved away while the task waited is no longer
+      # part of the turn — rendering it would hand the agent text and image
+      # attachments from a creative it may have no share on.
+      #
+      # Public because two doors ask the same question and must not diverge:
+      # this class decides what is delivered, and Matcher.permits_assignment?
+      # decides whether a merged @mention still licenses the turn. A mention
+      # excluded from the trigger cannot be the reason the turn is allowed.
+      def self.in_turn(ids, context)
+        context ||= {}
+        relation = Comment.public_only.without_approval_action.where(id: ids)
+        creative_id = context.dig("creative", "id")
+        relation = relation.where(creative_id: creative_id) if creative_id
+        # topic_id nil is a real scope (a creative's Main topic), so key? rather
+        # than presence decides whether the turn is topic-scoped at all.
+        relation = relation.where(topic_id: context.dig("topic", "id")) if context.key?("topic")
+        relation
+      end
+
+      # Prefix `content` with the merged comments, oldest first.
+      def self.prepend_to(content, context, agent:)
+        blocks = self.for(context, agent: agent)
+        return content if blocks.empty?
+
+        (blocks.map(&:text) + [ content.to_s ]).join("\n\n")
+      end
+
+      def initialize(context, agent:)
+        @context = context || {}
+        @agent = agent
+      end
+
+      # Ids of the coalesced comments, with the current anchor excluded — the
+      # anchor is delivered as the trigger itself and must not be duplicated.
+      def comment_ids
+        @comment_ids ||= begin
+          ids = Array(@context[Orchestration::TaskCoalescer::PAYLOAD_KEY])
+                  .compact.map(&:to_i).uniq
+          anchor_id = @context.dig("comment", "id")
+          anchor_id ? ids - [ anchor_id.to_i ] : ids
+        end
+      end
+
+      def blocks
+        return [] if comment_ids.empty?
+
+        # Memoized: MessageBuilder renders these into the trigger and also scans
+        # them for creative references, and one build should not re-query.
+        # Ordered by id, not created_at. A burst is exactly the case where the
+        # rows are written by different processes, and created_at is stamped by
+        # whichever one wrote it — clock skew or a tie can hand the agent
+        # "ignore that" ahead of the instruction it retracts. Ids are the app's
+        # single monotonic causal sequence (CommentsController orders by id for
+        # the same reason).
+        @blocks ||= within_budget(
+          self.class.in_turn(comment_ids, @context)
+            .includes(:user)
+            .order(:id)
+            .map { |c| Block.new(comment: c, text: label(c), images: image_blobs(c)) }
+        )
+      end
+
+      private
+
+      # Coalescing turns a burst into one indivisible message, so an oversized
+      # burst does not degrade — the whole turn fails. MessageBuilder budgets
+      # chat history by the same setting; the trigger these blocks go into had
+      # no budget at all, which is the asymmetry a burst is most likely to hit.
+      #
+      # Shrink, never drop. Dropping the oldest blocks would rest on the history
+      # window carrying them instead, and no delivery path guarantees that:
+      #
+      # - A session-backed agent has no history window at all
+      #   (SessionContextResolver#incremental_payload keeps only :trigger), and
+      #   ClaudeChannelAdapter sends only the comment content.
+      # - Even with history, MessageBuilder#append_chat_history caps it by
+      #   chat_history_limit and by *this same* size budget spread across the
+      #   whole preceding conversation, cutting from its newest end — which is
+      #   exactly where a just-dropped burst comment sits.
+      # - History carries text only. A dropped block's image attachments reach
+      #   the agent through nothing, whatever the budgets say.
+      #
+      # So the trigger is the only channel that can promise a merged comment
+      # arrives, and "which of the user's comments to delete" is not a choice
+      # this class is in a position to make. Every block is kept and truncated to
+      # an equal share instead: an oversized burst then degrades in fidelity
+      # rather than losing whole messages, and the truncation is visible in the
+      # text where a silent drop was not.
+      #
+      # No floor under the share. A budget too small to say much per comment is
+      # still not a reason to delete the other comments outright: keeping them
+      # preserves their order, their speakers and — the part the text budget
+      # never measures — their image attachments, which are delivered as
+      # separate parts and cost nothing here.
+      def within_budget(blocks)
+        budget = size_limit
+        return blocks if budget.nil? || blocks.sum { |b| b.text.length } <= budget
+
+        blocks.map { |b| truncate_block(b, budget / blocks.size) }
+      end
+
+      def truncate_block(block, limit)
+        return block if block.text.length <= limit
+
+        text = if limit > TRUNCATION_SUFFIX.length
+                 block.text[0, limit - TRUNCATION_SUFFIX.length] + TRUNCATION_SUFFIX
+        else
+                 block.text[0, limit]
+        end
+        Block.new(comment: block.comment, text: text, images: block.images)
+      end
+
+      def size_limit
+        @agent.respond_to?(:chat_history_size_limit) ? @agent.chat_history_size_limit : nil
+      end
+
+      def label(comment)
+        text = comment.content.to_s
+        if @agent && comment.user_id == @agent.id
+          # Defensive: an agent's own message should never be coalesced into its
+          # own trigger, but if one is, do not relabel it as a human speaker.
+          "[#{@agent.name}]: #{text}"
+        else
+          text = MentionParser.strip_self_mention(text, @agent.name) if @agent
+          "[#{comment.user&.name || 'unknown'}]: #{text}"
+        end
+      end
+
+      def image_blobs(comment)
+        comment.images.attached? ? comment.images.map(&:blob) : []
+      end
+    end
+  end
+end

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

@@ -106,14 +106,18 @@ module Collavre
       end
 
       def append_referenced_creative_contexts(messages)
-        content = @context.dig("comment", "content")
-        return unless content
+        # Comments coalesced into this turn are delivered with the trigger, so
+        # their links point at creatives the agent is about to be asked about.
+        # Scanning only the surviving anchor would drop the subtree that the
+        # absorbed comment's own dispatch would have supplied.
+        contents = [ @context.dig("comment", "content") ] + merged_trigger.blocks.map(&:text)
+        contents = contents.compact
+        return if contents.empty?
 
         children_level = @agent.creative_children_level
         max_depth = 1 + children_level
 
-        # Extract creative IDs from markdown links like [title](/creatives/123)
-        referenced_ids = content.scan(%r{\[[^\]]*\]\(/creatives/(\d+)\)}).flatten.map(&:to_i).uniq
+        referenced_ids = contents.flat_map { |c| referenced_creative_ids(c) }.uniq
         referenced_ids.reject! { |cid| @injected_creative_ids.include?(cid) }
         creatives_by_id = Creative.where(id: referenced_ids).index_by(&:id)
 
@@ -134,6 +138,44 @@ module Collavre
         end
       end
 
+      # Creative ids linked from markdown like [title](/creatives/123).
+      def referenced_creative_ids(text)
+        text.to_s.scan(%r{\[[^\]]*\]\(/creatives/(\d+)\)}).flatten.map(&:to_i).uniq
+      end
+
+      # Whether a history entry carries its comment whole.
+      #
+      # A history entry is text: this window renders `content` and nothing
+      # else. Two things ride only on the trigger path — the blobs
+      # append_trigger_message attaches, and the subtree
+      # append_referenced_creative_contexts renders for a linked creative,
+      # which scans the anchor and the merged blocks and never this window. A
+      # comment carrying either is *partly* delivered here, and the turn that
+      # swept it up is not a substitute for its own dispatch.
+      #
+      # Decided here rather than at Orchestration::DeliveryRecord, which reads
+      # the :comment_id tag as a delivery claim: this is the only place that
+      # knows what was rendered, and in particular which creatives were
+      # already injected. A link to the topic's own creative — the common case
+      # — withholds nothing, and a rule written anywhere else could not tell
+      # that apart from a link to a subtree the agent never saw.
+      #
+      # Deliberately the same test append_referenced_creative_contexts applies,
+      # @injected_creative_ids and all, so the two answer alike: whatever that
+      # path would have injected for this comment is what this window failed to
+      # supply. It holds only roots, not the descendants a rendered subtree
+      # also covers, so a link to a descendant reads as withheld when its text
+      # was in fact rendered. That asymmetry costs a redundant turn; the
+      # opposite one costs the message.
+      def delivered_whole?(comment)
+        return false if comment.images.attached?
+
+        missing = referenced_creative_ids(comment.content) - @injected_creative_ids.to_a
+        return true if missing.empty?
+
+        !Creative.where(id: missing).exists?
+      end
+
       # Appends chat history messages and returns the count of messages added.
       def append_chat_history(messages)
         creative_id = @context.dig("creative", "id")
@@ -146,16 +188,23 @@ module Collavre
         history_chars = 0
         count = 0
 
-        Comment.public_only.without_approval_action.where(creative_id: creative_id)
-               .where(topic_id: topic_id)
-               .where.not(user_id: nil)
-               .includes(:user)
-               .order(created_at: :desc)
-               .limit(history_limit)
-               .reverse
-               .each do |c|
-          next if c.id == trigger_comment&.id
-
+        scope = Comment.public_only.without_approval_action.where(creative_id: creative_id)
+                       .where(topic_id: topic_id)
+                       .where.not(user_id: nil)
+                       .includes(:user, :images_attachments)
+
+        # Exclude before limiting, not after. The trigger and the comments folded
+        # into it are delivered by append_trigger_message, so leaving them in the
+        # limited window lets a burst eat every history slot — a burst as large as
+        # the limit would leave no conversation at all and mark the turn
+        # first_message. Dropping them first lets older messages backfill.
+        excluded_ids = (merged_comment_ids + [ @context.dig("comment", "id") ]).compact.map(&:to_i)
+        scope = scope.where.not(id: excluded_ids) if excluded_ids.any?
+
+        scope.order(created_at: :desc)
+             .limit(history_limit)
+             .reverse
+             .each do |c|
           role = (c.user_id == @agent.id) ? "model" : "user"
           content = c.content.to_s
 
@@ -168,7 +217,18 @@ module Collavre
           history_chars += content.length
           break if history_chars > history_size_limit
 
-          messages << { role: role, kind: :chat_history, parts: [ { text: content } ] }
+          # Tagged with the comment it came from so Orchestration::DeliveryRecord
+          # can read, off the payload the adapter is actually handed, which
+          # comments this turn delivered. Consumers key into :role and :parts;
+          # the extra key is inert to all of them.
+          #
+          # Only an entry that carries its comment whole wears the tag — the
+          # tag is the delivery claim, and delivered_whole? is what makes it
+          # true. An untagged entry still goes to the agent as context; it just
+          # does not stand in for the comment's own dispatch.
+          entry = { role: role, kind: :chat_history, parts: [ { text: content } ] }
+          entry[:comment_id] = c.id if delivered_whole?(c)
+          messages << entry
           count += 1
         end
 
@@ -176,7 +236,7 @@ module Collavre
       end
 
       def append_trigger_message(messages)
-        payload_text = @context.dig("comment", "content") || @context.to_json
+        payload_text = trigger_payload_text
 
         if review_eligible?
           quoted_body = @original_comment.quoted_comment&.content
@@ -192,8 +252,17 @@ module Collavre
           payload_text = "[#{sender_name}]: #{payload_text}"
         end
 
+        # Comments that were folded into this task by Orchestration::TaskCoalescer
+        # (a burst of messages answered as one turn). They belong *in* the
+        # trigger, not in chat history: a session-backed agent receives only the
+        # :trigger message, so history-only placement would lose them entirely.
+        merged_blocks = merged_trigger.blocks
+        payload_text = (merged_blocks.map(&:text) + [ payload_text ]).join("\n\n") if merged_blocks.any?
+
         trigger_parts = [ { text: payload_text } ]
 
+        merged_blocks.each { |b| b.images.each { |blob| trigger_parts << { image: blob } } }
+
         if @original_comment&.images&.attached?
           @original_comment.images.each do |image|
             trigger_parts << { image: image.blob }
@@ -203,6 +272,24 @@ module Collavre
         messages << { role: "user", kind: :trigger, parts: trigger_parts }
       end
 
+      def trigger_payload_text
+        @context.dig("comment", "content") || @context.except(SystemEvents::Envelope::KEY).to_json
+      end
+
+      def merged_trigger
+        @merged_trigger ||= MergedTriggerComments.new(@context, agent: @agent)
+      end
+
+      # Ids of the coalesced comments this turn actually renders into the
+      # trigger (anchor excluded). Deliberately the rendered blocks rather than
+      # every merged id: MergedTriggerComments drops the oldest of an oversized
+      # burst, and excluding a comment that no longer appears in the trigger
+      # would delete it from the turn outright. Leaving it in the history scope
+      # lets that separately budgeted window carry it instead.
+      def merged_comment_ids
+        merged_trigger.blocks.filter_map { |b| b.comment&.id }
+      end
+
       def trigger_comment
         @trigger_comment ||= begin
           id = @context.dig("comment", "id")

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

@@ -32,9 +32,6 @@ module Collavre
         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})",
@@ -42,8 +39,7 @@ module Collavre
           llm_vendor: "anthropic",
           llm_model: "claude-code",
           created_by_id: @user.id,
-          searchable: false,
-          routing_expression: nil
+          searchable: false
         )
       rescue ActiveRecord::RecordNotUnique
         # A concurrent registration for the same (user, agent_name) won the
@@ -92,9 +88,9 @@ module Collavre
       end
 
       # Returns the agent only when it is the current user's own Claude Channel
-      # agent; nil otherwise (the caller renders :conflict). Routing activation
+      # agent; nil otherwise (the caller renders :conflict). Presence creation
       # stays deferred to AgentChannel#subscribe_to_agent_stream so the agent
-      # becomes matchable only once a WebSocket subscriber exists for
+      # becomes ambiently routable 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.

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

@@ -14,12 +14,15 @@ module Collavre
       #      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'.
+      #      status == 'delegated' under the lock, then update it to 'running'.
       #      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
+      # running is a transient claimed-reply state. It remains active while the
+      # comment transaction commits, so TopicMove cannot slip between claim and
+      # finalize; another /reply cannot claim it because only delegated rows are
+      # eligible. update_all (NOT update!) is required to skip 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
@@ -43,25 +46,38 @@ module Collavre
           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)
+          Task.where(id: locked.id).update_all(status: "running", 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:)
+      def link_reply(task:, comment:)
         comment.update_column(:task_id, task.id)
+      end
 
-        Orchestration::ResourceTracker.for(agent).release!(task.id)
+      # Finalize the claimed row inside TaskReplyService's topic-lock
+      # transaction. Completion effects are registered after commit, when the
+      # linked comment and done status are both visible. This leaves no gap for
+      # cancellation or TopicMove between reply persistence and completion.
+      # The effects release the ResourceTracker slot the
+      # AiAgentJob held under task.id, and drains the topic queue — mirroring AiAgentJob#perform's success path for
+      # non-delegated runs.
+      def finalize(agent:, task:, comment:)
+        completed = Task.where(id: task.id, status: "running")
+                        .update_all(status: "done", updated_at: Time.current)
+        raise ActiveRecord::RecordNotSaved, "claimed reply task was not running" unless completed == 1
 
-        if task.parent_task_id.present?
-          Collavre::Comments::WorkflowExecutor.new(task.parent_task).complete_subtask!(task)
+        task.reload
+        ActiveRecord.after_all_transactions_commit do
+          run_completion_effects(agent, task, comment)
         end
+      end
+
+      private
+
+      def run_completion_effects(agent, task, comment)
+        Orchestration::ResourceTracker.for(agent).release!(task.id)
 
         Orchestration::AgentOrchestrator.dequeue_next_for_topic(task.topic_id, task.creative_id)
 
@@ -79,8 +95,6 @@ module Collavre
         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.