anima-core 1.3.0 → 1.5.0

data/app/models/session.rb

@@ -7,10 +7,55 @@
 # Sessions form a hierarchy: a main session can spawn child sessions
 # (sub-agents) that inherit the parent's viewport context at fork time.
 class Session < ApplicationRecord
+  include AASM
+
   class MissingSoulError < StandardError; end
 
   VIEW_MODES = %w[basic verbose debug].freeze
 
+  # Non-default AASM options:
+  # - +whiny_transitions: false+ makes invalid transitions return +false+
+  #   instead of raising. {DrainJob} depends on this: +start_processing!+
+  #   returning +false+ signals that the session is busy (+:awaiting+) or
+  #   that the current tool round is still incomplete, so the current
+  #   invocation exits silently.
+  # - +no_direct_assignment: true+ blocks +session.aasm_state = ...+, forcing
+  #   every transition through a named event so guards always run.
+  # - +requires_lock: true+ wraps each transition in a pessimistic row lock
+  #   (+SELECT FOR UPDATE+ on PostgreSQL, +BEGIN IMMEDIATE+ on SQLite) so
+  #   two workers racing +start_processing!+ on a parallel tool-use turn
+  #   can't both succeed — the loser reads the updated +:awaiting+ state
+  #   and bails silently.
+  aasm whiny_transitions: false, no_direct_assignment: true, requires_lock: true do
+    after_all_events :emit_state_change
+    after_all_events :clear_interrupt_flag_if_idle
+    after_all_events :wake_drain_pipeline_if_pending
+
+    state :idle, initial: true
+    state :awaiting
+    state :executing
+
+    # Drain claim. Two transitions, one event:
+    # - From +:idle+, the session is fresh — claim unconditionally.
+    # - From +:executing+, only claim once every +tool_use_id+ from the
+    #   latest assistant turn has a matching tool_response (Message or
+    #   PendingMessage). This collapses "tool round complete" and "drain
+    #   claims" into one atomic, lock-protected transition so the LLM
+    #   never sees a partial round.
+    event :start_processing do
+      transitions from: :idle, to: :awaiting
+      transitions from: :executing, to: :awaiting, guard: :tool_round_complete?
+    end
+
+    event :tool_received do
+      transitions from: :awaiting, to: :executing
+    end
+
+    event :response_complete do
+      transitions from: :awaiting, to: :idle
+    end
+  end
+
   attribute :view_mode, :string, default: -> { Anima::Settings.default_view_mode }
 
   serialize :granted_tools, coder: JSON
@@ -28,212 +73,234 @@ class Session < ApplicationRecord
   validates :name, length: {maximum: 255}, allow_nil: true
 
   after_update_commit :broadcast_name_update, if: :saved_change_to_name?
-  after_update_commit :broadcast_active_skills_update, if: :saved_change_to_active_skills?
-  after_update_commit :broadcast_active_workflow_update, if: :saved_change_to_active_workflow?
 
   scope :recent, ->(limit = 10) { order(updated_at: :desc).limit(limit) }
   scope :root_sessions, -> { where(parent_session_id: nil) }
-  scope :processing_children_of, ->(parent_id) { where(parent_session_id: parent_id, processing: true) }
-
-  # Cycles to the next view mode: basic → verbose → debug → basic.
-  #
-  # @return [String] the next view mode in the cycle
-  def next_view_mode
-    current_index = VIEW_MODES.index(view_mode) || 0
-    VIEW_MODES[(current_index + 1) % VIEW_MODES.size]
-  end
+  # Sessions currently working on behalf of a human — any non-idle AASM state.
+  scope :processing, -> { awaiting.or(executing) }
 
   # @return [Boolean] true if this session is a sub-agent (has a parent)
   def sub_agent?
     parent_session_id.present?
   end
 
-  # Checks whether the Mneme terminal message has left the viewport and
-  # enqueues {MnemeJob} when it has. On the first message of a new session,
-  # initializes the boundary pointer.
+  # Checks whether the Mneme boundary has left the viewport and enqueues
+  # {MnemeJob} when it has. Delegates initial boundary placement to
+  # {#initialize_mneme_boundary!} on the first call.
   #
-  # The terminal message is always a conversation message (user/agent message
-  # or think tool_call), never a bare tool_call/tool_response.
+  # The boundary has "left the viewport" when the cumulative token cost
+  # of everything from the boundary to the newest message exceeds the
+  # budget — a single SUM aggregate, no window function needed.
   #
   # @return [void]
   def schedule_mneme!
     return if sub_agent?
 
-    # Initialize boundary on first conversation message
     if mneme_boundary_message_id.nil?
-      first_conversation = messages
-        .where(message_type: Message::CONVERSATION_TYPES)
-        .order(:id).first
-      first_conversation ||= messages
-        .where(message_type: "tool_call")
-        .detect { |msg| msg.payload["tool_name"] == Message::THINK_TOOL }
-
-      if first_conversation
-        update_column(:mneme_boundary_message_id, first_conversation.id)
-      end
+      initialize_mneme_boundary!
       return
     end
 
-    # Check if boundary message has left the viewport
-    return if viewport_message_ids.include?(mneme_boundary_message_id)
+    tokens_since_boundary = messages
+      .where("messages.id >= ?", mneme_boundary_message_id)
+      .sum(:token_count)
+    return if tokens_since_boundary <= effective_token_budget
 
     MnemeJob.perform_later(id)
   end
 
-  # Enqueues the analytical brain to perform background maintenance on
-  # this session. Currently handles session naming; future phases add
-  # skill activation, goal tracking, and memory.
+  # Places the initial Mneme boundary at the oldest eligible message in
+  # the session — the top of the raw window, from which Mneme will start
+  # compressing downward once that message drifts out of the viewport.
+  # Eligible messages are conversation messages (user/agent/system) and
+  # think tool_calls, considered on equal footing; bare tool_call or
+  # tool_response messages are never eligible.
   #
-  # Runs after the first exchange and periodically as the conversation
-  # evolves, so the name stays relevant to the current topic.
+  # No-op when the session has no eligible messages yet.
   #
   # @return [void]
-  def schedule_analytical_brain!
-    return if sub_agent?
+  def initialize_mneme_boundary!
+    first_id = messages.conversation_or_think.order(:id).pick(:id)
+    update_column(:mneme_boundary_message_id, first_id) if first_id
+  end
+
+  # Token budget appropriate for this session type.
+  # Sub-agents use a smaller budget to stay out of the "dumb zone".
+  # @return [Integer]
+  def effective_token_budget
+    sub_agent? ? Anima::Settings.subagent_token_budget : Anima::Settings.token_budget
+  end
 
-    count = messages.llm_messages.count
-    return if count < 2
-    # Already named — only regenerate at interval boundaries (30, 60, 90, …)
-    return if name.present? && (count % Anima::Settings.name_generation_interval != 0)
+  # Returns the messages currently visible in the LLM context window as a
+  # composable AR relation. Selects own messages above the Mneme boundary
+  # whose cumulative token count (walked newest-first) fits within the
+  # budget. The newest message is always included even when it alone
+  # exceeds the budget. Messages are full-size or excluded entirely.
+  #
+  # The selection runs as a single SQL query using a window function
+  # ({+SUM() OVER+}). Older messages have been compressed into snapshots
+  # and no longer participate in the viewport. Pending messages live in a
+  # separate table ({PendingMessage}) and never appear here — they are
+  # promoted to real messages before the agent processes them.
+  #
+  # @param token_budget [Integer] maximum tokens to include (positive)
+  # @return [ActiveRecord::Relation<Message>] chronologically ordered by id
+  def viewport_messages(token_budget: effective_token_budget)
+    scope = messages
+    scope = scope.where("messages.id >= ?", mneme_boundary_message_id) if mneme_boundary_message_id
+
+    windowed = scope.select(
+      "messages.*",
+      "SUM(token_count) OVER (ORDER BY id DESC) AS running_total"
+    )
 
-    AnalyticalBrainJob.perform_later(id)
+    Message
+      .from(windowed, :messages)
+      .where("running_total <= ? OR running_total = token_count", token_budget)
+      .order(:id)
   end
 
-  # Returns the messages currently visible in the LLM context window.
-  # Walks messages newest-first and includes them until the token budget
-  # is exhausted. Messages are full-size or excluded entirely.
+  # Returns the messages in the Mneme eviction zone — the oldest slice of
+  # the conversation starting from the boundary, filling the eviction budget
+  # walking newest-ward. These are the messages Mneme will summarize into a
+  # snapshot before advancing the boundary past them.
   #
-  # Sub-agent sessions inherit parent context via virtual viewport:
-  # child messages are prioritized and fill the budget first (newest-first),
-  # then parent messages from before the fork point fill the remaining budget.
-  # The final array is chronological: parent messages first, then child messages.
+  # Mirror of {#viewport_messages} but walks oldest-first from the boundary
+  # instead of newest-first from the tail.
   #
-  # Pending messages live in a separate table ({PendingMessage}) and never
-  # appear in this viewport — they are promoted to real messages before
-  # the agent processes them.
+  # @return [ActiveRecord::Relation<Message>] chronologically ordered by id
+  def eviction_zone_messages
+    return Message.none unless mneme_boundary_message_id
+
+    budget = (Anima::Settings.token_budget * Anima::Settings.eviction_fraction).to_i
+
+    scope = messages.where("messages.id >= ?", mneme_boundary_message_id)
+
+    windowed = scope.select(
+      "messages.*",
+      "SUM(token_count) OVER (ORDER BY id ASC) AS running_total"
+    )
+
+    Message
+      .from(windowed, :messages)
+      .where("running_total <= ? OR running_total = token_count", budget)
+      .order(:id)
+  end
+
+  # Names of skills currently present in the viewport as
+  # `from_melete_skill` phantom tool_call messages, in activation order.
   #
-  # @param token_budget [Integer] maximum tokens to include (positive)
-  # @return [Array<Message>] chronologically ordered
-  def viewport_messages(token_budget: Anima::Settings.token_budget)
-    own = select_messages(own_message_scope, budget: token_budget)
-    remaining = token_budget - own.sum { |msg| message_token_cost(msg) }
-
-    if sub_agent? && remaining > 0
-      parent = select_messages(parent_message_scope, budget: remaining)
-      trim_trailing_tool_calls(parent) + own
-    else
-      own
-    end
+  # @return [Array<String>] skill names in the viewport, activation order
+  def skills_in_viewport
+    from_melete_messages
+      .where("json_extract(payload, '$.tool_name') = ?", PendingMessage::MELETE_SKILL_TOOL)
+      .pluck(Arel.sql("json_extract(payload, '$.tool_input.skill')"))
+      .compact
   end
 
-  # Recalculates the viewport and returns IDs of messages evicted since the
-  # last snapshot. Updates the stored viewport_message_ids atomically.
-  # Piggybacks on message broadcasts to notify clients which messages left
-  # the LLM's context window.
+  # Workflow name currently present in the viewport as a
+  # `from_melete_workflow` phantom tool_call message, if any. The most
+  # recent activation wins when multiple are visible.
   #
-  # @return [Array<Integer>] IDs of messages no longer in the viewport
-  def recalculate_viewport!
-    new_ids = viewport_messages.map(&:id)
-    old_ids = viewport_message_ids
+  # @return [String, nil] workflow name in the viewport, or nil
+  def workflow_in_viewport
+    from_melete_messages
+      .where("json_extract(payload, '$.tool_name') = ?", PendingMessage::MELETE_WORKFLOW_TOOL)
+      .reorder(id: :desc)
+      .pick(Arel.sql("json_extract(payload, '$.tool_input.workflow')"))
+  end
 
-    evicted = old_ids - new_ids
-    update_column(:viewport_message_ids, new_ids) if old_ids != new_ids
-    evicted
+  # Active skills — skills Aoide is currently carrying or about to carry.
+  # Union of skills already promoted into the viewport and skills pending
+  # promotion. A skill is "active" from activation until eviction; there
+  # is no deactivation.
+  #
+  # @return [Array<String>] skill names, deduplicated, activation order first
+  def active_skills
+    queued = pending_messages.where(source_type: "skill").order(:id).pluck(:source_name)
+    (skills_in_viewport + queued).uniq
   end
 
-  # Overwrites the viewport snapshot without computing evictions.
-  # Used when transmitting or broadcasting a full viewport refresh,
-  # where eviction notifications are unnecessary (clients clear their
-  # store first).
+  # Active workflow — the workflow Aoide is currently carrying or about
+  # to carry. Pending activations take precedence over viewport contents
+  # (the last enqueue wins; the previous phantom pair evicts naturally).
   #
-  # @param ids [Array<Integer>] message IDs now in the viewport
-  # @return [void]
-  def snapshot_viewport!(ids)
-    update_column(:viewport_message_ids, ids)
+  # @return [String, nil]
+  def active_workflow
+    pending = pending_messages.where(source_type: "workflow").order(id: :desc).pick(:source_name)
+    pending || workflow_in_viewport
   end
 
   # Returns the system prompt for this session.
-  # Sub-agent sessions use their stored prompt plus active skills and
-  # the pinned task. Main sessions assemble a full system prompt from
-  # soul, environment, skills/workflow, and goals.
+  # Sub-agent sessions use their stored prompt plus the pinned task.
+  # Main sessions assemble a full system prompt from soul, sisters, and
+  # snapshots. Skills, workflows, and goals are injected as phantom
+  # tool_use/tool_result pairs in the message stream (not here) to keep
+  # the system prompt stable for prompt caching. Environment awareness
+  # flows through Bash tool responses.
   #
-  # @param environment_context [String, nil] pre-assembled environment block
-  #   from {EnvironmentProbe}; injected between soul and expertise sections
   # @return [String, nil] the system prompt text, or nil when nothing to inject
-  def system_prompt(environment_context: nil)
+  def system_prompt
     if sub_agent?
-      [prompt, assemble_expertise_section, assemble_task_section].compact.join("\n\n")
+      [prompt, assemble_task_section].compact.join("\n\n")
     else
-      assemble_system_prompt(environment_context: environment_context)
+      assemble_system_prompt
     end
   end
 
-  # Activates a skill on this session. Validates the skill exists in the
-  # registry, adds it to active_skills, and persists.
+  # Activates a skill on this session by enqueuing its content as a
+  # {PendingMessage} that promotes to a `from_melete_skill` phantom pair.
+  # Skips re-activation while the previous phantom pair is still in the
+  # viewport — Aoide already has the skill text in front of her.
   #
   # @param skill_name [String] name of the skill to activate
   # @return [Skills::Definition] the activated skill
   # @raise [Skills::InvalidDefinitionError] if skill not found in registry
-  # @raise [ActiveRecord::RecordInvalid] if save fails
   def activate_skill(skill_name)
     definition = Skills::Registry.instance.find(skill_name)
     raise Skills::InvalidDefinitionError, "Unknown skill: #{skill_name}" unless definition
-
     return definition if active_skills.include?(skill_name)
 
-    self.active_skills = active_skills + [skill_name]
-    save!
+    enqueue_recall_message("skill", skill_name, definition.content)
+    Events::Bus.emit(Events::SkillActivated.new(session_id: id, skill_name: skill_name))
     definition
   end
 
-  # Deactivates a skill on this session. Removes it from active_skills and persists.
-  #
-  # @param skill_name [String] name of the skill to deactivate
-  # @return [void]
-  def deactivate_skill(skill_name)
-    return unless active_skills.include?(skill_name)
-
-    self.active_skills = active_skills - [skill_name]
-    save!
-  end
-
-  # Activates a workflow on this session. Validates the workflow exists in the
-  # registry, sets it as the active workflow, and persists. Only one workflow
-  # can be active at a time — activating a new one replaces the previous.
+  # Activates a workflow on this session by enqueuing its content as a
+  # {PendingMessage} that promotes to a `from_melete_workflow` phantom
+  # tool pair. Workflows are main-session only.
+  # Skips re-activation while the previous phantom pair is still in the
+  # viewport.
   #
   # @param workflow_name [String] name of the workflow to activate
   # @return [Workflows::Definition] the activated workflow
   # @raise [Workflows::InvalidDefinitionError] if workflow not found in registry
-  # @raise [ActiveRecord::RecordInvalid] if save fails
   def activate_workflow(workflow_name)
     definition = Workflows::Registry.instance.find(workflow_name)
     raise Workflows::InvalidDefinitionError, "Unknown workflow: #{workflow_name}" unless definition
-
     return definition if active_workflow == workflow_name
 
-    self.active_workflow = workflow_name
-    save!
+    enqueue_recall_message("workflow", workflow_name, definition.content)
+    Events::Bus.emit(Events::WorkflowActivated.new(session_id: id, workflow_name: workflow_name))
     definition
   end
 
-  # Deactivates the current workflow on this session.
-  #
-  # @return [void]
-  def deactivate_workflow
-    return unless active_workflow.present?
-
-    self.active_workflow = nil
-    save!
-  end
-
-  # Assembles the system prompt: version preamble, soul, environment context,
-  # skills/workflow, then goals.
-  # The soul is always present — "who am I" before "what can I do."
+  # Assembles the system prompt: version preamble, soul, sisters block,
+  # available tools menu, tool guidelines, and snapshots. Skills,
+  # workflows, goals, and environment awareness flow through the message
+  # stream and tool responses, keeping the system prompt stable for
+  # prompt caching.
   #
-  # @param environment_context [String, nil] pre-assembled environment block
   # @return [String] composed system prompt
-  def assemble_system_prompt(environment_context: nil)
-    [assemble_version_preamble, assemble_soul_section, environment_context, assemble_expertise_section, assemble_goals_section].compact.join("\n\n")
+  def assemble_system_prompt
+    [
+      assemble_version_preamble,
+      assemble_soul_section,
+      assemble_sisters_section,
+      assemble_available_tools_section,
+      assemble_tool_guidelines_section,
+      assemble_snapshots_section
+    ].compact.join("\n\n")
   end
 
   # Serializes non-evicted goals as a lightweight summary for ActionCable
@@ -248,50 +315,34 @@ class Session < ApplicationRecord
 
   # Builds the message array expected by the Anthropic Messages API.
   # Viewport layout (top to bottom):
-  #   [L2 snapshots] [L1 snapshots] [pinned messages] [recalled memories] [sliding window messages]
+  #   [context prefix: goals + pinned messages] [sliding window messages]
   #
-  # Snapshots appear ONLY after their source messages have evicted from
-  # the sliding window. L1 snapshots drop once covered by an L2 snapshot.
-  # Pinned messages are critical context attached to active Goals — they
-  # survive eviction intact until their Goals complete.
-  # Recalled memories surface relevant older messages (passive recall via goals).
-  # Each layer has a fixed token budget fraction — snapshots, pins, and recall
-  # consume viewport space, reducing the sliding window size.
+  # Snapshots live in the system prompt (stable between Mneme runs).
+  # Goal events and recalled memories flow through the message stream as
+  # phantom tool pairs — they ride the conveyor belt as regular messages.
+  # After eviction, a goal snapshot + pinned messages block is rebuilt
+  # from DB state and prepended as a phantom pair.
   #
   # The sliding window is post-processed by {#ensure_atomic_tool_pairs}
   # which removes orphaned tool messages whose partner was cut off by the
   # token budget.
   #
-  # Sub-agent sessions skip snapshot/pin/recall injection (they inherit parent messages directly).
-  #
   # @param token_budget [Integer] maximum tokens to include (positive)
   # @return [Array<Hash>] Anthropic Messages API format
-  def messages_for_llm(token_budget: Anima::Settings.token_budget)
+  def messages_for_llm(token_budget: effective_token_budget)
     heal_orphaned_tool_calls!
 
     sliding_budget = token_budget
-    snapshot_messages = []
-    pinned_messages = []
-    recall_messages = []
-
-    unless sub_agent?
-      l2_budget = (token_budget * Anima::Settings.mneme_l2_budget_fraction).to_i
-      l1_budget = (token_budget * Anima::Settings.mneme_l1_budget_fraction).to_i
-      pinned_budget = (token_budget * Anima::Settings.mneme_pinned_budget_fraction).to_i
-      recall_budget = (token_budget * Anima::Settings.recall_budget_fraction).to_i
-      sliding_budget = token_budget - l2_budget - l1_budget - pinned_budget - recall_budget
-    end
 
-    window = viewport_messages(token_budget: sliding_budget)
+    pinned_budget = (token_budget * Anima::Settings.mneme_pinned_budget_fraction).to_i
+    sliding_budget -= pinned_budget
 
-    unless sub_agent?
-      first_message_id = window.first&.id
-      snapshot_messages = assemble_snapshot_messages(first_message_id, l2_budget: l2_budget, l1_budget: l1_budget)
-      pinned_messages = assemble_pinned_section_messages(first_message_id, budget: pinned_budget)
-      recall_messages = assemble_recall_messages(budget: recall_budget)
-    end
+    window = viewport_messages(token_budget: sliding_budget).to_a
+    first_message_id = window.first&.id
+
+    prefix = assemble_context_prefix_messages(first_message_id, budget: pinned_budget)
 
-    snapshot_messages + pinned_messages + recall_messages + assemble_messages(ensure_atomic_tool_pairs(window))
+    prefix + assemble_messages(ensure_atomic_tool_pairs(window))
   end
 
   # Detects orphaned tool_call messages (those without a matching tool_response
@@ -335,68 +386,95 @@ class Session < ApplicationRecord
     healed
   end
 
-  # Delivers a user message respecting the session's processing state.
-  #
-  # When idle, persists the message directly and enqueues {AgentRequestJob}
-  # to process it. When mid-turn ({#processing?}), stages the message as
-  # a {PendingMessage} in a separate table — it gets no message ID until
-  # promoted, so it can never interleave with tool_call/tool_response pairs.
-  #
-  # @param content [String] user message text
-  # @param bounce_back [Boolean] when true, passes +message_id+ to the job
-  #   so failed LLM delivery triggers a {Events::BounceBack} (used by
-  #   {SessionChannel#speak} for immediate-display messages)
+  # Enqueues an inbound human-side message (direct user input or a
+  # sub-agent reply) as an active {PendingMessage}. The PM's
+  # +after_create_commit+ emits the appropriate pipeline event when the
+  # session is idle (+StartMelete+ for user input, +StartProcessing+ for
+  # sub-agent deliveries). On a busy session the PM queues silently and
+  # {#wake_drain_pipeline_if_pending} picks it up on the next transition
+  # into +:idle+.
+  #
+  # @param content [String] message text (raw, without attribution)
+  # @param source_type [String] origin type: "user" (default) or "subagent"
+  # @param source_name [String, nil] sub-agent nickname (required when source_type is "subagent")
+  # @param bounce_back [Boolean] when true, a failed first LLM call on the
+  #   promoted message triggers a {Events::BounceBack} so the TUI can
+  #   restore the text to the input field
+  # @return [PendingMessage]
+  def enqueue_user_message(content, source_type: "user", source_name: nil, bounce_back: false)
+    message_type = (source_type == "subagent") ? "subagent" : "user_message"
+    pending_messages.create!(
+      content: content,
+      source_type: source_type,
+      source_name: source_name,
+      message_type: message_type,
+      bounce_back: bounce_back
+    )
+  end
+
+  # Promotes a phantom-pair PendingMessage into a synthetic
+  # tool_call/tool_response Message pair — the LLM sees "a tool I
+  # invoked returned a result" and the pair rides the viewport like
+  # any real tool round. Used by {DrainJob} to flush background
+  # enrichment PMs (recalled memories, activated skills, workflow
+  # triggers, goal events, sub-agent deliveries) into the
+  # conversation.
+  #
+  # Releases a failed drain claim and bounces the promoted user-message
+  # back to the client. Called from {DrainJob} when the LLM call raises
+  # before {Events::LLMResponded} ships. Destroying the exact message the
+  # PM promoted (tracked in {PendingMessage#promoted_message_id}) avoids
+  # the "last user_message" guess, which was racy under parallel drains.
+  #
+  # Idempotent — a nil +promoted_message_id+ skips the destroy and emits
+  # the BounceBack with +message_id: nil+ so the TUI still restores input.
+  #
+  # @param pm [PendingMessage] the user-message PM that failed to round-trip
+  # @param error [Exception] the raised error
   # @return [void]
-  def enqueue_user_message(content, bounce_back: false)
-    if processing?
-      pending_messages.create!(content: content)
-    else
-      msg = create_user_message(content)
-      job_args = bounce_back ? {message_id: msg.id} : {}
-      AgentRequestJob.perform_later(id, **job_args)
-    end
+  def release_with_bounce_back(pm, error)
+    response_complete! if may_response_complete?
+
+    bounced = pm.promoted_message_id && messages.find_by(id: pm.promoted_message_id)
+    bounced&.destroy!
+
+    Events::Bus.emit(Events::BounceBack.new(
+      content: pm.content,
+      error: error.message,
+      session_id: id,
+      message_id: bounced&.id
+    ))
   end
 
-  # Persists a user message directly, bypassing the pending queue.
-  #
-  # Used by {#enqueue_user_message} (idle path), {AgentLoop#run},
-  # and sub-agent spawn tools ({Tools::SpawnSubagent}, {Tools::SpawnSpecialist})
-  # because the global {Events::Subscribers::Persister} skips non-pending user
-  # messages — these callers own the persistence lifecycle.
+  # Persists a user_message Message directly — skipping the PendingMessage
+  # mailbox. Used by {DrainJob} to finalize a promoted user_message PM
+  # and by the sub-agent spawn tools ({Tools::SpawnSubagent},
+  # {Tools::SpawnSpecialist}) to seed the child's conversation with its
+  # assigned task. The global {Events::Subscribers::Persister} skips
+  # +user_message+ events, so these callers own the persistence.
   #
   # @param content [String] user message text
+  # @param source_type [String, nil] origin type (e.g. "skill", "workflow")
+  #   for viewport tracking; omitted for plain user messages
+  # @param source_name [String, nil] origin name (e.g. skill name)
   # @return [Message] the persisted message record
-  def create_user_message(content)
+  def create_user_message(content, source_type: nil, source_name: nil)
     now = now_ns
+    payload = {type: "user_message", content: content, session_id: id, timestamp: now}
+    payload["source_type"] = source_type if source_type
+    payload["source_name"] = source_name if source_name
     messages.create!(
       message_type: "user_message",
-      payload: {type: "user_message", content: content, session_id: id, timestamp: now},
+      payload: payload,
       timestamp: now
     )
   end
 
-  # Promotes all pending messages into the conversation history.
-  # Each {PendingMessage} is atomically deleted and replaced with a real
-  # {Message} — the new message gets the next auto-increment ID,
-  # naturally placing it after any tool_call/tool_response pairs that
-  # were persisted while the message was waiting.
-  #
-  # @return [Integer] number of promoted messages
-  def promote_pending_messages!
-    promoted = 0
-    pending_messages.find_each do |pm|
-      transaction do
-        create_user_message(pm.content)
-        pm.destroy!
-      end
-      promoted += 1
-    end
-    promoted
-  end
-
   # Broadcasts child session list to all clients subscribed to the parent
-  # session. Called when a child session is created or its processing state
-  # changes so the HUD sub-agents section updates in real time.
+  # session. Called when a child session is created or its AASM state
+  # changes so the HUD sub-agents section updates in real time. Evicted
+  # sub-agents (+hud_visible: false+) are filtered out — the panel mirrors
+  # what Aoide currently carries in her viewport.
   #
   # Queries children via FK directly (avoids loading the parent record) and
   # selects only the columns needed for the HUD payload.
@@ -405,44 +483,111 @@ class Session < ApplicationRecord
   def broadcast_children_update_to_parent
     return unless parent_session_id
 
-    children = Session.where(parent_session_id: parent_session_id)
+    children = Session.where(parent_session_id: parent_session_id, hud_visible: true)
       .order(:created_at)
-      .select(:id, :name, :processing)
+      .select(:id, :name, :aasm_state)
     ActionCable.server.broadcast("session_#{parent_session_id}", {
       "action" => "children_updated",
       "session_id" => parent_session_id,
       "children" => children.map { |child|
-        state = child.processing? ? "llm_generating" : "idle"
-        {"id" => child.id, "name" => child.name, "processing" => child.processing?, "session_state" => state}
+        {"id" => child.id, "name" => child.name, "session_state" => child.aasm_state}
       }
     })
   end
 
-  # Broadcasts the session's current processing state to all subscribed
-  # clients. Stateless — no storage, pure broadcast. The TUI uses this to
-  # drive the braille spinner animation and sub-agent HUD icons.
-  #
-  # Payload broadcast to +session_{id}+:
-  #   {"action" => "session_state", "state" => state, "session_id" => id}
-  #   # plus "tool" key when state is "tool_executing"
+  # True when at least one of +child+'s traces (the +spawn_subagent+ tool
+  # pair or any +from_{nickname}+ phantom pair) still lives above the
+  # Mneme boundary in this session's viewport. Used by {Mneme::Runner}
+  # after boundary advancement to decide whether a child should drop out
+  # of the HUD panel.
+  #
+  # Returns +false+ when the given session isn't a direct child, when it
+  # has no +spawn_tool_use_id+ (legacy child), or when the boundary has
+  # passed every trace.
+  #
+  # @param child [Session] a sub-agent session to check
+  # @return [Boolean]
+  def subagent_trace_in_viewport?(child)
+    return false unless child.parent_session_id == id
+
+    boundary_id = mneme_boundary_message_id
+    scope = messages
+    scope = scope.where("messages.id >= ?", boundary_id) if boundary_id
+
+    spawn_uid = child.spawn_tool_use_id
+    nickname = child.name
+    conditions = []
+    bindings = {}
+    if spawn_uid
+      conditions << "messages.tool_use_id = :uid"
+      bindings[:uid] = spawn_uid
+    end
+    if nickname
+      conditions << "json_extract(messages.payload, '$.tool_name') = :tool"
+      bindings[:tool] = "from_#{nickname}"
+    end
+    return false if conditions.empty?
+
+    scope.where(conditions.join(" OR "), **bindings).exists?
+  end
+
+  # AASM guard for the +executing → awaiting+ branch of +start_processing+.
+  # The round is complete when every orphan +tool_call+ Message (one
+  # without a matching +tool_response+ Message) has a corresponding
+  # +tool_response+ PendingMessage waiting to be promoted. Until then the
+  # drain bails so the LLM never sees a half-assembled tool turn.
+  #
+  # @return [Boolean]
+  def tool_round_complete?
+    msg_responses = messages.where(message_type: "tool_response").select(:tool_use_id)
+    pm_responses = pending_messages.where(message_type: "tool_response").select(:tool_use_id)
+    messages.where(message_type: "tool_call")
+      .where.not(tool_use_id: msg_responses)
+      .where.not(tool_use_id: pm_responses)
+      .none?
+  end
+
+  # AASM after_all_events callback — publishes
+  # {Events::SessionStateChanged} so the broadcaster subscriber can keep
+  # the TUI spinner and parent-session HUD in sync with the state machine.
+  # Fires after the state column is updated and persisted, so +aasm_state+
+  # reliably holds the post-transition value.
   #
-  # For sub-agents, also broadcasts +child_state+ to the parent stream:
-  #   {"action" => "child_state", "state" => state, "session_id" => id, "child_id" => id}
+  # @return [void]
+  def emit_state_change
+    Events::Bus.emit(Events::SessionStateChanged.new(session_id: id, state: aasm_state))
+  end
+
+  # AASM after_all_events callback — clears the +interrupt_requested+
+  # flag whenever the session lands in +:idle+. The flag is a
+  # one-shot signal that long-running tools ({Tools::Bash}) poll; once
+  # the round ends (tool aborted, response synthesized, drain wound
+  # down) the signal is spent and must not leak into the next round.
   #
-  # @param state [String] one of "idle", "llm_generating", "tool_executing", "interrupting"
-  # @param tool [String, nil] tool name when state is "tool_executing"
   # @return [void]
-  def broadcast_session_state(state, tool: nil)
-    payload = {"action" => "session_state", "state" => state, "session_id" => id}
-    payload["tool"] = tool if tool
-    ActionCable.server.broadcast("session_#{id}", payload)
+  def clear_interrupt_flag_if_idle
+    return unless idle?
+    return unless interrupt_requested?
 
-    # Notify the parent's stream so the HUD updates child state icons
-    # without requiring a full children_updated query.
-    return unless parent_session_id
+    update_column(:interrupt_requested, false)
+  end
 
-    parent_payload = payload.merge("action" => "child_state", "child_id" => id)
-    ActionCable.server.broadcast("session_#{parent_session_id}", parent_payload)
+  # AASM after_all_events callback — picks the oldest active
+  # PendingMessage and re-runs its pipeline routing whenever the session
+  # lands in +:idle+ with work still queued. Covers the race where a PM
+  # arrives while the session is +:awaiting+ (LLM in flight): its own
+  # +after_create_commit+ saw +may_start_processing?+ return false and
+  # emitted nothing, so without this callback the message would sit
+  # forever once the LLM call completed.
+  #
+  # The +:executing → :awaiting+ path (tool round close) does not need
+  # this callback — the closing tool_response PM is itself the wake.
+  #
+  # @return [void]
+  def wake_drain_pipeline_if_pending
+    return unless idle?
+
+    pending_messages.ordered_for_drain.first&.route_to_event_bus
   end
 
   # Broadcasts the full LLM debug context to debug-mode TUI clients.
@@ -458,6 +603,25 @@ class Session < ApplicationRecord
     ActionCable.server.broadcast("session_#{id}", self.class.system_prompt_payload(system, tools: tools))
   end
 
+  # Broadcasts current active skills and workflow to all subscribers.
+  # "Active" is viewport-derived — the HUD reflects what Aoide actually
+  # has in front of her. Callers invoke this after any operation that
+  # changes viewport composition (phantom pair promotion, Mneme eviction).
+  #
+  # @return [void]
+  def broadcast_active_state!
+    ActionCable.server.broadcast("session_#{id}", {
+      "action" => "active_skills_updated",
+      "session_id" => id,
+      "active_skills" => active_skills
+    })
+    ActionCable.server.broadcast("session_#{id}", {
+      "action" => "active_workflow_updated",
+      "session_id" => id,
+      "active_workflow" => active_workflow
+    })
+  end
+
   # Returns the deterministic tool schemas for this session's type and
   # granted_tools configuration. Standard and spawn tools are static
   # class-level definitions — no ShellSession or registry needed.
@@ -466,22 +630,7 @@ class Session < ApplicationRecord
   #
   # @return [Array<Hash>] tool schema hashes matching Anthropic tools API format
   def tool_schemas
-    tools = if granted_tools
-      granted = granted_tools.filter_map { |name| AgentLoop::STANDARD_TOOLS_BY_NAME[name] }
-      (AgentLoop::ALWAYS_GRANTED_TOOLS + granted).uniq
-    else
-      AgentLoop::STANDARD_TOOLS.dup
-    end
-
-    unless sub_agent?
-      tools.push(Tools::SpawnSubagent, Tools::SpawnSpecialist, Tools::OpenIssue)
-    end
-
-    if sub_agent?
-      tools.push(Tools::MarkGoalCompleted)
-    end
-
-    tools.map(&:schema)
+    resolved_tool_classes.map(&:schema)
   end
 
   # Builds the system prompt payload for debug mode transmission.
@@ -493,9 +642,8 @@ class Session < ApplicationRecord
   # @param tools [Array<Hash>, nil] tool schemas
   # @return [Hash] payload with type, rendered debug content, and token estimate
   def self.system_prompt_payload(prompt, tools: nil)
-    total_bytes = prompt.bytesize
-    total_bytes += tools.to_json.bytesize if tools&.any?
-    tokens = Message.estimate_token_count(total_bytes)
+    tools_json = tools&.any? ? tools.to_json : ""
+    tokens = TokenEstimation.estimate_token_count(prompt.to_s + tools_json)
 
     debug = {role: :system_prompt, content: prompt, tokens: tokens, estimated: true}
     debug[:tools] = tools if tools&.any?
@@ -509,6 +657,42 @@ class Session < ApplicationRecord
 
   private
 
+  # Returns `from_melete_*` tool_call messages currently in the viewport
+  # as a composable AR relation. Used by {#skills_in_viewport} and
+  # {#workflow_in_viewport} to derive active state with additional
+  # `.where` clauses on the tool name suffix.
+  #
+  # @return [ActiveRecord::Relation<Message>] chronologically ordered
+  def from_melete_messages
+    viewport_messages
+      .where(message_type: "tool_call")
+      .where("json_extract(payload, '$.tool_name') GLOB ?", "from_melete_*")
+      .order(:id)
+  end
+
+  # Enqueues a Melete-recalled skill or workflow as a background
+  # {PendingMessage}. {DrainJob} flushes it into the conversation as a
+  # phantom tool_use/tool_result pair on the next drain cycle.
+  #
+  # @param source_type [String] "skill" or "workflow"
+  # @param source_name [String] skill or workflow name
+  # @param content [String] definition content to recall
+  # @return [PendingMessage] the created pending message
+  def enqueue_recall_message(source_type, source_name, content)
+    message_type = case source_type
+    when "skill" then "from_melete_skill"
+    when "workflow" then "from_melete_workflow"
+    else raise ArgumentError, "unknown recall source_type: #{source_type.inspect}"
+    end
+
+    pending_messages.create!(
+      content: content,
+      source_type: source_type,
+      source_name: source_name,
+      message_type: message_type
+    )
+  end
+
   # One-line version preamble so the agent knows its own version.
   # Useful for commits, handoffs, and debugging.
   #
@@ -532,56 +716,64 @@ class Session < ApplicationRecord
     File.read(path).strip
   end
 
-  # Assembles the expertise section of the system prompt from active skills
-  # and the active workflow. Both are injected into the same "Your Expertise"
-  # section — the main agent treats them identically as domain knowledge.
+  # Introduces Melete and Mneme so the agent recognizes their
+  # contributions as delivered-to-her rather than self-invoked. The
+  # `from_` prefix carries the semantics — the section just makes the
+  # convention explicit once.
   #
-  # @return [String, nil] expertise section, or nil when nothing is active
-  def assemble_expertise_section
-    sections = active_skills.filter_map do |skill_name|
-      definition = Skills::Registry.instance.find(skill_name)
-      format_expertise_section(definition, skill_name)
-    end
+  # @return [String] sisters section
+  def assemble_sisters_section
+    <<~SISTERS.strip
+      ## Your Sisters
 
-    if active_workflow.present?
-      definition = Workflows::Registry.instance.find(active_workflow)
-      sections << format_expertise_section(definition, active_workflow) if definition
-    end
+      You don't work alone. Two muses share the conversation with you, and their work arrives as tool responses prefixed `from_`:
+
+      - **Melete**, the muse of practice, prepares the stage before you speak. Her contributions arrive as `from_melete_skill`, `from_melete_workflow`, and `from_melete_goal`.
+      - **Mneme**, the muse of memory, holds what has slipped past your immediate attention. When something from earlier matters again she surfaces it as `from_mneme`.
 
-    return if sections.empty?
+      Sub-agents you spawn arrive the same way, named after whoever sent them — `from_sleuth`, `from_scout`, and so on.
 
-    "## Your Expertise\n\nYou know this deeply. Now's your chance to put it to work.\n\n#{sections.join("\n\n")}"
+      **How delivery works:** Results from sisters and sub-agents appear automatically as tool responses in your conversation — you don't fetch them. There is no tool to call, no way to poll, and no status to check. When a sub-agent finishes, its output shows up on its own. If you're waiting on multiple agents, just wait — they'll arrive. Do other work in the meantime if you can.
+    SISTERS
   end
 
-  # Evicts completed goals that have aged past the configured threshold
-  # of meaningful messages (user + agent turns). Pure arithmetic — no LLM
-  # involvement. Called before prompt assembly so evicted goals are
-  # excluded from the very next context window.
+  # Renders a one-line menu of the session's available tools, populated
+  # from each tool's {Tools::Base.prompt_snippet}. Tools without a snippet
+  # are omitted; the section disappears entirely when no tool contributes.
   #
-  # @return [void]
-  def evict_stale_goals!
-    threshold = Anima::Settings.completed_decay_messages
-    goals.evictable.each do |goal|
-      messages_since = messages.llm_messages.where("created_at > ?", goal.completed_at).count
-      goal.update!(evicted_at: Time.current) if messages_since >= threshold
+  # @return [String, nil] available tools section, or nil when empty
+  def assemble_available_tools_section
+    menu = resolved_tool_classes.filter_map do |tool|
+      snippet = tool.prompt_snippet
+      "- #{tool.tool_name}: #{snippet}" if snippet
     end
+    return if menu.empty?
+
+    "## Available Tools\n\n#{menu.join("\n")}"
   end
 
-  # Assembles the goals section of the system prompt.
-  # Automatically evicts stale completed goals before filtering.
-  # Active root goals render as `###` headings with sub-goal checkboxes.
-  # Completed root goals collapse to a single strikethrough line.
-  # Evicted goals are excluded entirely to free context budget.
+  # Concatenates each available tool's {Tools::Base.prompt_guidelines}
+  # into a single behavioral guidance section. Guidelines steer cross-tool
+  # selection (e.g. prefer edit_file over `sed`) and reinforce non-obvious
+  # behaviour the schema cannot convey at every reasoning token.
   #
-  # @return [String, nil] goals section, or nil when no goals exist
-  def assemble_goals_section
-    evict_stale_goals!
+  # @return [String, nil] tool guidelines section, or nil when empty
+  def assemble_tool_guidelines_section
+    bullets = resolved_tool_classes.flat_map(&:prompt_guidelines).map { |line| "- #{line}" }
+    return if bullets.empty?
 
-    root_goals = goals.root.not_evicted.includes(:sub_goals).order(:created_at)
-    return if root_goals.empty?
+    "## Tool Guidelines\n\n#{bullets.join("\n")}"
+  end
 
-    entries = root_goals.map { |goal| render_goal_markdown(goal) }
-    "Current Goals\n=============\n\n#{entries.join("\n\n")}"
+  # Memoizes the active tool classes for this session by delegating to
+  # {Tools::Registry.tool_classes_for} — the shared resolver used by
+  # {.build}, {#tool_schemas}, and the prompt section assemblers so all
+  # views stay in sync. Safe to memoize: +granted_tools+ and +sub_agent?+
+  # are immutable post-creation.
+  #
+  # @return [Array<Class>] tool classes (no MCP tools — those are dynamic)
+  def resolved_tool_classes
+    @resolved_tool_classes ||= Tools::Registry.tool_classes_for(self)
   end
 
   # Assembles the task section for sub-agent system prompts.
@@ -621,22 +813,6 @@ class Session < ApplicationRecord
     lines.join("\n")
   end
 
-  # Formats a definition (skill or workflow) as a Markdown section for the
-  # expertise prompt. Extracts the first Markdown heading from content for
-  # the section title; falls back to the definition name when content has
-  # no heading.
-  #
-  # @param definition [Skills::Definition, Workflows::Definition, nil] the definition to format
-  # @param fallback_name [String] name to use if content has no heading
-  # @return [String, nil] formatted section, or nil if definition is nil
-  def format_expertise_section(definition, fallback_name)
-    return unless definition
-
-    content = definition.content
-    heading = content.lines.first&.sub(/^#+ /, "")&.strip || fallback_name
-    "### #{heading}\n\n#{content}"
-  end
-
   # Broadcasts a name change to all clients subscribed to this session.
   # Triggered by after_update_commit so clients see name updates in real time.
   #
@@ -649,88 +825,16 @@ class Session < ApplicationRecord
     })
   end
 
-  # Broadcasts active skill changes to all clients subscribed to this session.
-  # Triggered by after_update_commit so the TUI info panel updates reactively.
-  #
-  # @return [void]
-  def broadcast_active_skills_update
-    ActionCable.server.broadcast("session_#{id}", {
-      "action" => "active_skills_updated",
-      "session_id" => id,
-      "active_skills" => active_skills
-    })
-  end
-
-  # Broadcasts active workflow change to all clients subscribed to this session.
-  # Triggered by after_update_commit so the TUI info panel updates reactively.
-  #
-  # @return [void]
-  def broadcast_active_workflow_update
-    ActionCable.server.broadcast("session_#{id}", {
-      "action" => "active_workflow_updated",
-      "session_id" => id,
-      "active_workflow" => active_workflow
-    })
-  end
-
-  # Scopes own messages for viewport assembly.
-  # @return [ActiveRecord::Relation]
-  def own_message_scope
-    messages.context_messages
-  end
-
-  # Scopes parent messages created before this session's fork point.
-  # Excludes spawn tool messages — sub-agents don't need to see sibling
-  # spawn pairs, which cause role confusion (the sub-agent mistakes
-  # itself for the parent when it sees "Specialist @sibling spawned...").
-  # @return [ActiveRecord::Relation]
-  def parent_message_scope
-    parent_session.messages.context_messages
-      .excluding_spawn_messages
-      .where(created_at: ...created_at)
-  end
-
-  # Walks messages newest-first, selecting until the token budget is exhausted.
-  # Always includes at least the newest message even if it exceeds budget.
-  #
-  # @param scope [ActiveRecord::Relation] message scope to select from
-  # @param budget [Integer] maximum tokens to include
-  # @return [Array<Message>] chronologically ordered
-  def select_messages(scope, budget:)
-    selected = []
-    remaining = budget
-
-    scope.reorder(id: :desc).each do |msg|
-      cost = message_token_cost(msg)
-      break if cost > remaining && selected.any?
-
-      selected << msg
-      remaining -= cost
-    end
-
-    selected.reverse
-  end
-
-  # @return [Integer] token cost, using cached count or heuristic estimate
-  def message_token_cost(msg)
-    (msg.token_count > 0) ? msg.token_count : estimate_tokens(msg)
-  end
-
-  # Removes trailing tool_call messages that lack matching tool_response.
-  # Prevents orphaned tool_use blocks at the parent/child viewport boundary
-  # (the spawn_subagent/spawn_specialist tool_call is emitted before the child exists,
-  # but its tool_response comes after — so the cutoff can split them).
-  def trim_trailing_tool_calls(message_list)
-    message_list.pop while message_list.last&.message_type == "tool_call"
-    message_list
-  end
-
   # Ensures every tool_call in the message list has a matching tool_response
   # (and vice versa) by removing unpaired messages. The Anthropic API requires
   # every tool_use block to have a tool_result — a missing partner causes
   # a permanent API error. Token budget cutoffs can split pairs when the
   # boundary falls between a tool_call and its tool_response.
   #
+  # Still necessary even though {#assemble_messages} pairs by +tool_use_id+:
+  # the assembly assumes every tool_call has a matching response in the window.
+  # This guard ensures that assumption holds after viewport truncation.
+  #
   # @param message_list [Array<Message>] chronologically ordered messages
   # @return [Array<Message>] messages with unpaired tool messages removed
   def ensure_atomic_tool_pairs(message_list)
@@ -747,33 +851,33 @@ class Session < ApplicationRecord
     message_list.reject { |m| m.tool_use_id.present? && !complete_ids.include?(m.tool_use_id) }
   end
 
-  # Selects visible snapshots and formats them as Anthropic messages.
-  # Snapshots are visible when their source messages have fully evicted.
-  # L1 snapshots are excluded when covered by an L2 snapshot.
-  #
-  # @param first_message_id [Integer, nil] first message ID in the sliding window
-  # @param l2_budget [Integer] token budget for L2 snapshots
-  # @param l1_budget [Integer] token budget for L1 snapshots
-  # @return [Array<Hash>] Anthropic Messages API format
-  def assemble_snapshot_messages(first_message_id, l2_budget:, l1_budget:)
-    return [] unless first_message_id
-
-    l2_messages = select_snapshots_within_budget(
-      snapshots.for_level(2).source_messages_evicted(first_message_id).chronological,
-      budget: l2_budget
-    ).map { |snapshot| format_snapshot_message(snapshot, label: "long-term memory") }
-
-    l1_messages = select_snapshots_within_budget(
-      snapshots.for_level(1).not_covered_by_l2.source_messages_evicted(first_message_id).chronological,
-      budget: l1_budget
-    ).map { |snapshot| format_snapshot_message(snapshot, label: "recent memory") }
+  # Assembles L1/L2 snapshots as a system prompt section.
+  # Snapshots form a compressed timeline between the system prompt and
+  # the live viewport. The budget walk fills chronologically — when the
+  # budget overflows, the oldest snapshots drop first so the most recent
+  # ones always bridge into the viewport.
+  #
+  # @return [String, nil] formatted snapshot text for the system prompt, or nil
+  def assemble_snapshots_section
+    l2 = select_snapshots_within_budget(
+      snapshots.for_level(2),
+      budget: (Anima::Settings.token_budget * Anima::Settings.mneme_l2_budget_fraction).to_i
+    )
+    l1 = select_snapshots_within_budget(
+      snapshots.for_level(1).not_covered_by_l2,
+      budget: (Anima::Settings.token_budget * Anima::Settings.mneme_l1_budget_fraction).to_i
+    )
 
-    l2_messages + l1_messages
+    sections = []
+    sections << format_snapshots_text(l2, label: "Long-term Memory") if l2.any?
+    sections << format_snapshots_text(l1, label: "Recent Memory") if l1.any?
+    sections.join("\n\n").presence
   end
 
-  # Walks snapshots chronologically, selecting until the token budget is exhausted.
-  # Always includes at least one snapshot even if it exceeds the budget, so the
-  # agent never loses all memory context.
+  # Walks snapshots newest-first (by to_message_id), selecting until the
+  # token budget is exhausted. Always includes the newest snapshot even
+  # if it exceeds the budget. Returns results in chronological order
+  # so they read as a timeline in the system prompt.
   #
   # @param scope [ActiveRecord::Relation] snapshot scope to select from
   # @param budget [Integer] maximum tokens to include
@@ -782,91 +886,111 @@ class Session < ApplicationRecord
     selected = []
     remaining = budget
 
-    scope.each do |snapshot|
-      cost = snapshot.token_cost
+    scope.order(to_message_id: :desc).each do |snapshot|
+      cost = snapshot.token_count
       break if cost > remaining && selected.any?
 
       selected << snapshot
       remaining -= cost
     end
 
-    selected
+    selected.reverse
   end
 
-  # Formats a snapshot as an Anthropic user message with a memory label prefix.
+  # Formats a list of snapshots as a labeled section for the system prompt.
   #
-  # @param snapshot [Snapshot]
-  # @param label [String] human-readable label (e.g. "recent memory", "long-term memory")
-  # @return [Hash] Anthropic message format
-  def format_snapshot_message(snapshot, label:)
-    {role: "user", content: "[#{label}]\n#{snapshot.text}"}
+  # @param snapshots_list [Array<Snapshot>]
+  # @param label [String] section heading
+  # @return [String]
+  def format_snapshots_text(snapshots_list, label:)
+    texts = snapshots_list.map(&:text)
+    "## #{label}\n\n#{texts.join("\n\n")}"
   end
 
-  # Assembles pinned messages as a Goals section message for the viewport.
-  # Only includes pinned messages whose source message has evicted from the
-  # sliding window (same rule as snapshots — no duplication with live messages).
+  # Assembles the context prefix: active goals snapshot + pinned messages.
+  # Only shown after the first eviction — before that, goal events flow
+  # as phantom pairs in the message stream and pinned messages have not
+  # yet evicted.
   #
-  # Deduplication: the first Goal referencing a message shows its truncated
-  # display_text; subsequent Goals show a bare `message N` ID to save tokens.
+  # Returns a phantom tool_call/tool_result pair so the LLM sees a
+  # coherent goals + pins block it "recalled" via a tool invocation.
   #
   # @param first_message_id [Integer, nil] first message ID in the sliding window
-  # @param budget [Integer] token budget for pinned messages
-  # @return [Array<Hash>] Anthropic Messages API format (0 or 1 messages)
-  def assemble_pinned_section_messages(first_message_id, budget:)
+  # @param budget [Integer] token budget for context prefix
+  # @return [Array<Hash>] Anthropic Messages API format (0 or 2 messages)
+  def assemble_context_prefix_messages(first_message_id, budget:)
     return [] unless first_message_id
+    return [] unless messages.where("id < ?", first_message_id).exists?
 
-    pins = pinned_messages
-      .includes(:message, :goals)
-      .where("pinned_messages.message_id < ?", first_message_id)
-      .order("pinned_messages.message_id")
-
-    return [] if pins.empty?
+    root_goals = goals.root.active.includes(:sub_goals).order(:created_at)
+    return [] if root_goals.empty?
 
-    selected = select_pins_within_budget(pins, budget)
-    return [] if selected.empty?
-
-    text = render_pinned_messages_section(selected)
-    [{role: "user", content: "[pinned messages]\n#{text}"}]
+    pins_scope = pinned_messages.where("pinned_messages.message_id < ?", first_message_id)
+    selected_pins = select_pins_within_budget(pins_scope, budget: budget)
+      .includes(:message, :goals)
+    content = render_goal_snapshot_with_pins(root_goals, selected_pins)
+
+    # Uses session ID (not PendingMessage ID) because this snapshot is
+    # rebuilt from DB state on every eviction — it has no stable PM record.
+    uid = "goal_snapshot_#{id}"
+    [
+      {role: "assistant", content: [
+        {type: "tool_use", id: uid, name: PendingMessage::MELETE_GOAL_TOOL, input: {}}
+      ]},
+      {role: "user", content: [
+        {type: "tool_result", tool_use_id: uid, content: content}
+      ]}
+    ]
   end
 
-  # Walks pinned messages chronologically, selecting until the token budget
-  # is exhausted. Always includes at least one pin.
+  # Selects pins within a token budget using a cumulative-sum window
+  # function — mirror of {#eviction_zone_messages} but keyed by
+  # +message_id+. Walks oldest-first and always anchors on the first
+  # pin even if it alone exceeds the budget (via
+  # +running_total = token_count+).
   #
-  # @param pins [Array<PinnedMessage>]
-  # @param budget [Integer]
-  # @return [Array<PinnedMessage>]
-  def select_pins_within_budget(pins, budget)
-    selected = []
-    remaining = budget
-
-    pins.each do |pin|
-      cost = pin.token_cost
-      break if cost > remaining && selected.any?
-
-      selected << pin
-      remaining -= cost
-    end
+  # @param scope [ActiveRecord::Relation] pin scope to select from
+  # @param budget [Integer] maximum tokens to include
+  # @return [ActiveRecord::Relation<PinnedMessage>] chronologically ordered
+  def select_pins_within_budget(scope, budget:)
+    windowed = scope.select(
+      "pinned_messages.*",
+      "SUM(pinned_messages.token_count) OVER (ORDER BY pinned_messages.message_id ASC) AS running_total"
+    )
 
-    selected
+    PinnedMessage
+      .from(windowed, :pinned_messages)
+      .where("running_total <= ? OR running_total = token_count", budget)
+      .order(:message_id)
   end
 
-  # Renders the pinned messages section grouped by Goal.
-  # First Goal referencing a pin shows truncated text; subsequent Goals
-  # show bare `message N` ID to avoid token-expensive repetition.
+  # Renders active goals with their associated pinned messages as a
+  # combined snapshot. Each goal shows its sub-goals and any pinned
+  # messages attached to it.
   #
+  # @param root_goals [Array<Goal>] active root goals with preloaded sub_goals
   # @param pins [Array<PinnedMessage>] selected pins with preloaded goals
-  # @return [String] formatted section text
-  def render_pinned_messages_section(pins)
-    goal_pins = group_pins_by_active_goal(pins)
-
+  # @return [String] formatted goals + pins block
+  def render_goal_snapshot_with_pins(root_goals, pins)
+    pin_groups = group_pins_by_active_goal(pins)
     shown_messages = Set.new
-    goal_pins.map { |goal, pin_list|
-      render_goal_pins(goal, pin_list, shown_messages)
-    }.join("\n\n")
+
+    sections = root_goals.map { |goal|
+      lines = [render_goal_markdown(goal)]
+      goal_pins = pin_groups[goal]
+      if goal_pins
+        lines << ""
+        goal_pins.each { |pin| lines << format_pin_line(pin, shown_messages) }
+      end
+      lines.join("\n")
+    }
+
+    "Current Goals\n=============\n\n#{sections.join("\n\n")}"
   end
 
   # Groups pins by their active Goals so the viewport renders
-  # one headed section per Goal.
+  # one headed section per Goal. Relies on +:goals+ being eager-loaded
+  # on each pin — without it, +active_goal_pin_pairs+ triggers N+1.
   #
   # @param pins [Array<PinnedMessage>] pins with preloaded goals
   # @return [Hash{Goal => Array<PinnedMessage>}]
@@ -884,18 +1008,6 @@ class Session < ApplicationRecord
     pin.goals.select(&:active?).map { |goal| [goal, pin] }
   end
 
-  # Renders one Goal's pinned messages as a headed list.
-  #
-  # @param goal [Goal]
-  # @param pin_list [Array<PinnedMessage>]
-  # @param shown_messages [Set<Integer>] tracks already-rendered message IDs for dedup
-  # @return [String]
-  def render_goal_pins(goal, pin_list, shown_messages)
-    lines = ["📌 #{goal.description} (id: #{goal.id})"]
-    pin_list.each { |pin| lines << format_pin_line(pin, shown_messages) }
-    lines.join("\n")
-  end
-
   # Formats a single pin line with deduplication: first occurrence shows
   # truncated text, subsequent occurrences show bare message ID only.
   #
@@ -905,109 +1017,100 @@ class Session < ApplicationRecord
   def format_pin_line(pin, shown_messages)
     mid = pin.message_id
     if shown_messages.add?(mid)
-      "  message #{mid}: #{pin.display_text}"
+      "  📌 message #{mid}: #{pin.display_text}"
     else
-      "  message #{mid}"
-    end
-  end
-
-  # Assembles recalled memory messages from passive recall results.
-  # Recalled messages are fetched by ID and formatted as compact snippets
-  # with session and message context for drill-down via the remember tool.
-  #
-  # @param budget [Integer] token budget for recall messages
-  # @return [Array<Hash>] Anthropic Messages API format
-  def assemble_recall_messages(budget:)
-    return [] if recalled_message_ids.blank?
-
-    recalled = Message.where(id: recalled_message_ids)
-      .includes(:session)
-      .index_by(&:id)
-
-    snippets = []
-    remaining = budget
-
-    recalled_message_ids.each do |mid|
-      msg = recalled[mid]
-      next unless msg
-
-      text = format_recall_snippet(msg)
-      cost = Message.estimate_token_count(text.bytesize)
-      break if cost > remaining && snippets.any?
-
-      snippets << text
-      remaining -= cost
-    end
-
-    return [] if snippets.empty?
-
-    [{role: "user", content: "[associative recall]\n#{snippets.join("\n\n")}"}]
-  end
-
-  # Formats a recalled message as a compact snippet with enough context
-  # for the agent to decide whether to drill down with the remember tool.
-  #
-  # @param msg [Message] the recalled message
-  # @return [String] formatted snippet
-  def format_recall_snippet(msg)
-    session_label = msg.session.name || "session ##{msg.session_id}"
-    content = extract_message_content(msg).to_s.truncate(Anima::Settings.recall_max_snippet_tokens * Message::BYTES_PER_TOKEN)
-    "message #{msg.id} (#{session_label}): #{content}"
-  end
-
-  # Extracts readable content from a message's payload.
-  #
-  # @param msg [Message]
-  # @return [String]
-  def extract_message_content(msg)
-    data = msg.payload
-    case msg.message_type
-    when "user_message", "agent_message", "system_message"
-      data["content"]
-    when "tool_call"
-      if data["tool_name"] == Message::THINK_TOOL
-        data.dig("tool_input", "thoughts")
-      else
-        "#{data["tool_name"]}(…)"
-      end
-    else
-      data["content"]
+      "  📌 message #{mid}"
     end
   end
 
   # Converts a chronological list of messages into Anthropic wire-format messages.
   # Prepends a compact timestamp to each user message for LLM time awareness.
-  # Groups consecutive tool_call messages into one assistant message and
-  # consecutive tool_response messages into one user message.
   #
-  # @param msgs [Array<Message>]
-  # @return [Array<Hash>]
+  # Tool pairing uses +tool_use_id+ lookup, not message order. When a batch
+  # of consecutive +tool_call+ messages is encountered, all matching
+  # +tool_response+ messages are found by +tool_use_id+ and emitted as a
+  # single user message immediately after the assistant message. This
+  # guarantees correct API structure even when responses are persisted
+  # out of order (e.g. parallel tool execution, interleaved sub-agent
+  # deliveries, or promoted pending messages).
+  #
+  # Assumes +ensure_atomic_tool_pairs+ has already removed any unpaired
+  # tool messages from the window.
+  #
+  # @param msgs [Array<Message>] chronologically ordered (by id), pre-filtered
+  # @return [Array<Hash>] Anthropic API message format
   def assemble_messages(msgs)
-    msgs.each_with_object([]) do |msg, api_messages|
+    response_index = build_tool_response_index(msgs)
+
+    result = []
+    i = 0
+    while i < msgs.length
+      msg = msgs[i]
+
       case msg.message_type
       when "user_message"
-        content = "#{format_message_time(msg.timestamp)}\n#{msg.payload["content"]}"
-        api_messages << {role: "user", content: content}
+        result << {role: "user", content: "#{format_message_time(msg.timestamp)}\n#{msg.payload["content"]}"}
+        i += 1
       when "agent_message"
-        api_messages << {role: "assistant", content: msg.payload["content"].to_s}
+        result << {role: "assistant", content: msg.payload["content"].to_s}
+        i += 1
       when "tool_call"
-        append_grouped_block(api_messages, "assistant", tool_use_block(msg.payload))
+        i = assemble_tool_pair(msgs, i, response_index, result)
       when "tool_response"
-        append_grouped_block(api_messages, "user", tool_result_block(msg.payload))
+        # Already emitted by assemble_tool_pair via tool_use_id lookup.
+        # Any response still here was orphaned by viewport eviction
+        # and should have been stripped by ensure_atomic_tool_pairs.
+        i += 1
       when "system_message"
-        # Wrapped as user role with prefix — Claude API has no system role in conversation history
-        api_messages << {role: "user", content: "[system] #{msg.payload["content"]}"}
+        result << {role: "user", content: "[system] #{msg.payload["content"]}"}
+        i += 1
+      else
+        i += 1
       end
     end
+
+    result
   end
 
-  # Groups consecutive tool blocks into a single message of the given role.
-  def append_grouped_block(api_messages, role, block)
-    prev = api_messages.last
-    if prev&.dig(:role) == role && prev[:content].is_a?(Array)
-      prev[:content] << block
-    else
-      api_messages << {role: role, content: [block]}
+  # Collects a batch of consecutive tool_call messages starting at +start+,
+  # emits one assistant message with all tool_use blocks, then emits one
+  # user message with matching tool_result blocks found by tool_use_id.
+  #
+  # @param msgs [Array<Message>] the full message list
+  # @param start [Integer] index of the first tool_call in the batch
+  # @param response_index [Hash{String => Message}] tool_use_id → tool_response
+  # @param result [Array<Hash>] accumulator for assembled API messages
+  # @return [Integer] index of the first message after the batch
+  def assemble_tool_pair(msgs, start, response_index, result)
+    # Collect consecutive tool_calls (same LLM turn)
+    batch = []
+    i = start
+    while i < msgs.length && msgs[i].message_type == "tool_call"
+      batch << msgs[i]
+      i += 1
+    end
+
+    # Assistant message: all tool_use blocks
+    result << {role: "assistant", content: batch.map { |tc| tool_use_block(tc.payload) }}
+
+    # User message: matching tool_result blocks, paired by tool_use_id
+    tool_results = batch.filter_map do |tc|
+      response = response_index[tc.tool_use_id]
+      next unless response
+      tool_result_block(response.payload)
+    end
+    result << {role: "user", content: tool_results} if tool_results.any?
+
+    i
+  end
+
+  # Builds a hash mapping tool_use_id → tool_response Message for O(1) lookup.
+  #
+  # @param msgs [Array<Message>]
+  # @return [Hash{String => Message}]
+  def build_tool_response_index(msgs)
+    msgs.each_with_object({}) do |msg, idx|
+      idx[msg.tool_use_id] = msg if msg.message_type == "tool_response"
     end
   end
 
@@ -1046,13 +1149,4 @@ class Session < ApplicationRecord
   def now_ns
     Time.current.to_ns
   end
-
-  # Delegates to {Message#estimate_tokens} for messages not yet counted
-  # by the background job.
-  #
-  # @param msg [Message]
-  # @return [Integer] at least 1
-  def estimate_tokens(msg)
-    msg.estimate_tokens
-  end
 end