oikos/plans/done/2026-08-03-nomos-chat-reliability-and-ux-audit.md

2026-08-03 — Nomos chat: reliability & predictability audit

Status: Implemented (F1–F7) in v0.15.0; F8 deferred. See Resolution at the end.

Scope: The live chat/task UX across one production session, audited through the code paths behind each operator-reported symptom — cmd/nomos/{main.go,agent.go,continue.go,store.go}, web/src/lib/stores/{chat,activity,execstream,events,workspace}.ts, web/src/lib/components/{ChatThread,AgentTrace,ToolCallCard,UnifiedTimeline,TaskContextPanel,SessionChatWindow}.svelte. Trigger: Operator report — streaming invisible in the tool card; the activity/plan panel wrong about parallel/nested runs and timestamps with no clear sequence; no links to artifacts/knowledge referenced in chat; agent "thinking" flickers/overwrites itself; layout jumps when a chat goes from empty to content; "Agent connection lost / Error in input stream" messages that aren't actionable and don't self-resolve; overall flaky/disconnected feel where the task never cleanly ended.

The prior round (2026-07-30-session-review-plan-drift-and-dead-activity-panel.md, shipped in 467589d) fixed the plan-seq and fabricated-timestamp rendering bugs. This round's symptoms are a different layer: turn orchestration, streaming wiring, and connection-state UX. One architectural gap (F1) is the common cause behind several of them.

---

The one root cause that compounds everything: F1

F1 — No per-session turn serialization (concurrent turns corrupt the view)

handleChat runs a.chat(ctx, ...) directly in the HTTP request goroutine, and every "resume" path (resumeSession, the reconnect empty-message path, the auto-continuation worker, the idle sweep, answer-question) launches another goroutine (safego.Go) running a full turn. There is no mutex keyed on sessionID anywhere. The codebase already knows this is a hazard — agent.go:316-323 marks approved executions continued specifically because "two concurrent LLM calls for the same session cause empty responses and race conditions" — but the fix is per-path patching, not a general lock.

What this produces, deterministically:

• A network blip on the browser↔nomos stream fires handleDisconnect (chat.ts:383), which POSTs an empty-message reconnect → main.go:194-206 spawns resumeSession as a new goroutine. If the original turn is still alive (or finishes its current tool call), two turns now run for one session: interleaved tool_use/text_delta events, a re-proposed plan, and "the agent is repeating itself."
• The activity timeline (activity.ts:119-185) groups tools under a plan step by inferring currentStepSeq from update_plan_step calls in the message stream. Two interleaved turns make that inference wrong → tools land under the wrong step, steps appear to nest/parallelize that never did, the sequence reads as garbage. This is the "parallel runs / nesting / no clear sequence" report.
• Two turns appending to the same session's messages is also the source of the duplicate-tool-call/empty-response class of bugs the prior plan docs keep patching individually.

This is why the experience "felt flaky and disconnected" and "the task didn't end": the panel is faithfully rendering a corrupted, interleaved event stream.

Fix (proposed)

1. One in-flight turn per session, server-side. Add a per-sessionID turn mutex (a sync.Map[string]*singleflight or a keyed sync.Mutex) in handleChat/resumeSession/continue.go. A second attempt to start a turn for a session that already has one running must queue (preferred — the operator's message waits its turn) or return 409 "turn in progress" (the frontend then just re-polls; no new goroutine). This single change removes the interleaving that drives F2/F3/F8.
2. Make the empty-message reconnect a no-op when a turn is already running. Today it always spawns resumeSession. Gate it on "is any turn active for this session?" — if yes, return 202 and let the existing turn + the poller do the work. A blip should never create work.

---

F2 — Reconnect spawns a new turn and surfaces raw, non-actionable errors

chat.ts:383-426 handleDisconnect: on a dropped SSE it sets connectionState='disconnected', starts the 3s poller, shows "Agent connection lost. The task is still running — retrying…", then calls streamChat('', sid, …) up to 3× — each of which is the empty-message POST that triggers F1's new resumeSession goroutine. Separately, the LLM stream errors surface verbatim: agent.go:388 does emitError("llm: %v", err), so an OpenRouter transport break reaches the operator as llm: error in input stream: … (the openai-go SDK's SSE-reader text), shown raw in ChatThread's error bar.

Combined with F1, this is the exact "messages not actionable and not self-resolving" + "task didn't end" experience: a blip both invents a duplicate turn and paints a scary, unfixable error that lingers.

Secondary defects in the same path:

• streaming stays true for the entire reconnect window, so the composer is disabled and the poller's if (streaming && connected) return guard (chat.ts:177) suppresses updates except while disconnected — fragile.
• The per-window error path (sendSessionMessage, startTask) does not auto-reconnect at all — it only polls. Its onReconnect in SessionChatWindow.svelte:110 is () => loadSessionChat(sessionId), which just re-fetches the transcript and never re-attaches to a live stream. And the global reconnect() (chat.ts:428) keys off the global currentSession, so a floating window's Reconnect button can target the wrong session. Two different, both-broken reconnect behaviors.

Fix (proposed)

1. Stop the empty-message-reconnect from creating turns (depends on F1.2). Reconnect should mean "catch up," not "run more."
2. Humanize + bucket error strings. Map known transport errors to operator-readable, actionable copy with a single primary action:
   • llm: …input stream… / 502/503/timeout → "The model connection dropped. The task is still running in the background — it'll catch up automatically." (auto-dismiss when the next event/poll lands)
   • HTTP 401/403 → "Session expired — reconnect." (action: re-auth)
   • unknown → show the raw text but behind a "Details" toggle, not as the headline.
3. Make errors self-resolving. Clear the error + connection-lost banner the moment the poller sees a newer message or any live event for the session arrives (wire eventsConnected / a session-scoped event into the banner's visibility). Today the banner stays until manual dismiss even after recovery.
4. Unify reconnect. One reconnect(sessionId) that (a) re-fetches the transcript, (b) if no turn is active, is a pure no-op refresh; used by both the main view and windows. Drop the global-currentSession coupling.

---

F3 — The UI can't tell when a turn truly ended (so it never looks "done")

When the SSE stream ends without a done event, streamChat's onDone (chat.ts:355-368) calls handleDisconnect. Even if the backend turn then finishes and persists its final message, the frontend only learns via the 3s poller re-setting messages — but nothing transitions streaming→false or connectionState→connected from that path, so the spinner/indicator and the "connection lost" banner can persist indefinitely. That is "the task didn't end / backend connection was lost."

The backend does emit a terminal signal — task.status events on complete_task/auto-complete (workspace.ts:82-88 STATUS_AFFECTING) — but nothing in the chat store reacts to a terminal task.status to force streaming=false + clear the banner. The signal exists; the chat ignores it.

Fix (proposed)

1. Treat a terminal task.status (done/failed) for the viewed session as authoritative end-of-turn in chat.ts: set streaming=false, connectionState='connected', dismiss any connection-lost error. The poller already refreshes messages; this just closes the loop on the state flags.
2. Add a task.completed / turn.ended SSE event from the backend on every terminal path (today done is a chat-stream-only event; background turns have no equivalent). The always-on events stream already reaches the panel — route the same signal to the chat store so background-completed turns clear the UI without waiting on a poll.

---

F4 — Command streaming isn't shown where the operator looks

Streaming exists (execstream.ts liveExecutionOutputFor, fed by fetchExecutionLogs via the always-on events stream) and the UnifiedTimeline does render tool.liveOutput with tail-pinned scroll (UnifiedTimeline.svelte:451-457). But:

• The global activityLog (activity.ts:236) — used by the main Chat page's panel — never calls withLiveOutput. Only the per-window activityLogFor(sessionId) (activity.ts:271) attaches live output. So the main chat view's timeline shows no streaming at all.
• The inline chat tool cards — ToolCallCard.svelte (rendered inside AgentTrace.svelte) — show only args/result/error. They never read liveOutput. Expanding a running run call in the transcript (the natural place to "check the tool") shows nothing live; output appears all at once when the tool_result lands.

This is the report: "I expected checking on the tool to let me see the streaming."

Fix (proposed)

1. Wire live output into the global activityLog so the main chat panel streams too (call withLiveOutput in the activityLog derivation, same as activityLogFor).
2. Show streaming in the inline tool card. Pass the session's live-output store into AgentTrace/ToolCallCard (or attach liveOutput to the running run tool entry the way the timeline does) and render a tail-pinned <pre> while the call is tool_use/running. Reuse the UnifiedTimeline's scroll-pin pattern. Gated runs (queued-for-approval) should instead show a "queued — watch in entity detail" affordance (per execstream.ts header comment).

---

F5 — Artifacts and knowledge referenced in chat aren't navigable

When the agent records knowledge, the activity panel shows Recorded: <title> (activity.ts:188-203) but it's plain text — no link. The backend already emits knowledge.recorded and links the note to the task (store.go:1572 linkKnowledgeToTask, agent.go:594), and the Wiki reader exists (web/src/lib/components/knowledge/WikiReader.svelte). Nothing connects them. Same for get_entity/run results: slugs and execution ids appear in tool output but aren't clickable to open the entity window or execution view.

Fix (proposed)

1. Make activity/tool entries link-bearing. Add an optional link?: { kind: 'knowledge'|'entity'|'execution', id: string } to ActivityEntry. Populate it from upsert_knowledge (title→knowledge id from the result), get_entity (slug), and run (execution id). Render a clickable chip that opens the right surface: knowledge → Wiki reader (new tab / window), entity → entity detail window, execution → execution log pane (already fetched by EntityDetailContent.svelte).
2. Render entity/knowledge mentions in assistant markdown as links when they resolve to known slugs (lightweight: a post-process pass on rendered text, or let the model emit explicit [slug](entity:…) markers it already has tools to discover).

---

F6 — "Thinking" is an unstable single-line headline, not a predictable trace

ChatThread's indicatorLabel (ChatThread.svelte:83-89) returns the first running activity entry's description; AgentTrace's headline mirrors it. As tools fire sequentially the running entry changes, so the one line rewrites itself every call — "the thinking overwrites itself." There is no persistent, additive reasoning surface, and no predictable turn structure (plan → steps → answer) the operator can learn to read. Claude-Code-style predictability is absent.

Fix (proposed)

1. A stable, additive per-turn reasoning block. Keep the collapsed trace as a summary ("Step 2 of 4 · running run"), but when expanded show an append-only log of (a) the model's intermediate text (reasoning before each tool call — already emitted at agent.go:458-460 and persisted) and (b) each tool call as a fixed row, instead of a single mutating headline.
2. Predictable turn shape. Enforce/cue a consistent sequence in the UI — Goal → Plan → Steps (each with its tools nested) → Final answer — and render each phase as a stable section that fills in rather than a line that overwrites. The UnifiedTimeline already models most of this; surface the same model in the inline trace so chat and panel tell one story.

---

F7 — Layout jumps when a chat goes from empty to content

SessionChatWindow.svelte:58-63 gates the right rail on hasContext: empty task → ChatThread full-width; first activity/touched entity → switches to Splitpanes with the TaskContextPanel rail. The swap is instant and reflows the chat column width the moment the first event lands — "switching from empty to chat with something, the layout was off." Compounded by the NewTaskChat → real SessionChatWindow window-swap on first send (NewTaskChat.svelte:17-22).

Fix (proposed)

1. Reserve the rail's space from the start (collapse to a thin sliver / icon rail when empty) instead of mounting it on demand, so adding content doesn't change the chat column width. Or animate the rail in.
2. Avoid the window swap on first send — let the new-task window become the session window in place once the id is assigned (same component, swap the store source) rather than close+open.

---

F8 — Activity/plan ordering & parallelism (largely a symptom of F1)

With F1 fixed (no interleaved turns) the heuristic step-grouping in activity.ts becomes reliable again. Remaining standalone items:

• The timeline is newest-first with ts-0 goal/pending parked at the bottom (UnifiedTimeline.svelte:119-127); for a long task this can read as "sequence is off." Consider an explicit oldest-first / seq-ordered mode toggle, and always show the step number prominently so order is unambiguous regardless of sort.
• Background/auto-continued turns still rely on the 3s poller for their result to appear; until F3's terminal event lands, the panel can lag. The always-on events stream already carries plan.* and entity.touched live — extend it to carry per-tool tool.* deltas for background turns so the panel is live, not polled, during autonomous work.

---

Recommended sequence

Order	Item	Why first
1	F1 per-session turn mutex + no-op reconnect-when-busy	Removes the interleaving that is the root cause of F2/F3/F8 symptoms; everything else is cosmetics on top of a corrupted stream.
2	F3 terminal-event → clear chat state	Once turns can't double, make "the task ended" unambiguous so the UI stops lingering.
3	F2 humanized/self-resolving errors + unified reconnect	Turns the scary, sticky "connection lost / input stream" into recoverable, auto-clearing UX.
4	F4 streaming in the global log + inline tool card	Highest-visibility "I can't see what it's doing" fix; small, isolated change.
5	F6 stable additive reasoning trace	Predictability of the interaction model (the Claude-Code feel).
6	F5 artifact/knowledge deep links	Navigation completeness.
7	F7 layout stability	Polish.
8	F8 ordering mode + live background deltas	Polish, partly free after F1.

Verification hooks (when implementing)

• cmd/nomos: a test that starts two turns for the same session and asserts the second queues/is-rejected (no interleaved tool_use order in persisted messages).
• web/src/lib/stores: extend activity.test.ts/execstream.test.ts — global activityLog now carries liveOutput; tool-card live output renders while tool_use and clears on tool_result.
• A reconnect/integration test: drop the SSE mid-turn, assert (a) no duplicate resumeSession goroutine, (b) banner auto-clears on next event, (c) streaming returns to false on terminal task.status.

---

Note on method

This audit was done against the code paths behind the reported symptoms, not a single session transcript (no MCP/DB access from this session). To tie a specific finding to a specific past session, pull the session via docker exec oikos-postgres-1 psql -U oikos oikos -c "select id,goal,outcome from agent_sessions order by last_active_at desc limit 5" and cross-reference its agent_activity rows / persisted messages against the F1 interleaving signature (two assistant turns' tool ids interleaved in one message shell).

---

Resolution (2026-08-03)

Implemented F1–F7 in v0.15.0 (VERSION 0.14.2 → 0.15.0). F8 deferred (its primary symptom — interleaved/out-of-order entries — is removed by F1; the ordering toggle and live background tool-delta streaming remain as nice-to- haves).

Item	What shipped	Where
F1	Per-session single-flight turn gate (turnGate): at most one in-flight turn per session. Background resume paths (resumeSession — covers the continuation worker, idle sweep, answer-question, /resume, and the empty-message reconnect) skip non-blocking when busy; the live chat path waits briefly then bails with an actionable error instead of stacking a second turn.	cmd/nomos/turngate.go (+turngate_test.go), wired in agent.go (struct/init), continue.go (resumeSession), main.go (handleChat).
F3	Terminal task.status events (done/failed/abandoned/awaiting_input) now clear a stuck chat view's streaming/connectionState and dismiss the connection-lost toasts — the authoritative "turn ended" signal the UI was ignoring. Poller safety net catches the edge where the event fired during the disconnect window.	web/src/lib/stores/chat.ts (clearTurnState, liveEvents subscription, startSessionPolling).
F2	Raw errors humanized ("The model connection dropped. The task keeps running…") and bucketed; one connection surface per drop (not banner+toast+raw error); errors self-clear via F3. The turn-spawning reconnect attempt loop is gone (dead global path simplified to a turn-free refresh); window "Reconnect" re-fetches + resets state.	web/src/lib/stores/chat.ts (humanizeChatError, error handlers, loadSessionChat, handleDisconnect/reconnect), web/src/lib/components/ChatThread.svelte (banner copy).
F4	Command streaming now shows (a) in the global activity timeline (live output wired into activityLog, was only per-window) and (b) in the inline chat tool card — expanding a running run shows live output auto-opened and tail-pinned.	web/src/lib/types.ts (liveOutput), web/src/lib/stores/activity.ts (currentLiveOutput), web/src/lib/components/ChatThread.svelte (toolsWithLive), web/src/lib/components/ToolCallCard.svelte.
F6	The "thinking" headline is now step-first (stable across a step's many tool calls) instead of rewriting per command; falls back to the current tool / "thinking…" only when no step is active.	web/src/lib/components/ChatThread.svelte (indicatorLabel).
F5	Activity entries now carry a deep link: recorded knowledge docs and get_entity lookups get an "open artifact" chip that opens the entity/knowledge window directly.	web/src/lib/stores/activity.ts (link, knowledgeLinkFromResult, entityLinkFromArgs), web/src/lib/components/UnifiedTimeline.svelte.
F7	The empty→content layout reflow is gone: SessionChatWindow now has one stable Splitpanes+ChatThread from open (no more destroy/remount of the thread or column reflow when the rail appears).	web/src/lib/components/SessionChatWindow.svelte.

Verification:

• go test ./cmd/nomos/ green (incl. new turngate_test.go: non-blocking skip, blocking-waits-for-release, timeout, and a 50-goroutine single-flight concurrency test asserting max in-flight = 1). go vet clean.
• Web vitest 70/70 green (incl. activity.test.ts/execstream.test.ts); the activity.test.ts chat mock gained currentSession for the new currentLiveOutput derivation.
• vite build succeeds (all Svelte components compile). Pre-existing tsc strictness errors in unrelated files (ui/*, oidc.ts, windows.ts, workspace.ts) are unchanged; no new errors in any touched file.

Follow-ups (not in this pass):

• F8: oldest-first ordering toggle; emit per-tool tool.* events on the always-on stream during background resumeSession turns so the panel is live (not 3s-polled) during autonomous work.
• F5: run execution deep-links (open the entity detail's execution pane) — needs an execution-view opener; knowledge/entity links shipped first as the explicit complaint.
• F7: the NewTaskChat → SessionChatWindow window-swap on first send (a windows.ts open/close) still causes a brief flash; an in-place handoff (same window, swap store source) would remove it.