anima-core 1.2.0 → 1.4.0

data/app/models/session.rb

@@ -16,6 +16,7 @@ class Session < ApplicationRecord
   serialize :granted_tools, coder: JSON
 
   has_many :messages, -> { order(:id) }, dependent: :destroy
+  has_many :pending_messages, dependent: :destroy
   has_many :goals, dependent: :destroy
   has_many :snapshots, dependent: :destroy
   has_many :pinned_messages, through: :messages
@@ -32,6 +33,7 @@ class Session < ApplicationRecord
 
   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.
   #
@@ -59,10 +61,10 @@ class Session < ApplicationRecord
 
     # Initialize boundary on first conversation message
     if mneme_boundary_message_id.nil?
-      first_conversation = messages.deliverable
+      first_conversation = messages
         .where(message_type: Message::CONVERSATION_TYPES)
         .order(:id).first
-      first_conversation ||= messages.deliverable
+      first_conversation ||= messages
         .where(message_type: "tool_call")
         .detect { |msg| msg.payload["tool_name"] == Message::THINK_TOOL }
 
@@ -97,29 +99,25 @@ class Session < ApplicationRecord
     AnalyticalBrainJob.perform_later(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
+
   # 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.
   #
-  # 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.
+  # 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.
   #
   # @param token_budget [Integer] maximum tokens to include (positive)
-  # @param include_pending [Boolean] whether to include pending messages (true for
-  #   display, false for LLM context assembly)
   # @return [Array<Message>] chronologically ordered
-  def viewport_messages(token_budget: Anima::Settings.token_budget, include_pending: true)
-    own = select_messages(own_message_scope(include_pending), budget: token_budget)
-    remaining = token_budget - own.sum { |msg| message_token_cost(msg) }
-
-    if sub_agent? && remaining > 0
-      parent = select_messages(parent_message_scope(include_pending), budget: remaining)
-      trim_trailing_tool_calls(parent) + own
-    else
-      own
-    end
+  def viewport_messages(token_budget: effective_token_budget)
+    select_messages(own_message_scope, budget: token_budget)
   end
 
   # Recalculates the viewport and returns IDs of messages evicted since the
@@ -148,19 +146,47 @@ class Session < ApplicationRecord
     update_column(:viewport_message_ids, ids)
   end
 
+  # Returns skill names whose recalled content is currently visible in the
+  # viewport. Used by the analytical brain for deduplication — skills already
+  # in the viewport are excluded from the activation catalog.
+  #
+  # @return [Set<String>] skill names present in the viewport
+  def skills_in_viewport
+    recalled_sources_in_viewport("skill")
+  end
+
+  # Returns the workflow name currently visible in the viewport, if any.
+  # Only one workflow can be active at a time, so we return the first match.
+  #
+  # @return [String, nil] workflow name present in the viewport
+  def workflow_in_viewport
+    recalled_sources_in_viewport("workflow").first
+  end
+
   # Returns the system prompt for this session.
-  # Sub-agent sessions use their stored prompt. Main sessions assemble
-  # a system prompt from active skills and current goals.
+  # Sub-agent sessions use their stored prompt plus active skills and
+  # the pinned task. Main sessions assemble a full system prompt from
+  # soul 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.
+  #
+  # Sub-agent sessions still include expertise inline — they're short-lived
+  # and don't benefit from prompt caching.
   #
-  # @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)
-    sub_agent? ? prompt : assemble_system_prompt(environment_context: environment_context)
+  def system_prompt
+    if sub_agent?
+      [prompt, assemble_expertise_section, assemble_task_section].compact.join("\n\n")
+    else
+      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.
+  # registry, updates active_skills, and enqueues the skill content as a
+  # {PendingMessage} so it enters the conversation as a phantom
+  # tool_use/tool_result pair through the normal promotion flow.
   #
   # @param skill_name [String] name of the skill to activate
   # @return [Skills::Definition] the activated skill
@@ -174,10 +200,12 @@ class Session < ApplicationRecord
 
     self.active_skills = active_skills + [skill_name]
     save!
+    enqueue_recall_message("skill", skill_name, definition.content)
     definition
   end
 
   # Deactivates a skill on this session. Removes it from active_skills and persists.
+  # The skill's recalled message stays in the conversation and evicts naturally.
   #
   # @param skill_name [String] name of the skill to deactivate
   # @return [void]
@@ -189,8 +217,9 @@ class Session < ApplicationRecord
   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.
+  # registry, sets it as the active workflow, and enqueues the workflow content
+  # as a {PendingMessage}. Only one workflow can be active at a time —
+  # activating a new one replaces the previous.
   #
   # @param workflow_name [String] name of the workflow to activate
   # @return [Workflows::Definition] the activated workflow
@@ -204,10 +233,12 @@ class Session < ApplicationRecord
 
     self.active_workflow = workflow_name
     save!
+    enqueue_recall_message("workflow", workflow_name, definition.content)
     definition
   end
 
   # Deactivates the current workflow on this session.
+  # The workflow's recalled message stays in the conversation and evicts naturally.
   #
   # @return [void]
   def deactivate_workflow
@@ -217,67 +248,57 @@ class Session < ApplicationRecord
     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, 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_snapshots_section]
+      .compact.join("\n\n")
   end
 
-  # Serializes active goals as a lightweight summary for ActionCable
+  # Serializes non-evicted goals as a lightweight summary for ActionCable
   # broadcasts and TUI display. Returns a nested structure: root goals
-  # with their sub-goals inlined.
+  # with their sub-goals inlined. Evicted goals and their sub-goals are
+  # excluded.
   #
   # @return [Array<Hash>] each with :id, :description, :status, and :sub_goals
   def goals_summary
-    goals.root.includes(:sub_goals).order(:created_at).map(&:as_summary)
+    goals.root.not_evicted.includes(:sub_goals).order(:created_at).map(&:as_summary)
   end
 
   # 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.
   #
-  # Sub-agent sessions skip snapshot/pin/recall injection (they inherit parent messages directly).
+  # 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.
   #
   # @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
+    pinned_budget = (token_budget * Anima::Settings.mneme_pinned_budget_fraction).to_i
+    sliding_budget -= pinned_budget
 
-    window = viewport_messages(token_budget: sliding_budget, include_pending: false)
+    window = viewport_messages(token_budget: sliding_budget)
+    first_message_id = window.first&.id
 
-    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
+    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
@@ -293,7 +314,7 @@ class Session < ApplicationRecord
   #
   # @return [Integer] number of synthetic responses created
   def heal_orphaned_tool_calls!
-    now_ns = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+    current_ns = now_ns
     responded_ids = messages.where(message_type: "tool_response").select(:tool_use_id)
     unresponded = messages.where(message_type: "tool_call")
       .where.not(tool_use_id: responded_ids)
@@ -302,7 +323,7 @@ class Session < ApplicationRecord
     unresponded.find_each do |orphan|
       timeout = orphan.payload["timeout"] || Anima::Settings.tool_timeout
       deadline_ns = orphan.timestamp + (timeout * 1_000_000_000)
-      next if now_ns < deadline_ns
+      next if current_ns < deadline_ns
 
       messages.create!(
         message_type: "tool_response",
@@ -314,7 +335,7 @@ class Session < ApplicationRecord
           "success" => false
         },
         tool_use_id: orphan.tool_use_id,
-        timestamp: now_ns
+        timestamp: current_ns
       )
       healed += 1
     end
@@ -324,59 +345,119 @@ class Session < ApplicationRecord
   # 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?}), emits a pending
-  # {Events::UserMessage} via {Events::Bus} so it queues until the
-  # current agent loop completes — preventing interleaving between
-  # tool_use/tool_result pairs.
+  # 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 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, passes +message_id+ to the job
   #   so failed LLM delivery triggers a {Events::BounceBack} (used by
   #   {SessionChannel#speak} for immediate-display messages)
   # @return [void]
-  def enqueue_user_message(content, bounce_back: false)
+  def enqueue_user_message(content, source_type: "user", source_name: nil, bounce_back: false)
     if processing?
-      Events::Bus.emit(Events::UserMessage.new(
-        content: content, session_id: id,
-        status: Message::PENDING_STATUS
-      ))
+      pending_messages.create!(content: content, source_type: source_type, source_name: source_name)
     else
-      msg = create_user_message(content)
+      display = if source_type == "subagent"
+        format(Tools::ResponseTruncator::ATTRIBUTION_FORMAT, source_name, content)
+      else
+        content
+      end
+      msg = create_user_message(display)
       job_args = bounce_back ? {message_id: msg.id} : {}
       AgentRequestJob.perform_later(id, **job_args)
     end
   end
 
+  # Promotes a phantom pair pending message into a tool_call/tool_response pair.
+  # These persist as real Message records and ride the conveyor belt.
+  #
+  # @param pm [PendingMessage] phantom pair pending message
+  # @return [void]
+  def promote_phantom_pair!(pm)
+    tool_name = pm.phantom_tool_name
+    tool_input = pm.phantom_tool_input
+    uid = "#{tool_name}_#{pm.id}"
+    now = now_ns
+
+    messages.create!(
+      message_type: "tool_call",
+      tool_use_id: uid,
+      payload: {"tool_name" => tool_name, "tool_use_id" => uid,
+                "tool_input" => tool_input.stringify_keys,
+                "content" => pm.display_content.lines.first.chomp},
+      timestamp: now,
+      token_count: Mneme::PassiveRecall::TOOL_PAIR_OVERHEAD_TOKENS
+    )
+
+    messages.create!(
+      message_type: "tool_response",
+      tool_use_id: uid,
+      payload: {"tool_name" => tool_name, "tool_use_id" => uid,
+                "content" => pm.content, "success" => true},
+      timestamp: now,
+      token_count: Message.estimate_token_count(pm.content.bytesize)
+    )
+  end
+
   # Persists a user message directly, bypassing the pending queue.
   #
-  # Used by {#enqueue_user_message} (idle path), {AgentLoop#process},
+  # 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.
   #
   # @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)
-    now = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+  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 user messages to delivered status so they
-  # appear in the next LLM context. Triggers broadcast_update for
-  # each message so connected clients refresh the pending indicator.
+  # 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.
+  #
+  # Returns a hash with two keys:
+  # - +:texts+ — plain content strings for user messages (injected as text blocks
+  #   within the current tool_results turn)
+  # - +:pairs+ — synthetic tool_use/tool_result message hashes for phantom pair
+  #   types (appended as new conversation turns)
   #
-  # @return [Integer] number of promoted messages
+  # @return [Hash{Symbol => Array}] promoted messages split by injection strategy
   def promote_pending_messages!
-    promoted = 0
-    messages.where(message_type: "user_message", status: Message::PENDING_STATUS).find_each do |msg|
-      msg.update!(status: nil, payload: msg.payload.except("status"))
-      promoted += 1
+    texts = []
+    pairs = []
+    pending_messages.find_each do |pm|
+      transaction do
+        if pm.phantom_pair?
+          promote_phantom_pair!(pm)
+        else
+          create_user_message(pm.display_content, source_type: pm.source_type, source_name: pm.source_name)
+        end
+        pm.destroy!
+      end
+      if pm.phantom_pair?
+        pairs.concat(pm.to_llm_messages)
+      else
+        texts << pm.content
+      end
     end
-    promoted
+    {texts: texts, pairs: pairs}
   end
 
   # Broadcasts child session list to all clients subscribed to the parent
@@ -396,12 +477,133 @@ class Session < ApplicationRecord
     ActionCable.server.broadcast("session_#{parent_session_id}", {
       "action" => "children_updated",
       "session_id" => parent_session_id,
-      "children" => children.map { |child| {"id" => child.id, "name" => child.name, "processing" => child.processing?} }
+      "children" => children.map { |child|
+        state = child.processing? ? "llm_generating" : "idle"
+        {"id" => child.id, "name" => child.name, "processing" => child.processing?, "session_state" => 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"
+  #
+  # For sub-agents, also broadcasts +child_state+ to the parent stream:
+  #   {"action" => "child_state", "state" => state, "session_id" => id, "child_id" => id}
+  #
+  # @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)
+
+    # Notify the parent's stream so the HUD updates child state icons
+    # without requiring a full children_updated query.
+    return unless parent_session_id
+
+    parent_payload = payload.merge("action" => "child_state", "child_id" => id)
+    ActionCable.server.broadcast("session_#{parent_session_id}", parent_payload)
+  end
+
+  # Broadcasts the full LLM debug context to debug-mode TUI clients.
+  # Called on every LLM request so the TUI shows exactly what the LLM
+  # receives — system prompt and tool schemas. No-op outside debug mode.
+  #
+  # @param system [String, nil] the final system prompt sent to the LLM
+  # @param tools [Array<Hash>, nil] tool schemas sent to the LLM
+  # @return [void]
+  def broadcast_debug_context(system:, tools: nil)
+    return unless view_mode == "debug" && system
+
+    ActionCable.server.broadcast("session_#{id}", self.class.system_prompt_payload(system, tools: tools))
+  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.
+  # MCP tools are excluded (they require live server queries and appear
+  # after the first LLM request via {#broadcast_debug_context}).
+  #
+  # @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)
+  end
+
+  # Builds the system prompt payload for debug mode transmission.
+  # Token estimate covers both the system prompt and tool schemas
+  # since both consume the LLM's context window.
+  # Tools are sent as raw schemas; the TUI formats them as TOON for display.
+  #
+  # @param prompt [String] system prompt text
+  # @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)
+
+    debug = {role: :system_prompt, content: prompt, tokens: tokens, estimated: true}
+    debug[:tools] = tools if tools&.any?
+
+    {
+      "id" => Message::SYSTEM_PROMPT_ID,
+      "type" => "system_prompt",
+      "rendered" => {"debug" => debug}
+    }
+  end
+
   private
 
+  # Finds recalled skill/workflow source names in the current viewport.
+  # Scans viewport messages for user_messages tagged with the given source_type.
+  #
+  # @param source_type [String] "skill" or "workflow"
+  # @return [Set<String>] source names present in the viewport
+  def recalled_sources_in_viewport(source_type)
+    ids = viewport_message_ids
+    return Set.new if ids.empty?
+
+    messages
+      .where(id: ids, message_type: "user_message")
+      .where("json_extract(payload, '$.source_type') = ?", source_type)
+      .pluck(Arel.sql("json_extract(payload, '$.source_name')"))
+      .to_set
+  end
+
+  # Enqueues a recalled skill or workflow as a {PendingMessage}.
+  # Always goes through the pending queue because the analytical brain
+  # only runs during processing. The message enters the conversation
+  # through the normal promotion flow as a phantom tool_use/tool_result pair.
+  #
+  # @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)
+    pending_messages.create!(content: content, source_type: source_type, source_name: source_name)
+  end
+
   # One-line version preamble so the agent knows its own version.
   # Useful for commits, handoffs, and debugging.
   #
@@ -446,17 +648,24 @@ class Session < ApplicationRecord
     "## Your Expertise\n\nYou know this deeply. Now's your chance to put it to work.\n\n#{sections.join("\n\n")}"
   end
 
-  # Assembles the goals section of the system prompt.
-  # Active root goals render as `###` headings with sub-goal checkboxes.
-  # Completed root goals collapse to a single strikethrough line.
+  # Assembles the task section for sub-agent system prompts.
+  # Sub-agents have a single pinned goal — their entire raison d'etre.
+  # Rendered as a persistent task block so the LLM always knows what it
+  # was spawned to do, regardless of conversation length.
   #
-  # @return [String, nil] goals section, or nil when no goals exist
-  def assemble_goals_section
-    root_goals = goals.root.includes(:sub_goals).order(:created_at)
-    return if root_goals.empty?
+  # @return [String, nil] task section, or nil when no active goal exists
+  def assemble_task_section
+    goal = goals.active.root.first
+    return unless goal
+
+    <<~SECTION.strip
+      Your Task
+      =========
+
+      #{goal.description}
 
-    entries = root_goals.map { |goal| render_goal_markdown(goal) }
-    "## Current Goals\n\n#{entries.join("\n\n")}"
+      Complete this task and call mark_goal_completed when done.
+    SECTION
   end
 
   # Renders a single root goal with its sub-goals as Markdown.
@@ -529,22 +738,13 @@ class Session < ApplicationRecord
   end
 
   # Scopes own messages for viewport assembly.
+  # Starts from the Mneme boundary (inclusive) — older messages have been
+  # compressed into snapshots and no longer participate in the viewport.
   # @return [ActiveRecord::Relation]
-  def own_message_scope(include_pending)
+  def own_message_scope
     scope = messages.context_messages
-    include_pending ? scope : scope.deliverable
-  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(include_pending)
-    scope = parent_session.messages.context_messages
-      .excluding_spawn_messages
-      .where(created_at: ...created_at)
-    include_pending ? scope : scope.deliverable
+    scope = scope.where("messages.id >= ?", mneme_boundary_message_id) if mneme_boundary_message_id
+    scope
   end
 
   # Walks messages newest-first, selecting until the token budget is exhausted.
@@ -573,21 +773,16 @@ class Session < ApplicationRecord
     (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)
@@ -604,28 +799,32 @@ 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.
+  # Assembles L1/L2 snapshots as a system prompt section.
+  # Snapshots are visible when their source messages precede the Mneme boundary
+  # (compressed in a previous run). Between Mneme runs this section is frozen,
+  # making it cache-friendly.
   #
-  # @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
+  # @return [String, nil] formatted snapshot text for the system prompt, or nil
+  def assemble_snapshots_section
+    reference_id = mneme_boundary_message_id || viewport_message_ids.first
+    return unless reference_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") }
+    l2_budget = (Anima::Settings.token_budget * Anima::Settings.mneme_l2_budget_fraction).to_i
+    l1_budget = (Anima::Settings.token_budget * Anima::Settings.mneme_l1_budget_fraction).to_i
 
-    l1_messages = select_snapshots_within_budget(
-      snapshots.for_level(1).not_covered_by_l2.source_messages_evicted(first_message_id).chronological,
+    l2 = select_snapshots_within_budget(
+      snapshots.for_level(2).source_messages_evicted(reference_id).chronological,
+      budget: l2_budget
+    )
+    l1 = select_snapshots_within_budget(
+      snapshots.for_level(1).not_covered_by_l2.source_messages_evicted(reference_id).chronological,
       budget: l1_budget
-    ).map { |snapshot| format_snapshot_message(snapshot, label: "recent memory") }
+    )
 
-    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.
@@ -650,40 +849,53 @@ class Session < ApplicationRecord
     selected
   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?
+
+    root_goals = goals.root.active.includes(:sub_goals).order(:created_at)
+    return [] if root_goals.empty?
 
     pins = pinned_messages
       .includes(:message, :goals)
       .where("pinned_messages.message_id < ?", first_message_id)
       .order("pinned_messages.message_id")
 
-    return [] if pins.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}"}]
+    selected_pins = select_pins_within_budget(pins, budget)
+    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::RECALL_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
@@ -707,23 +919,33 @@ class Session < ApplicationRecord
     selected
   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>}]
@@ -741,18 +963,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.
   #
@@ -762,109 +972,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}"
-    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 = [(text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
-      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
+      "  📌 message #{mid}: #{pin.display_text}"
     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
 
@@ -893,7 +1094,15 @@ class Session < ApplicationRecord
   # @example
   #   format_message_time(1_710_406_260_000_000_000) #=> "Thu Mar 14 09:51"
   def format_message_time(timestamp_ns)
-    Time.at(timestamp_ns / 1_000_000_000.0).strftime("%a %b %-d %H:%M")
+    Time.at(timestamp_ns / 1_000_000_000.0).utc.strftime("%a %b %-d %H:%M")
+  end
+
+  # Current time as nanoseconds since epoch. Uses Time.current so
+  # ActiveSupport's freeze_time works in tests.
+  #
+  # @return [Integer] nanoseconds since epoch
+  def now_ns
+    Time.current.to_ns
   end
 
   # Delegates to {Message#estimate_tokens} for messages not yet counted