SouveraineOS/docs/substrate/tasks/subconscious-live-reasoning-stream.md

Subconscious Live Reasoning Stream

Status: 🔴 Open Priority: High Phase: Design

Problem

The subconscious pass (N+1) runs silently — no visible output until it either surfaces something into the chat field or finishes. The user sees only the [surface] Subconscious pass complete message, with no insight into what the subconscious is thinking, what tools it's calling, or how it's reasoning.

Desired Behavior

1. During the pass — Live reasoning ticker

A scrolling/fading one-liner in the TUI (below the phase indicator) shows the subconscious's actual thinking/reasoning/tool calls in real-time:

⟡ subconscious: reviewing conversation for anomalies...
⟡ subconscious: consulting memory ledger for user energy levels...
⟡ subconscious: tool — read memory/ledger/energy-balance.md

This is transient — it flows while the pass runs and is not persisted in the chat field. Each line fades or scrolls as the next appears.

What feeds it:

• Subconscious thinking tokens (the content it produces before tool calls)
• Tool calls the subconscious makes (tool name + brief arg summary)
• Tool results (compact, one line)
• Essentially everything the consciousness_engine.rs streaming events already emit, but redirected to a live TUI display instead of just firehose

2. When the pass completes — Cockpit event log

The live stream moves into the cockpit's subconscious section, becoming a persistent, clickable list of past subconscious turns. Each turn entry shows:

• A brief summary of what the pass did ("reviewed conversation, checked ledger")
• Tool counts and types
• Scrollable/collapsible per-turn

Clicking a turn opens an overlay (same pattern as /btw) showing the full transcript: reasoning tokens, tool calls with inputs/outputs, final output.

This replaces the current raw-text dump in the cockpit subconscious pane.

3. Surfacing events (chat field) — Rare, agency-driven

Already partially designed in subconscious-surfacing-threshold.md. The subconscious only surfaces into the chat field when it has something genuinely important to raise. The threshold is the subconscious's own judgment, not a scoring system.

Implementation Notes

• The live stream and the cockpit event log are linked — the same event data powers both views
• Events need a structured format on the Rust side (not just formatted strings) so they can be rendered differently in live vs cockpit vs overlay contexts
• The /btw-style overlay pattern already exists in overlays.rs — reuse that component
• The cockpit subconscious pane currently renders raw text (cockpit.rs) — this becomes a structured event log
• Tool visibility in the stream is important for debugging: seeing what tools the subconscious reaches for naturally tells us how to improve the system

Dependencies

• docs/tasks/subconscious-surfacing-threshold.md — the surfacing-on-complete design
• docs/bugs.md B-005 — subconscious messages not expandable

Related

• src/server/consciousness_engine.rs — the N+1 pass that produces the events
• src/ui/chat/cockpit.rs — current raw-text rendering (to be replaced)
• src/ui/chat/overlays.rs — /btw overlay pattern to reuse
• src/ui/chat/events.rs — where BackendEvent variants could be added for streaming reasoning