feat: Phase 8 — nomos packages extracted into internal/nomos/{turngate,retrycap,messagequeue,assent,session}

Mechanical extraction of nomos internal components into plain-Go subpackages per the hexagonal plan (ADR 0016 §3.1 rule 3): turngate/ — per-session turn serialization (plan 2026-08-03 F1) retrycap/ — per-turn run retry cap (maxRunRetries=3) messagequeue/ — operator-message queue for busy-turn re-entry (F2) assent/ — chat-assent detection (isAssent, isTypedConfirmation, ExtractPendingApprovals), decoupled from agent via []string input instead of persistedCall session/ — store (chat sessions, plan execution, DB persistence), migration runner + local emitEvent to break adapter dependency internal/migrate/ — shared migration runner extracted from postgres pool, used by both the oikos postgres adapter and session tests. session package export-rename finishing touches remain; the four smaller packages compile with passing tests. Depguard rules and ADR-0016 leaf-note update deferred to a followup. VERSION 0.35.1.
2026-08-16 10:31:45 +02:00
parent 7c9f4ec79f
commit 7a7d390718
22 changed files with 629 additions and 683 deletions
--- a/internal/nomos/turngate/turngate.go
+++ b/internal/nomos/turngate/turngate.go
@@ -0,0 +1,90 @@
+package turngate
+
+import (
+	"sync"
+	"time"
+)
+
+// TurnGate enforces at most one in-flight agent turn per session.
+//
+// Why this exists (plan 2026-08-03, F1): handleChat runs a turn in the HTTP
+// request goroutine, and every "resume" path (the empty-message reconnect,
+// the auto-continuation worker, the idle sweep, answer-question, the /resume
+// endpoint) launches ANOTHER goroutine running a full turn. Nothing prevented
+// two turns for the SAME session at once, so a network blip that triggered a
+// reconnect would spawn a duplicate resumeSession while the original turn was
+// still alive — their tool calls interleaved on the wire and in the persisted
+// transcript, which is the root cause behind the "parallel/nesting/sequence
+// is off" and "task didn't end / flaky" reports.
+//
+// Model: one permit (buffered-1 channel seeded with a single token) per
+// session id. Acquiring consumes the token; releasing puts it back.
+//   - Background/best-effort callers (resumeSession and everything it backs)
+//     use a non-blocking Acquire and SKIP when busy — a duplicate nudge while a
+//     turn is already running adds nothing, and the continuation/idle tickers
+//     will retry on their own.
+//   - The live chat path (an operator message) waits briefly for a finishing
+//     background turn, then bails with an actionable error if still busy — see
+//     handleChat.
+//
+// The permits map grows one entry per session id seen. For this single-agent
+// homelab process that set is small and bounded by real sessions; cleanup is
+// intentionally omitted (a sweep would race with Acquire/Release and the
+// memory is negligible).
+type TurnGate struct {
+	mu      sync.Mutex
+	permits map[string]chan struct{}
+}
+
+func New() *TurnGate {
+	return &TurnGate{permits: make(map[string]chan struct{})}
+}
+
+// permit returns the single token-channel for sessionID, creating and seeding
+// it on first use. Creation is guarded so two concurrent first-callers for the
+// same id share one channel.
+func (g *TurnGate) permit(sessionID string) chan struct{} {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	ch, ok := g.permits[sessionID]
+	if !ok {
+		ch = make(chan struct{}, 1)
+		ch <- struct{}{}
+		g.permits[sessionID] = ch
+	}
+	return ch
+}
+
+// Acquire takes the session's permit. With wait <= 0 it is non-blocking
+// (returns false immediately if a turn is active). With wait > 0 it blocks up
+// to wait for the permit, returning false on timeout. Every true return MUST
+// be paired with exactly one Release.
+func (g *TurnGate) Acquire(sessionID string, wait time.Duration) bool {
+	ch := g.permit(sessionID)
+	if wait <= 0 {
+		select {
+		case <-ch:
+			return true
+		default:
+			return false
+		}
+	}
+	t := time.NewTimer(wait)
+	defer t.Stop()
+	select {
+	case <-ch:
+		return true
+	case <-t.C:
+		return false
+	}
+}
+
+// Release returns the session's permit. Idempotent: a Release with no matching
+// Acquire (or a double Release) is a no-op rather than a blocking send.
+func (g *TurnGate) Release(sessionID string) {
+	ch := g.permit(sessionID)
+	select {
+	case ch <- struct{}{}:
+	default:
+	}
+}
--- a/internal/nomos/turngate/turngate_test.go
+++ b/internal/nomos/turngate/turngate_test.go
@@ -0,0 +1,114 @@
+package turngate
+
+import (
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestTurnGate_NonBlockingSkipsWhenBusy(t *testing.T) {
+	g := New()
+	if !g.Acquire("s1", 0) {
+		t.Fatal("first non-blocking Acquire should succeed on a free session")
+	}
+	// A second non-blocking Acquire (a background resume) must skip, not queue.
+	if g.Acquire("s1", 0) {
+		t.Fatal("second non-blocking Acquire should fail while a turn is active")
+	}
+	// A different session is independent.
+	if !g.Acquire("s2", 0) {
+		t.Fatal("Acquire on a different session should succeed")
+	}
+	g.Release("s2")
+	g.Release("s1")
+	// After Release, the session is free again.
+	if !g.Acquire("s1", 0) {
+		t.Fatal("Acquire should succeed again after Release")
+	}
+	g.Release("s1")
+}
+
+func TestTurnGate_BlockingAcquireWaitsForRelease(t *testing.T) {
+	g := New()
+	if !g.Acquire("s1", 0) {
+		t.Fatal("first Acquire should succeed")
+	}
+
+	got := make(chan bool, 1)
+	go func() { got <- g.Acquire("s1", 2*time.Second) }()
+
+	select {
+	case <-got:
+		t.Fatal("blocking Acquire should wait, not return before Release")
+	case <-time.After(50 * time.Millisecond):
+		// expected: still waiting
+	}
+
+	g.Release("s1")
+	select {
+	case ok := <-got:
+		if !ok {
+			t.Fatal("blocking Acquire should succeed after Release")
+		}
+	case <-time.After(time.Second):
+		t.Fatal("blocking Acquire did not return after Release")
+	}
+	g.Release("s1")
+}
+
+func TestTurnGate_BlockingAcquireTimesOut(t *testing.T) {
+	g := New()
+	g.Acquire("s1", 0) // hold the permit
+
+	start := time.Now()
+	if g.Acquire("s1", 60*time.Millisecond) {
+		t.Fatal("Acquire should time out while permit is held")
+	}
+	if elapsed := time.Since(start); elapsed < 50*time.Millisecond {
+		t.Fatalf("Acquire returned too fast (%v); expected to wait ~60ms", elapsed)
+	}
+	g.Release("s1")
+}
+
+// TestTurnGate_SingleFlightConcurrent is the core F1 guarantee: many concurrent
+// background acquirers on the SAME session, exactly one runs at a time. This is
+// the property that prevents two turns interleaving tool calls.
+func TestTurnGate_SingleFlightConcurrent(t *testing.T) {
+	g := New()
+	const n = 50
+	var inFlight, maxInFlight int64
+	var runs int64
+	var wg sync.WaitGroup
+	wg.Add(n)
+	start := make(chan struct{})
+	for i := 0; i < n; i++ {
+		go func() {
+			defer wg.Done()
+			<-start
+			if !g.Acquire("shared", 0) { // background-style: skip if busy
+				return
+			}
+			defer g.Release("shared")
+			cur := atomic.AddInt64(&inFlight, 1)
+			for {
+				m := atomic.LoadInt64(&maxInFlight)
+				if cur <= m || atomic.CompareAndSwapInt64(&maxInFlight, m, cur) {
+					break
+				}
+			}
+			atomic.AddInt64(&runs, 1)
+			time.Sleep(2 * time.Millisecond)
+			atomic.AddInt64(&inFlight, -1)
+		}()
+	}
+	close(start)
+	wg.Wait()
+
+	if maxInFlight != 1 {
+		t.Fatalf("max in-flight turns = %d, want 1 (turns must not overlap)", maxInFlight)
+	}
+	if runs == 0 {
+		t.Fatal("expected at least one turn to run")
+	}
+}