collavre 0.22.0 → 0.24.0

data/app/controllers/collavre/admin/settings_controller.rb

@@ -79,76 +79,16 @@ module Collavre
 
       def update
         SystemSetting.transaction do
-          # Help Link
-          help_link_setting = SystemSetting.find_or_initialize_by(key: "help_menu_link")
-          help_link_setting.value = params[:help_link].to_s.strip
-          help_link_setting.save!
-
-          # MCP Tool Approval
-          mcp_setting = SystemSetting.find_or_initialize_by(key: "mcp_tool_approval_required")
-          mcp_setting.value = params[:mcp_tool_approval] == "1" ? "true" : "false"
-          mcp_setting.save!
-
-          # Creatives Login Required
-          creatives_login_setting = SystemSetting.find_or_initialize_by(key: "creatives_login_required")
-          creatives_login_setting.value = params[:creatives_login_required] == "1" ? "true" : "false"
-          creatives_login_setting.save!
-
-          # Home Page Paths (unauthenticated default + authenticated override)
+          settings_from_params.each do |key, value|
+            SystemSetting.find_or_initialize_by(key: key).update!(value: value)
+          end
+
+          # Home Page Paths (unauthenticated default + authenticated override).
+          # Kept separate because they validate/normalize and may raise.
           save_home_page_path("home_page_path", params[:home_page_path])
           save_home_page_path("home_page_path_authenticated", params[:home_page_path_authenticated])
 
-          # Account Lockout Settings
-          max_attempts = params[:max_login_attempts].to_i
-          max_attempts = SystemSetting::DEFAULT_MAX_LOGIN_ATTEMPTS if max_attempts < 1
-          SystemSetting.find_or_initialize_by(key: "max_login_attempts").tap { |s| s.value = max_attempts.to_s; s.save! }
-
-          lockout_duration = params[:lockout_duration_minutes].to_i
-          lockout_duration = SystemSetting::DEFAULT_LOCKOUT_DURATION_MINUTES if lockout_duration < 1
-          SystemSetting.find_or_initialize_by(key: "lockout_duration_minutes").tap { |s| s.value = lockout_duration.to_s; s.save! }
-
-          # Password Policy Settings
-          password_min_length = [ [ params[:password_min_length].to_i, SystemSetting::DEFAULT_PASSWORD_MIN_LENGTH ].max, 72 ].min
-          SystemSetting.find_or_initialize_by(key: "password_min_length").tap { |s| s.value = password_min_length.to_s; s.save! }
-
-          # Session Timeout Settings
-          session_timeout = [ params[:session_timeout_minutes].to_i, 0 ].max
-          SystemSetting.find_or_initialize_by(key: "session_timeout_minutes").tap { |s| s.value = session_timeout.to_s; s.save! }
-
-          # Rate Limiting - Password Reset
-          pw_reset_limit = params[:password_reset_rate_limit].to_i
-          pw_reset_limit = SystemSetting::DEFAULT_PASSWORD_RESET_RATE_LIMIT if pw_reset_limit < 1
-          SystemSetting.find_or_initialize_by(key: "password_reset_rate_limit").tap { |s| s.value = pw_reset_limit.to_s; s.save! }
-
-          pw_reset_period = params[:password_reset_rate_period_minutes].to_i
-          pw_reset_period = SystemSetting::DEFAULT_PASSWORD_RESET_RATE_PERIOD_MINUTES if pw_reset_period < 1
-          SystemSetting.find_or_initialize_by(key: "password_reset_rate_period_minutes").tap { |s| s.value = pw_reset_period.to_s; s.save! }
-
-          # Rate Limiting - API
-          api_limit = params[:api_rate_limit].to_i
-          api_limit = SystemSetting::DEFAULT_API_RATE_LIMIT if api_limit < 1
-          SystemSetting.find_or_initialize_by(key: "api_rate_limit").tap { |s| s.value = api_limit.to_s; s.save! }
-
-          api_period = params[:api_rate_period_minutes].to_i
-          api_period = SystemSetting::DEFAULT_API_RATE_PERIOD_MINUTES if api_period < 1
-          SystemSetting.find_or_initialize_by(key: "api_rate_period_minutes").tap { |s| s.value = api_period.to_s; s.save! }
-
-          # LLM Settings
-          llm_timeout = params[:llm_request_timeout_seconds].to_i
-          llm_timeout = SystemSetting::DEFAULT_LLM_REQUEST_TIMEOUT_SECONDS if llm_timeout < 30
-          SystemSetting.find_or_initialize_by(key: "llm_request_timeout_seconds").tap { |s| s.value = llm_timeout.to_s; s.save! }
-
-          # Auth Providers
-          auth_providers = Array(params[:auth_providers]).reject(&:blank?)
-          if auth_providers.empty?
-            auth_setting = SystemSetting.new(key: "auth_providers_enabled")
-            auth_setting.errors.add(:base, t("admin.settings.auth_provider_required"))
-            raise ActiveRecord::RecordInvalid, auth_setting
-          end
-
-          all_provider_keys = Rails.application.config.auth_providers.map { |p| p[:key].to_s }
-          disabled_providers = all_provider_keys - auth_providers
-          SystemSetting.find_or_initialize_by(key: "auth_providers_disabled").tap { |s| s.value = disabled_providers.join(","); s.save! }
+          save_auth_providers!
         end
 
         redirect_to collavre.admin_settings_path, notice: t("admin.settings.updated")
@@ -174,6 +114,51 @@ module Collavre
 
       private
 
+      # Maps each SystemSetting key to its normalized string value derived from
+      # the request params. Collapses the previously repetitive per-setting
+      # blocks into a single data-driven loop in #update.
+      def settings_from_params
+        {
+          "help_menu_link" => params[:help_link].to_s.strip,
+          "mcp_tool_approval_required" => boolean_setting(:mcp_tool_approval),
+          "creatives_login_required" => boolean_setting(:creatives_login_required),
+          "max_login_attempts" => int_setting(:max_login_attempts, SystemSetting::DEFAULT_MAX_LOGIN_ATTEMPTS),
+          "lockout_duration_minutes" => int_setting(:lockout_duration_minutes, SystemSetting::DEFAULT_LOCKOUT_DURATION_MINUTES),
+          "password_min_length" => [ [ params[:password_min_length].to_i, SystemSetting::DEFAULT_PASSWORD_MIN_LENGTH ].max, 72 ].min.to_s,
+          "session_timeout_minutes" => [ params[:session_timeout_minutes].to_i, 0 ].max.to_s,
+          "password_reset_rate_limit" => int_setting(:password_reset_rate_limit, SystemSetting::DEFAULT_PASSWORD_RESET_RATE_LIMIT),
+          "password_reset_rate_period_minutes" => int_setting(:password_reset_rate_period_minutes, SystemSetting::DEFAULT_PASSWORD_RESET_RATE_PERIOD_MINUTES),
+          "api_rate_limit" => int_setting(:api_rate_limit, SystemSetting::DEFAULT_API_RATE_LIMIT),
+          "api_rate_period_minutes" => int_setting(:api_rate_period_minutes, SystemSetting::DEFAULT_API_RATE_PERIOD_MINUTES),
+          "llm_request_timeout_seconds" => int_setting(:llm_request_timeout_seconds, SystemSetting::DEFAULT_LLM_REQUEST_TIMEOUT_SECONDS, min: 30)
+        }
+      end
+
+      # Checkbox param ("1" when checked) -> "true"/"false" string value.
+      def boolean_setting(param_key)
+        params[param_key] == "1" ? "true" : "false"
+      end
+
+      # Integer param that falls back to a default when below the minimum floor.
+      def int_setting(param_key, default, min: 1)
+        value = params[param_key].to_i
+        value = default if value < min
+        value.to_s
+      end
+
+      def save_auth_providers!
+        auth_providers = Array(params[:auth_providers]).reject(&:blank?)
+        if auth_providers.empty?
+          auth_setting = SystemSetting.new(key: "auth_providers_enabled")
+          auth_setting.errors.add(:base, t("admin.settings.auth_provider_required"))
+          raise ActiveRecord::RecordInvalid, auth_setting
+        end
+
+        all_provider_keys = Rails.application.config.auth_providers.map { |p| p[:key].to_s }
+        disabled_providers = all_provider_keys - auth_providers
+        SystemSetting.find_or_initialize_by(key: "auth_providers_disabled").update!(value: disabled_providers.join(","))
+      end
+
       def save_home_page_path(key, raw_value)
         input = raw_value.to_s.strip
         setting = SystemSetting.find_or_initialize_by(key: key)

data/app/controllers/collavre/api/v1/agents_controller.rb

@@ -29,14 +29,14 @@ module Collavre
             return
           end
 
-          ai_user = find_or_create_session_agent(agent_name)
+          ai_user = session_provisioner.find_or_create_agent(agent_name)
           unless ai_user
             render json: { error: "Session agent email is already in use by a different account" }, status: :conflict
             return
           end
 
           inbox = Creative.inbox_for(current_user)
-          topic = find_or_create_session_topic(inbox, ai_user, session_id, params[:session_label])
+          topic = session_provisioner.find_or_create_topic(inbox, ai_user, session_id, params[:session_label])
           topic.unarchive! if topic.archived?
           topic.set_primary_agent!(ai_user)
 
@@ -202,7 +202,7 @@ module Collavre
           )
 
           if comment.save
-            finalize_claimed_task(agent, claimed_task, comment) if claimed_task
+            task_claim_service.finalize(agent: agent, task: claimed_task, comment: comment) if claimed_task
             dispatch_a2a(agent, comment)
             render json: { comment_id: comment.id }, status: :created
           else
@@ -463,90 +463,6 @@ module Collavre
           nil
         end
 
-        # 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_claimed_task replays both callbacks after the comment is
-        # persisted via Task#fire_completion_callbacks_after_external_claim.
-        def claim_delegated_task(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_claimed_task(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_delegated_task — 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
-
-        # 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
-
         # When an MCP session unregisters, any tasks still in delegated state
         # are abandoned — the client that would have called /reply is gone.
         # Mirror the cancel path so the agent's slot and each topic's queue
@@ -665,111 +581,24 @@ module Collavre
           ).dispatch
         end
 
-        # Deterministic, collision-free email key for a (current_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-#{current_user.id}-#{slug}-#{digest}@agent.collavre.local"
-        end
-
-        # One ai_user per (current_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 (current_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_session_agent(agent_name)
-          email = session_agent_email(agent_name)
-
-          existing = User.find_by(email: email)
-          return verified_session_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_session_agent.
-          User.create!(
-            email: email,
-            name: "Claude Channel (#{agent_name})",
-            password: SecureRandom.hex(32),
-            llm_vendor: "anthropic",
-            llm_model: "claude-code",
-            created_by_id: current_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_session_agent(User.find_by(email: email))
+        # Provisions the (agent, topic) identities for a Claude Code
+        # registration. Memoized per request; behavior extracted verbatim.
+        def session_provisioner
+          @session_provisioner ||= AiAgent::SessionProvisioner.new(current_user)
         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 this POST returning
-        # and the client's subsequent cable subscribe would broadcast into an
-        # empty stream, stranding delegated tasks until stuck recovery.
-        def verified_session_agent(ai_user)
-          return nil unless ai_user &&
-                            ai_user.created_by_id == current_user.id &&
-                            ai_user.ai_user? &&
-                            ai_user.claude_channel_agent?
-
-          ai_user
+        # Claims and finalizes delegated tasks on /reply. Stateless, so a single
+        # instance is reused for the request.
+        def task_claim_service
+          @task_claim_service ||= AiAgent::TaskClaimService.new
         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_session_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: current_user,
-            primary_agent_id: ai_user.id,
-            session_id: session_id
-          )
-        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
+        # Thin delegator to TaskClaimService#claim. Kept as a controller method
+        # (rather than calling the service inline in #reply) so the concurrency
+        # test that patches AgentsController#claim_delegated_task to inject a race
+        # keeps exercising the same seam.
+        def claim_delegated_task(agent, topic, requested_task_id)
+          task_claim_service.claim(agent: agent, topic: topic, requested_task_id: requested_task_id)
         end
       end
     end

data/app/controllers/collavre/api/v1/base_controller.rb

@@ -4,41 +4,23 @@ module Collavre
   module Api
     module V1
       class BaseController < ActionController::API
+        include Collavre::Api::Authenticatable
+
         before_action :authenticate!
 
+        rescue_from Collavre::ApiError do |e|
+          render json: { error: e.message }, status: e.status
+        end
+
         private
 
         def authenticate!
           token = extract_bearer_token
-          if token.blank?
-            render json: { error: "Missing authentication token" }, status: :unauthorized
-            return
-          end
-
-          access_token = Doorkeeper::AccessToken.by_token(token)
-          unless access_token&.accessible?
-            render json: { error: "Invalid authentication token" }, status: :unauthorized
-            return
-          end
+          raise Collavre::ApiError.new("Missing authentication token", status: :unauthorized) if token.blank?
 
-          user = Collavre::User.find_by(id: access_token.resource_owner_id)
-          unless user
-            render json: { error: "User not found" }, status: :unauthorized
-            return
+          unless find_user_by_bearer_token(token)
+            raise Collavre::ApiError.new("Invalid authentication token", status: :unauthorized)
           end
-
-          Collavre::Current.user = user
-        end
-
-        def extract_bearer_token
-          auth_header = request.headers["Authorization"]
-          return nil unless auth_header&.start_with?("Bearer ")
-
-          auth_header.sub("Bearer ", "")
-        end
-
-        def current_user
-          Collavre::Current.user
         end
       end
     end

data/app/controllers/collavre/api/v1/mobile/agent_events_controller.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Collavre
+  module Api
+    module V1
+      module Mobile
+        # The heart of the loop. GET surfaces pending approvals (+ recent agent
+        # replies) with a stable spoken ref number and a decision-ready summary.
+        # POST :id/respond branches on the referenced event KIND:
+        #   (A) approval/permission comment → the spoken response is a BUTTON
+        #       press (allow|deny) → decide_claude_channel_permission! + relay.
+        #   (B) ordinary agent message → the spoken response is FREE TEXT passed
+        #       verbatim back to the agent as a reply comment (no server parsing).
+        class AgentEventsController < BaseController
+          # Spoken decision verbs. The app no longer addresses approvals by
+          # ordinal, so a reply to an approval event is just an allow/deny verb;
+          # anything else asks for clarification rather than firing a decision.
+          APPROVE = /(승인|허용|적용|approve|allow|confirm|네|좋아|오케이|\bok\b|\byes\b)/i
+          DENY    = /(거절|거부|반려|deny|reject|취소|아니|\bno\b)/i
+
+          def index
+            approvals = pending_approvals
+            notices = system_inbox_messages
+
+            # Every undecided approval is emitted on every poll — the server keeps
+            # no per-client cursor. Re-speaking is prevented on the CLIENT (an
+            # in-memory "already spoken" set), the same at-least-once shape as
+            # notices: a pending approval keeps surfacing until it is decided
+            # (which clears it from pending_approvals) or the app restarts (when a
+            # still-pending approval SHOULD be re-surfaced). The old `since` cursor
+            # filtered here, but a batch high-water-mark could burn past an approval
+            # whose created_at trailed a newer notice, losing it forever.
+            events = approvals.map do |c|
+              {
+                id: c.id, type: "approval_requested",
+                title: title_for_topic(c.topic_id),
+                summary: summarizer.approval_summary(comment: c, label: label_for_topic(c.topic_id)),
+                speak: true, requires_response: true, topic_id: c.topic_id,
+                created_at: c.created_at.iso8601(6)
+              }
+            end
+
+            events += notices.map do |c|
+              # The notice stands in for the origin comment it quotes; the app
+              # lists/reads it against the ORIGIN thread and replies route there.
+              origin_topic_id = c.quoted_comment&.topic_id || c.topic_id
+              {
+                id: c.id, type: "agent_reply",
+                title: title_for_topic(origin_topic_id),
+                summary: speakable(c.content),
+                speak: true, requires_response: c.quoted_comment_id.present?,
+                topic_id: origin_topic_id, created_at: c.created_at.iso8601(6)
+              }
+            end
+
+            render json: events.sort_by { |e| e[:created_at] }
+          end
+
+          def respond
+            comment = Collavre::Comment.find_by(id: params[:id])
+            unless comment && authorized_comment?(comment)
+              return render json: { error: "Event not found" }, status: :not_found
+            end
+
+            # Acting on a notice means the user has heard it — clear it from the
+            # unread inbox set so it isn't read again on the next poll.
+            mark_inbox_read(comment)
+
+            if comment.claude_channel_permission?
+              decide_on(comment)
+            else
+              relay_free_text(comment)
+            end
+          end
+
+          # The app calls this when it finishes reading a message ALOUD (whether or
+          # not the user then replies). Reading = hearing it, so the inbox read
+          # pointer advances and the notice stops surfacing — the SAME read-state
+          # the inbox badge uses. A crash before this call leaves the notice unread,
+          # so the next poll re-reads it (at-least-once, not the lossy old cursor).
+          def read
+            comment = Collavre::Comment.find_by(id: params[:id])
+            unless comment && authorized_comment?(comment)
+              return render json: { error: "Event not found" }, status: :not_found
+            end
+
+            mark_inbox_read(comment)
+            head :ok
+          end
+
+          private
+
+          # The user's Inbox → System topic is the per-user alarm stream: mentions,
+          # agent replies, share notices, … land here as system-authored
+          # (user_id: nil) comments that QUOTE the origin comment. This is the
+          # canonical, agent-ownership-independent feed the voice loop reads aloud.
+          #
+          # Emission is gated by the inbox's OWN read-state — the CommentReadPointer
+          # (comments with id > last_read_comment_id are unread) that also drives the
+          # inbox badge — NOT by the client's `since` cursor. A `since` cursor is a
+          # fetch-time high-water-mark: any notice fetched-but-never-spoken (crash,
+          # background, busy queue, restart) gets burned past and is lost forever,
+          # even though it stays unread in the inbox. Driving off the read pointer
+          # makes "unread in the inbox" and "read aloud by the app" the same set; the
+          # app marks a notice read (POST :id/read) only after actually speaking it.
+          def system_inbox_messages
+            inbox = current_user_inbox or return []
+            last_read = inbox_read_pointer&.last_read_comment_id || 0
+
+            scope = Collavre::Comment.where(creative_id: inbox.id, topic_id: inbox.system_topic.id)
+                                     .where("comments.id > ?", last_read)
+                                     .order(:id)
+                                     .limit(50)
+            # Approval prompts are surfaced (actionably) by pending_approvals; their
+            # System-topic FYI duplicate must not be read a second time.
+            scope.reject { |c| c.quoted_comment&.claude_channel_permission? }
+          end
+
+          def inbox_read_pointer
+            inbox = current_user_inbox or return nil
+
+            Collavre::CommentReadPointer.find_by(user: current_user, creative: inbox)
+          end
+
+          # Advance the inbox read pointer to (at least) this notice — forward-only,
+          # so a later message is never un-read. Only inbox-creative comments move the
+          # inbox pointer; calling this for an approval (which lives in the origin
+          # creative and is owned by pending_approvals) is a harmless no-op.
+          def mark_inbox_read(comment)
+            inbox = current_user_inbox or return
+            return unless comment.creative_id == inbox.id
+
+            pointer = Collavre::CommentReadPointer.find_or_initialize_by(user: current_user, creative: inbox)
+            new_id = [ pointer.last_read_comment_id || 0, comment.id ].max
+            pointer.update(last_read_comment_id: new_id)
+          end
+
+          def current_user_inbox
+            return @current_user_inbox if defined?(@current_user_inbox)
+
+            @current_user_inbox = Collavre::Creative.inbox_for(current_user)
+          end
+
+          # Read the whole message aloud, but spoken: strip markdown link syntax to
+          # its text and collapse whitespace so TTS doesn't read raw URLs.
+          def speakable(text)
+            text.to_s.gsub(/\[([^\]]+)\]\([^)]*\)/, '\1').gsub(/\s+/, " ").strip
+          end
+
+          def authorized_comment?(comment)
+            return true if comment.approver_id == current_user.id
+            return true if own_inbox_notice?(comment)
+
+            author = comment.user
+            author.respond_to?(:created_by_id) && agent_ids.include?(author.id)
+          end
+
+          # A system-authored notice in the caller's own Inbox#System topic. Owning
+          # the inbox is the authorization proof (the notice has no approver/author).
+          def own_inbox_notice?(comment)
+            inbox = current_user_inbox or return false
+
+            comment.user_id.nil? &&
+              comment.creative_id == inbox.id &&
+              comment.topic_id == inbox.system_topic.id
+          end
+
+          # (A) bounded decision: spoken response IS the approve/deny button.
+          def decide_on(comment)
+            behavior = behavior_from(params[:response])
+
+            unless %w[allow deny].include?(behavior)
+              return render_speak(:clarify_decision, action: { type: "needs_clarification", comment_id: comment.id })
+            end
+
+            case decide_permission(comment, behavior)
+            when :unauthorized
+              render_speak(:not_authorized, action: { type: "not_authorized", comment_id: comment.id }, status: :forbidden)
+            when :already_decided
+              render_speak(:already_decided, action: { type: "already_decided", comment_id: comment.id })
+            else
+              render_speak(
+                behavior == "allow" ? :approved : :denied,
+                action: { type: behavior == "allow" ? "approved" : "denied", comment_id: comment.id }
+              )
+            end
+          end
+
+          # (B) free-form: relay the utterance verbatim as a human reply.
+          def relay_free_text(comment)
+            text = params[:response].to_s.strip
+            return render_speak(:empty_response, action: { type: "noop" }) if text.blank?
+
+            # A System-inbox notice is a stand-in for the origin comment it quotes;
+            # the reply must land on that origin thread (the System topic itself
+            # never dispatches AI), not on the notice.
+            target = comment.quoted_comment || comment
+            topic = target.topic
+            creative = topic&.creative&.effective_origin || target.creative
+            # quoted_comment threads the reply to the message being answered, but
+            # review_type: :question keeps review_message? false — otherwise the
+            # agent's response would update the quoted comment IN PLACE (review flow)
+            # instead of posting a new reply, so no new comment is created and the
+            # Inbox#System alarm never fires. Same guard as InboxReplyService (#1301).
+            reply = creative.comments.create!(
+              content: text, user: current_user, topic: topic,
+              quoted_comment: target, review_type: :question
+            )
+
+            render_speak(:relayed, action: { type: "relayed", comment_id: reply.id, topic_id: topic&.id })
+          end
+
+          def behavior_from(response)
+            text = response.to_s.strip
+            return "allow" if text.match?(APPROVE)
+            return "deny"  if text.match?(DENY)
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end