anima-core 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8a12f6624492adc6c4de4e5fbc5e28df74edf73a568b73fc0819a8d3fc45163
-  data.tar.gz: 84f3c8680deb81a5e4989abd7b9eeafaae9bdc8e5b0a04db6af27c615f31144c
+  metadata.gz: 2ec0963d3bb57afc7a12414258c90d645dd200ca489bd7ab34e6ace19ea11927
+  data.tar.gz: 712d1904e5ddf7b0c244ddeffb2ed993f6265d097eb18000b139cdb08a9bfc4c
 SHA512:
-  metadata.gz: ae5c8c7ba47910544c6bb3b316bed1a90a54929cae275983c8dd36fca91cdceebbd06cd50b6a1e512d1142e38ab8ebc414b635dd0ed0ff67eea74c5e0af86d86
-  data.tar.gz: 8d8c6ddf84970520c805da2b2fb98d6b2c47faad068f5e602e89389bcc7e70bd206a0ed35dc7dc94aeef2bb8cea615e57627fcf883937d23ad2f70f5610bd6e2
+  metadata.gz: 3b70800258af5296bf243e7b0c020efd6f7736e3f1f58734352e022ca8ec7a15599ffce938fc1adc511bc37a7141472845dcead21b6512cdc09dfceae8b04b87
+  data.tar.gz: e70536705ac4d1cc468a951079799edd8677cae3c167251c60cccfbb51f79b0e2e7f896b5420f4972c8a59ee3d377ae0fd284d3603db441bd45313a1030f60ca

data/.reek.yml

@@ -35,8 +35,11 @@ detectors:
       - "Tools::SpawnSubagent#spawn_child"
       - "Tools::SpawnSpecialist#spawn_child"
       - "Tools::SpawnSpecialist#execute"
-      # Nickname assignment operates on child session and parent's children — inherent.
+      # Spawn helpers operate on child session — inherent to the mixin pattern.
       - "Tools::SubagentPrompts#assign_nickname_via_brain"
+      - "Tools::SubagentPrompts#inject_identity_context"
+      # Registry dispatches to tool's threshold method — duck-typing delegation.
+      - "Tools::Registry#truncation_threshold"
       # Goal tools operate on goal objects — inherent to the pattern.
       - "AnalyticalBrain::Tools::UpdateGoal#execute"
       # Validation methods naturally reference the validated value more than self.
@@ -92,6 +95,10 @@ detectors:
   UncommunicativeMethodName:
     exclude:
       - "ToolDecorator#self.encode_utf8"
+  # Registry uses respond_to? for duck-typing dispatch with MCP tool instances.
+  ManualDispatch:
+    exclude:
+      - "Tools::Registry#truncation_threshold"
   # Abstract base class methods declare parameters for the subclass contract.
   UnusedParameters:
     exclude:

data/README.md

@@ -132,7 +132,7 @@ State directory (`~/.anima/`):
 ├── config.toml      # Main settings (hot-reloadable)
 ├── mcp.toml         # MCP server configuration
 ├── config/
-│   └── credentials/ # Rails encrypted credentials per environment
+│   └── credentials/   # Rails encrypted credentials (includes AR encryption keys)
 ├── agents/          # User-defined specialist agents (override built-ins)
 ├── skills/          # User-defined skills (override built-ins)
 ├── workflows/       # User-defined workflows (override built-ins)
@@ -149,7 +149,7 @@ Anima uses your Claude Pro/Max subscription for API access. You need a setup-tok
 
 1. Run `claude setup-token` in a terminal to get your token
 2. In the TUI, press `Ctrl+a → a` to open the token setup popup
-3. Paste the token and press Enter — Anima validates it against the Anthropic API and saves it to encrypted credentials
+3. Paste the token and press Enter — Anima validates it against the Anthropic API and saves it to the encrypted secrets database
 
 The popup also activates automatically when Anima detects a missing or invalid token. If the token expires, repeat the process with a new one.
 
@@ -162,12 +162,17 @@ The agent has access to these built-in tools:
 | Tool | Description |
 |------|-------------|
 | `bash` | Execute shell commands with persistent working directory |
-| `read` | Read files with smart truncation and offset/limit paging |
-| `write` | Create or overwrite files |
-| `edit` | Surgical text replacement with uniqueness constraint |
+| `read_file` | Read files with smart truncation and offset/limit paging |
+| `write_file` | Create or overwrite files |
+| `edit_file` | Surgical text replacement with uniqueness constraint |
 | `web_get` | Fetch content from HTTP/HTTPS URLs (HTML → Markdown, JSON → TOON) |
 | `spawn_specialist` | Spawn a named specialist sub-agent from the registry |
 | `spawn_subagent` | Spawn a generic child session with custom tool grants |
+| `think` | Think out loud or silently — reasoning step between tool calls |
+| `recall` | Search past conversations by keywords (FTS5). Returns ranked snippets with message IDs for drill-down |
+| `remember` | Recall full conversation context around a past message at fractal resolution |
+| `open_issue` | File a self-improvement issue when something is broken, missing, or could be better |
+| `mark_goal_completed` | Sub-agent only: signal task completion and deliver results to parent |
 
 Plus dynamic tools from configured MCP servers, namespaced as `server_name__tool_name`.
 
@@ -189,7 +194,9 @@ Two types:
 
 **Generic Sub-agents** — child sessions with custom tool grants for ad-hoc tasks. Each generic sub-agent gets a Haiku-generated nickname (e.g. `@loop-sleuth`, `@api-scout`) for @mention addressing.
 
-Sub-agents communicate through natural text — their `agent_message` events route to the parent session automatically, and the parent replies via `@name` mentions. No special tools needed; when a sub-agent writes text, the parent sees it. When the parent @mentions a sub-agent, the message arrives in that child's session. Workers become colleagues.
+Each sub-agent is spawned with a single **Goal** pinned from its task description and a framing message that redirects attention away from inherited parent goals. When done, the sub-agent calls `mark_goal_completed` to deliver results to the parent — this is the explicit finish line that prevents runaway agents. Sub-agents also get half the main agent's thinking budget to limit scope creep.
+
+Between spawn and completion, sub-agents communicate through natural text — their `agent_message` events route to the parent session automatically, and the parent replies via `@name` mentions. Workers become colleagues.
 
 ### Skills
 
@@ -255,12 +262,12 @@ anima mcp add fs -- mcp-server-filesystem --root / # Add stdio server
 anima mcp add -s api_key=sk-xxx linear https://...  # Add with secret
 anima mcp remove sentry                     # Remove server
 
-anima mcp secrets set linear_api_key=sk-xxx # Store secret in encrypted credentials
+anima mcp secrets set linear_api_key=sk-xxx # Store secret in encrypted database
 anima mcp secrets list                      # List secret names (not values)
 anima mcp secrets remove linear_api_key     # Remove secret
 ```
 
-Secrets are stored in Rails encrypted credentials and interpolated via `${credential:key_name}` syntax in any TOML string value.
+Secrets are stored in an encrypted database table (Active Record Encryption) and interpolated via `${credential:key_name}` syntax in any TOML string value.
 
 ### Analytical Brain
 
@@ -270,7 +277,7 @@ The analytical brain observes the main conversation between turns and handles ev
 
 - **Skill activation** — activates/deactivates domain knowledge based on conversation context
 - **Workflow management** — recognizes tasks, activates matching workflows, tracks lifecycle
-- **Goal tracking** — creates root goals and sub-goals as work progresses, marks them complete
+- **Goal tracking** — creates root goals and sub-goals as work progresses, marks them complete, evicts finished goals from context after a configurable message threshold
 - **Session naming** — generates emoji + short name when the topic becomes clear
 
 Each of these would be a context switch for the main agent — a chore that competes with the primary task. For the analytical brain, they ARE the primary task. Two agents, each in their own flow state.
@@ -293,10 +300,13 @@ token_budget = 190_000
 api = 300
 command = 30
 
+[goals]
+completed_decay_messages = 5
+
 [analytical_brain]
 max_tokens = 4096
 blocking_on_user_message = true
-event_window = 20
+message_window = 20
 
 [session]
 default_view_mode = "basic"
@@ -396,6 +406,21 @@ The difference from every other system: memory isn't a tool the agent uses. It's
 
 The right-side HUD panel shows session state at a glance: session name, goals (with status icons), active skills, workflow, and sub-agents. Toggle with `C-a → h`; when hidden, the input border shows `C-a → h HUD` as a reminder.
 
+**Braille spinner**: An animated braille character (U+2800-U+28FF) replaces the old "Thinking..." label in both the chat viewport and HUD. Each processing state has a distinct animation pattern — smooth snake rotation for LLM generation, staccato pulse for tool execution, rapid deceleration for interrupting. Sub-agents in the HUD show state-driven icons: `●` (generating, green), `◉` (tool executing, green), `●` (interrupting, red), `◌` (idle, grey).
+
+When content exceeds the panel height, the HUD scrolls. Three input methods:
+
+| Input | Action |
+|-------|--------|
+| `C-a → →` | Enter HUD focus mode (yellow border) |
+| `↑` / `↓` | Scroll one line (when focused) |
+| `Page Up` / `Page Down` | Scroll one page (when focused) |
+| `Home` / `End` | Jump to top / bottom (when focused) |
+| `Escape` or `C-a` | Exit HUD focus mode |
+| Mouse wheel over HUD | Scroll without entering focus mode |
+
+**Escape key interrupt:** Press `Escape` while the agent is working to stop execution mid-tool. Running shell commands receive Ctrl+C and return partial output; pending tool calls are skipped; LLM text generation is discarded. The interrupt cascades to active sub-agents.
+
 Three switchable view modes let you control how much detail the TUI shows. Cycle with `C-a → v`:
 
 | Mode | What you see |
@@ -582,7 +607,7 @@ This single example demonstrates every core principle:
 - Dynamic viewport context assembly (endless sessions, no compaction)
 - Analytical brain (skills, workflows, goals, session naming)
 - Mneme memory department (eviction-triggered summarization, persistent snapshots, goal-scoped event pinning, associative recall)
-- 9 built-in tools + MCP integration (HTTP + stdio transports)
+- 12 built-in tools + MCP integration (HTTP + stdio transports)
 - 7 built-in skills + 13 built-in workflows (user-extensible)
 - Sub-agents with lossless context inheritance (5 specialists + generic)
 - Client-server architecture with WebSocket transport + graceful reconnection

data/agents/codebase-analyzer.md

@@ -1,7 +1,7 @@
 ---
 name: codebase-analyzer
 description: Traces data flow and explains how code works. Returns file:line references.
-tools: read, bash
+tools: read_file, bash
 ---
 
 You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.

data/agents/codebase-pattern-finder.md

@@ -1,7 +1,7 @@
 ---
 name: codebase-pattern-finder
 description: Finds similar implementations, usage examples, and existing patterns to model after. Returns concrete code examples.
-tools: read, bash
+tools: read_file, bash
 ---
 
 You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.

data/agents/documentation-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: documentation-researcher
 description: Fetches official docs. Returns ready-to-use code examples.
-tools: web_get, read
+tools: web_get, read_file
 color: cyan
 ---
 

data/agents/thoughts-analyzer.md

@@ -1,7 +1,7 @@
 ---
 name: thoughts-analyzer
 description: "thoughts/ holds design decisions, architecture notes, and implementation rationale. Answers WHY things work the way they do and how they should work by design."
-tools: read, bash
+tools: read_file, bash
 ---
 
 You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.

data/agents/web-search-researcher.md

@@ -1,11 +1,11 @@
 ---
 name: web-search-researcher
 description: Researches topics across multiple web sources. Use when a single page won't answer the question.
-tools: web_get, bash, read
+tools: web_get, bash, read_file
 color: yellow
 ---
 
-You are an expert web research specialist. Use `web_get` to fetch web pages and extract information. Use `bash` for processing and `read` for examining local files when needed.
+You are an expert web research specialist. Use `web_get` to fetch web pages and extract information. Use `bash` for processing and `read_file` for examining local files when needed.
 
 ## Core Responsibilities
 

data/app/channels/session_channel.rb

@@ -47,8 +47,8 @@ class SessionChannel < ApplicationCable::Channel
   # schedules {AgentRequestJob} for LLM delivery. If delivery fails, the
   # job deletes the message and emits a {Events::BounceBack}.
   #
-  # For busy sessions, emits a pending {Events::UserMessage} that queues
-  # until the current agent loop completes.
+  # For busy sessions, stages the message as a {PendingMessage} in a
+  # separate table until the current agent loop completes.
   #
   # @param data [Hash] must include "content" with the user's message text
   # @see Session#enqueue_user_message
@@ -63,38 +63,42 @@ class SessionChannel < ApplicationCable::Channel
   end
 
   # Recalls the most recent pending message for editing. Deletes the
-  # pending message and broadcasts the recall so all clients remove it.
+  # {PendingMessage} — its +after_destroy_commit+ broadcasts removal
+  # so all clients remove the pending indicator.
   #
-  # @param data [Hash] must include "message_id" (positive integer)
+  # @param data [Hash] must include "pending_message_id" (positive integer)
   def recall_pending(data)
-    message_id = data["message_id"].to_i
-    return if message_id <= 0
-
-    message = Message.find_by(
-      id: message_id,
-      session_id: @current_session_id,
-      message_type: "user_message",
-      status: Message::PENDING_STATUS
-    )
-    return unless message
-
-    message.destroy!
-    ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "message_id" => message_id})
+    pm_id = data["pending_message_id"].to_i
+    return if pm_id <= 0
+
+    pm = PendingMessage.find_by(id: pm_id, session_id: @current_session_id)
+    pm&.destroy!
   end
 
   # Requests interruption of the current tool execution. Sets a flag on the
   # session that the LLM client checks between tool calls. Remaining tools
-  # receive synthetic "Stopped by user" results to satisfy the API's
+  # receive synthetic "Your human wants your attention" results to satisfy the API's
   # tool_use/tool_result pairing requirement.
   #
+  # Cascades to running sub-agent sessions to avoid burning tokens in
+  # child jobs that the parent will discard anyway.
+  #
   # Atomic: a single UPDATE with WHERE avoids the read-then-write race where
   # the session could finish processing between the SELECT and UPDATE.
   # No-op if the session isn't currently processing.
   #
   # @param _data [Hash] unused
   def interrupt_execution(_data)
-    Session.where(id: @current_session_id, processing: true)
+    updated = Session.where(id: @current_session_id, processing: true)
       .update_all(interrupt_requested: true)
+
+    return unless updated > 0
+
+    Session.processing_children_of(@current_session_id)
+      .update_all(interrupt_requested: true)
+
+    Session.find_by(id: @current_session_id)&.broadcast_session_state("interrupting")
+    ActionCable.server.broadcast(stream_name, {"action" => "interrupt_acknowledged"})
   end
 
   # Returns recent root sessions with nested child metadata for session picker UI.
@@ -132,9 +136,9 @@ class SessionChannel < ApplicationCable::Channel
     transmit_error("Session not found")
   end
 
-  # Validates and saves an Anthropic subscription token to encrypted credentials.
+  # Validates and saves an Anthropic subscription token to encrypted storage.
   # Format-validated and API-validated before storage. The token never enters the
-  # LLM context window — it flows directly from WebSocket to encrypted credentials.
+  # LLM context window — it flows directly from WebSocket to the secrets table.
   #
   # @param data [Hash] must include "token" (Anthropic subscription token string)
   def save_token(data)
@@ -217,7 +221,10 @@ class SessionChannel < ApplicationCable::Channel
 
     children = session.child_sessions.order(:created_at).select(:id, :name, :processing)
     if children.any?
-      payload["children"] = children.map { |child| {"id" => child.id, "name" => child.name, "processing" => child.processing?} }
+      payload["children"] = children.map { |child|
+        state = child.processing? ? "llm_generating" : "idle"
+        {"id" => child.id, "name" => child.name, "processing" => child.processing?, "session_state" => state}
+      }
     end
 
     transmit(payload)
@@ -251,6 +258,7 @@ class SessionChannel < ApplicationCable::Channel
   # the transmitted payload. Tool messages are included so the TUI can
   # reconstruct tool call counters on reconnect.
   # In debug mode, prepends the assembled system prompt as a special block.
+  # Pending messages are sent last so the TUI shows them at the bottom.
   #
   # Snapshots the viewport so subsequent message broadcasts can compute
   # eviction diffs accurately.
@@ -262,11 +270,16 @@ class SessionChannel < ApplicationCable::Channel
     each_viewport_message(session) do |_msg, msg_payload|
       transmit(msg_payload)
     end
+
+    session.pending_messages.find_each do |pm|
+      transmit({"action" => "pending_message_created", "pending_message_id" => pm.id, "content" => pm.content})
+    end
   end
 
   # Broadcasts the re-decorated viewport to all clients on the session stream.
   # Used after a view mode change to refresh all connected clients.
   # In debug mode, prepends the assembled system prompt as a special block.
+  # Pending messages are sent last so the TUI shows them at the bottom.
   #
   # Snapshots the viewport so subsequent message broadcasts can compute
   # eviction diffs accurately.
@@ -279,12 +292,21 @@ class SessionChannel < ApplicationCable::Channel
     each_viewport_message(session) do |_msg, msg_payload|
       ActionCable.server.broadcast(stream_name, msg_payload)
     end
+
+    session.pending_messages.find_each do |pm|
+      ActionCable.server.broadcast(stream_name, {"action" => "pending_message_created", "pending_message_id" => pm.id, "content" => pm.content})
+    end
   end
 
   # Loads the viewport, snapshots it for eviction tracking, and yields
-  # each message with its decorated payload. Snapshot uses snapshot_viewport!
-  # (not recalculate_viewport!) because full viewport refreshes don't need
-  # eviction diffs — clients clear their store before rendering.
+  # each message with its decorated payload in newest-first order.
+  # Newest-first prevents render thrashing during session switches: the
+  # most recent messages fill the visible viewport immediately, while
+  # older messages are inserted above the fold without visual disruption.
+  #
+  # Snapshot uses snapshot_viewport! (not recalculate_viewport!) because
+  # full viewport refreshes don't need eviction diffs — clients clear
+  # their store before rendering.
   #
   # @param session [Session] the session whose viewport to iterate
   # @yieldparam message [Message] the persisted message record
@@ -294,7 +316,7 @@ class SessionChannel < ApplicationCable::Channel
     viewport = session.viewport_messages
     session.snapshot_viewport!(viewport.map(&:id))
 
-    viewport.each do |msg|
+    viewport.reverse_each do |msg|
       yield msg, decorate_message_payload(msg, session.view_mode)
     end
   end
@@ -338,23 +360,19 @@ class SessionChannel < ApplicationCable::Channel
   end
 
   # Builds the system prompt payload for debug mode transmission.
+  # Delegates to {Session.system_prompt_payload} for the shared format.
+  # Includes deterministic tool schemas (standard + spawn tools).
+  # MCP tools appear after the first LLM request via live broadcast.
   # @param session [Session]
   # @return [Hash, nil] the system prompt payload, or nil if no prompt
   def system_prompt_payload(session)
     prompt = session.system_prompt
     return unless prompt
 
-    tokens = [(prompt.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
-    {
-      "type" => "system_prompt",
-      "rendered" => {
-        "debug" => {role: :system_prompt, content: prompt, tokens: tokens, estimated: true}
-      }
-    }
+    Session.system_prompt_payload(prompt, tools: session.tool_schemas)
   end
 
-  # Merges the Anthropic subscription token into encrypted credentials,
-  # preserving existing keys (e.g. secret_key_base).
+  # Writes the Anthropic subscription token to encrypted storage.
   #
   # @param token [String] validated Anthropic subscription token
   # @return [void]

data/app/decorators/tool_call_decorator.rb

@@ -7,7 +7,7 @@ require "toon"
 # aggregated tool counter instead. Verbose mode returns tool name
 # and a formatted preview of the input arguments. Debug mode shows
 # full untruncated input with tool_use_id — TOON format for most
-# tools, but write tool content preserves actual newlines.
+# tools, but write_file tool content preserves actual newlines.
 #
 # Think tool calls are special: "aloud" thoughts are shown in all
 # view modes (with a thought bubble), while "inner" thoughts are
@@ -97,14 +97,14 @@ class ToolCallDecorator < MessageDecorator
   def format_debug_input
     input = tool_input
     case payload["tool_name"]
-    when "write" then format_write_content(input)
+    when "write_file" then format_write_content(input)
     else Toon.encode(input)
     end
   end
 
   # Formats write tool input with file path header and content body.
   # Content newlines are preserved so the TUI can render them as
-  # separate lines, matching how read tool responses display file content.
+  # separate lines, matching how read_file tool responses display file content.
   # @param input [Hash] tool input hash with "file_path" and "content" keys
   # @return [String] path + content with real newlines, or TOON-encoded hash when content is empty
   def format_write_content(input)
@@ -125,7 +125,7 @@ class ToolCallDecorator < MessageDecorator
       "$ #{input&.dig("command")}"
     when "web_get"
       "GET #{input&.dig("url")}"
-    when "read", "edit", "write"
+    when "read_file", "edit_file", "write_file"
       input&.dig("file_path").to_s
     else
       truncate_lines(Toon.encode(input), max_lines: 2)

data/app/decorators/user_message_decorator.rb

@@ -3,22 +3,15 @@
 # Decorates user_message records for display in the TUI.
 # Basic mode returns role and content. Verbose mode adds a timestamp.
 # Debug mode adds token count (exact when counted, estimated when not).
-# Pending messages include `status: "pending"` so the TUI renders them
-# with a visual indicator (dimmed, clock icon).
 class UserMessageDecorator < MessageDecorator
-  # @return [Hash] structured user message data
-  #   `{role: :user, content: String}` or with `status: "pending"` when queued
+  # @return [Hash] structured user message data `{role: :user, content: String}`
   def render_basic
-    base = {role: :user, content: content}
-    base[:status] = "pending" if pending?
-    base
+    {role: :user, content: content}
   end
 
   # @return [Hash] structured user message with nanosecond timestamp
   def render_verbose
-    base = {role: :user, content: content, timestamp: timestamp}
-    base[:status] = "pending" if pending?
-    base
+    {role: :user, content: content, timestamp: timestamp}
   end
 
   # @return [Hash] verbose output plus token count for debugging
@@ -31,11 +24,4 @@ class UserMessageDecorator < MessageDecorator
   def render_brain
     "User: #{truncate_middle(content)}"
   end
-
-  private
-
-  # @return [Boolean] true when this message is queued but not yet sent to LLM
-  def pending?
-    payload["status"] == Message::PENDING_STATUS
-  end
 end

data/app/jobs/agent_request_job.rb

@@ -155,18 +155,27 @@ class AgentRequestJob < ApplicationJob
 
   # Sets the session's processing flag atomically. Returns true if this
   # job claimed the lock, false if another job already holds it.
-  # Broadcasts the state change to the parent session's HUD.
+  # Broadcasts +session_state: llm_generating+ and the state change to
+  # the parent session's HUD.
   def claim_processing(session_id)
     claimed = Session.where(id: session_id, processing: false).update_all(processing: true) == 1
-    Session.find_by(id: session_id)&.broadcast_children_update_to_parent if claimed
+    if claimed
+      session = Session.find_by(id: session_id)
+      session&.broadcast_session_state("llm_generating")
+      session&.broadcast_children_update_to_parent
+    end
     claimed
   end
 
   # Clears the processing flag so the session can accept new jobs.
-  # Broadcasts the state change to the parent session's HUD.
+  # Broadcasts +session_state: idle+ to the session stream (replaces
+  # the old +processing_stopped+ action) and +children_updated+ to the
+  # parent session's HUD.
   def release_processing(session_id)
     Session.where(id: session_id).update_all(processing: false)
-    Session.find_by(id: session_id)&.broadcast_children_update_to_parent
+    session = Session.find_by(id: session_id)
+    session&.broadcast_session_state("idle")
+    session&.broadcast_children_update_to_parent
   end
 
   # Safety-net clearing of the interrupt flag.

data/app/models/goal.rb

@@ -25,6 +25,16 @@ class Goal < ApplicationRecord
   scope :completed, -> { where(status: "completed") }
   scope :root, -> { where(parent_goal_id: nil) }
 
+  # @!method self.not_evicted
+  #   Goals still visible in context (not yet evicted by the analytical brain).
+  #   @return [ActiveRecord::Relation]
+  scope :not_evicted, -> { where(evicted_at: nil) }
+
+  # @!method self.evictable
+  #   Completed goals pending eviction — visible to the brain for age-based review.
+  #   @return [ActiveRecord::Relation]
+  scope :evictable, -> { completed.where(evicted_at: nil) }
+
   after_commit :broadcast_goals_update
   after_commit :schedule_passive_recall, on: [:create, :update]
 
@@ -37,6 +47,9 @@ class Goal < ApplicationRecord
   # @return [Boolean] true if this is a root goal (no parent)
   def root? = !parent_goal_id
 
+  # @return [Boolean] true if this goal has been evicted from display
+  def evicted? = evicted_at.present?
+
   # Cascades completion to all active sub-goals. Called when a root goal
   # is finished — remaining sub-items are implicitly resolved because
   # the semantic episode that spawned them has ended.

data/app/models/message.rb

@@ -29,7 +29,6 @@ class Message < ApplicationRecord
   CONVERSATION_TYPES = %w[user_message agent_message system_message].freeze
   THINK_TOOL = "think"
   SPAWN_TOOLS = %w[spawn_subagent spawn_specialist].freeze
-  PENDING_STATUS = "pending"
 
   # Message types that require a tool_use_id to pair call with response.
   TOOL_TYPES = %w[tool_call tool_response].freeze
@@ -39,6 +38,18 @@ class Message < ApplicationRecord
   # Heuristic: average bytes per token for English prose.
   BYTES_PER_TOKEN = 4
 
+  # Synthetic ID for system prompt entries in the TUI message store.
+  # Real message IDs are positive integers from the database, so 0
+  # is safe for deduplication without collision risk.
+  SYSTEM_PROMPT_ID = 0
+
+  # Estimates token count from a byte size using the {BYTES_PER_TOKEN} heuristic.
+  # @param bytesize [Integer] number of bytes
+  # @return [Integer] estimated token count (at least 1)
+  def self.estimate_token_count(bytesize)
+    [(bytesize / BYTES_PER_TOKEN.to_f).ceil, 1].max
+  end
+
   belongs_to :session
   has_many :pinned_messages, dependent: :destroy
 
@@ -60,17 +71,6 @@ class Message < ApplicationRecord
   #   @return [ActiveRecord::Relation]
   scope :context_messages, -> { where(message_type: CONTEXT_TYPES) }
 
-  # @!method self.pending
-  #   User messages queued during active agent processing, not yet sent to LLM.
-  #   @return [ActiveRecord::Relation]
-  scope :pending, -> { where(status: PENDING_STATUS) }
-
-  # @!method self.deliverable
-  #   Messages eligible for LLM context (excludes pending messages).
-  #   NULL status means delivered/processed — the only excluded value is "pending".
-  #   @return [ActiveRecord::Relation]
-  scope :deliverable, -> { where(status: nil) }
-
   # @!method self.excluding_spawn_messages
   #   Excludes spawn_subagent/spawn_specialist tool_call and tool_response messages.
   #   Used when building parent context for sub-agents — spawn messages cause role
@@ -98,11 +98,6 @@ class Message < ApplicationRecord
     message_type.in?(CONTEXT_TYPES)
   end
 
-  # @return [Boolean] true if this is a pending message not yet sent to the LLM
-  def pending?
-    status == PENDING_STATUS
-  end
-
   # @return [Boolean] true if this is a conversation message (user/agent/system)
   #   or a think tool_call — the messages Mneme treats as "conversation" for boundary tracking
   def conversation_or_think?
@@ -121,7 +116,7 @@ class Message < ApplicationRecord
     else
       payload["content"].to_s
     end
-    [(text.bytesize / BYTES_PER_TOKEN.to_f).ceil, 1].max
+    self.class.estimate_token_count(text.bytesize)
   end
 
   private

data/app/models/pending_message.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# A user message waiting to enter a session's conversation history.
+# Pending messages live in their own table — they are NOT part of the
+# message stream and have no database ID that could interleave with
+# tool_call/tool_response pairs.
+#
+# Created when a user sends a message while the session is processing.
+# Promoted to a real {Message} (delete + create in transaction) when
+# the current agent loop completes, giving the new message an ID that
+# naturally follows the tool batch.
+#
+# @see Session#enqueue_user_message
+# @see Session#promote_pending_messages!
+class PendingMessage < ApplicationRecord
+  belongs_to :session
+
+  validates :content, presence: true
+
+  after_create_commit :broadcast_created
+  after_destroy_commit :broadcast_removed
+
+  private
+
+  # Broadcasts a pending message appearance so TUI clients render the
+  # dimmed indicator immediately.
+  def broadcast_created
+    ActionCable.server.broadcast("session_#{session_id}", {
+      "action" => "pending_message_created",
+      "pending_message_id" => id,
+      "content" => content
+    })
+  end
+
+  # Broadcasts pending message removal so TUI clients clear the entry.
+  # Fires on both promotion (normal flow) and recall (user edit).
+  def broadcast_removed
+    ActionCable.server.broadcast("session_#{session_id}", {
+      "action" => "pending_message_removed",
+      "pending_message_id" => id
+    })
+  end
+end