feat: sub-agent intelligence quality — headline tail-keep + bounded stall detection (T2) (#242)

* feat: sub-agent headline tail-keep + bounded stall detection (T2 intelligence quality)

Headline channel (B1):
- extractSummaryInfo keeps the TAIL of over-cap answers (leading …):
  verdicts, recommendations, and next actions live at the end of a
  report — the old head cut dropped exactly the conclusions
- truncateTailWithLen helper; original rune count and summary_truncated
  semantics unchanged; delegate_tasks description states the new contract
- legacy head-keep pins updated to the tail-keep contract

Stall detection (B2):
- hints escalate instead of resetting: per-fingerprint milestone doubles
  (3→6→12→…), later hints marked 'again' — a hint-resistant loop gets
  progressively fewer interruptions instead of 27 identical hints
- bg_status/bg_output polling is bounded rather than exempt: 3× threshold
  (9 identical polls) fires a poll-specific hint (check bg_list, read
  bg_output, move on) — a pinned dead job id can no longer burn the
  whole iteration budget silently

Pinned RED-first in internal/loop/stall_escalation_test.go and
cmd/odek/headline_tail_test.go. internal/loop and full cmd/odek green
under -race.

* fix: close review findings — partial-marker detection under tail-keep, milestone lifecycle

- PartialSummaryReason matches budget markers with Contains instead of
  HasPrefix: tail-kept over-cap summaries lose their leading bytes, so a
  budget-killed run was misclassified as success (HIGH, judge round 2)
- toolStallMilestones reset at run start and dropped alongside
  fingerprints on error/eviction — long-lived engines no longer inherit
  escalated milestones across runs (MAJOR, judge round 1)
- bg-poll hints use the milestone mechanism with an accurate poll count
  instead of doubling the counter (reported 18 polls after 9)

internal/loop and full cmd/odek green under -race.

Author: jkyberneees

cmd/odek/headline_tail_test.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/BackendStack21/odek/internal/session"
+)
+
+// ── B1: sub-agent headline keeps the TAIL ────────────────────────────────
+//
+// The old head-keep truncation chopped exactly the part that matters: a
+// verdict/recommendation lives at the END of a report, so a 2048-rune
+// head-cut dropped conclusions while keeping boilerplate. The headline cut
+// must keep the tail (verdicts, file lists, next actions) with a leading
+// ellipsis marking the trim.
+
+func TestExtractSummaryInfo_KeepsTail(t *testing.T) {
+	verdict := "VERDICT: MERGE — the patch is correct and complete."
+	filler := strings.Repeat("Analysis prose. ", 200) // > 2048 runes
+	content := filler + "\n\n" + verdict
+
+	msgs := []session.Message{{Role: "assistant", Content: content}}
+	got, total, truncated := extractSummaryInfo(msgs)
+
+	if !truncated {
+		t.Fatal("expected truncated=true for over-cap content")
+	}
+	if total != len([]rune(content)) {
+		t.Errorf("total rune count = %d, want %d", total, len([]rune(content)))
+	}
+	if !strings.Contains(got, verdict) {
+		t.Errorf("tail-keep headline lost the verdict — head-keep truncation drops conclusions:\n%.300s", got)
+	}
+	if !strings.HasPrefix(got, "…") {
+		t.Errorf("tail-keep headline must mark the cut with a LEADING ellipsis, got: %.50s", got)
+	}
+	runes := len([]rune(got))
+	if runes > subagentHeadlineMaxRunes+1 { // +1 for the ellipsis rune
+		t.Errorf("headline = %d runes, want ≤ %d (+ellipsis)", runes, subagentHeadlineMaxRunes)
+	}
+}
+
+func TestExtractSummaryInfo_ShortContentUntouched(t *testing.T) {
+	msgs := []session.Message{{Role: "assistant", Content: "short answer"}}
+	got, total, truncated := extractSummaryInfo(msgs)
+	if truncated || total != 12 || got != "short answer" {
+		t.Errorf("short content must pass through untouched, got %q (total=%d, truncated=%v)", got, total, truncated)
+	}
+}
+
+// The parent-facing description must describe the new semantics.
+func TestSubagentDescription_TailKeepSemantics(t *testing.T) {
+	desc := (&delegateTasksTool{}).Description()
+	if strings.Contains(desc, "a trailing … means it was cut") {
+		t.Error("description still claims head-keep semantics ('a trailing … means it was cut')")
+	}
+	if !strings.Contains(desc, "leading …") {
+		t.Error("description must state the tail-keep contract ('a leading … marks the cut; the end of the answer is kept')")
+	}
+}

cmd/odek/subagent.go

@@ -1364,12 +1364,15 @@ const subagentHeadlineMaxRunes = 2048
 
 // extractSummaryInfo returns the child's final answer cut to the headline
 // cap, the ORIGINAL rune count, and whether it was cut (C — the parent
-// render turns this into a visible truncation marker). The bulk channel is
-// the artifact protocol; the headline is a status summary.
+// render turns this into a visible truncation marker). The cut keeps the
+// TAIL of the answer with a leading ellipsis: verdicts, recommendations,
+// and next actions live at the end of a report — a head cut dropped
+// exactly the conclusions. The bulk channel is the artifact protocol; the
+// headline is a status summary.
 func extractSummaryInfo(messages []session.Message) (string, int, bool) {
 	for i := len(messages) - 1; i >= 0; i-- {
 		if messages[i].Role == "assistant" && messages[i].Content != "" {
-			s, total := truncateWithLen(messages[i].Content, subagentHeadlineMaxRunes)
+			s, total := truncateTailWithLen(messages[i].Content, subagentHeadlineMaxRunes)
 			return s, total, total > subagentHeadlineMaxRunes
 		}
 	}
@@ -1394,6 +1397,20 @@ func truncateWithLen(s string, n int) (string, int) {
 	return string(runes[:n]) + "…", len(runes)
 }
 
+// truncateTailWithLen keeps the LAST n runes of s (prepending "…") and
+// reports the ORIGINAL rune count. Used by the sub-agent headline: the end
+// of a report carries the verdict; the start is boilerplate.
+func truncateTailWithLen(s string, n int) (string, int) {
+	runes := []rune(s)
+	if n <= 0 {
+		return "…", len(runes)
+	}
+	if len(runes) <= n {
+		return s, len(runes)
+	}
+	return "…" + string(runes[len(runes)-n:]), len(runes)
+}
+
 func extractFilesChanged(messages []session.Message) []string {
 	var files []string
 	seen := make(map[string]bool)

cmd/odek/subagent_contract_test.go

@@ -823,7 +823,8 @@ func TestExtractSummary_AssistantWithToolCallsOnly(t *testing.T) {
 }
 
 // Updated for the headline cap (SUBAGENT_RESULT_ARTIFACTS_PLAN.md):
-// extractSummary now carries 2048 runes instead of the old 500-rune cut.
+// extractSummary carries 2048 runes; since the tail-keep change the cut
+// preserves the END of the answer (verdicts) with a leading ellipsis.
 func TestExtractSummary_TruncatesLongOutput(t *testing.T) {
 	longContent := strings.Repeat("a", 3000)
 	msgs := []session.Message{
@@ -833,8 +834,11 @@ func TestExtractSummary_TruncatesLongOutput(t *testing.T) {
 	if len([]rune(summary)) > subagentHeadlineMaxRunes+1 { // cap + ellipsis
 		t.Errorf("extractSummary too long: %d runes (max %d)", len([]rune(summary)), subagentHeadlineMaxRunes+1)
 	}
-	if !strings.HasSuffix(summary, "…") {
-		t.Errorf("truncated summary should end with '…', got: %q", summary)
+	if !strings.HasPrefix(summary, "…") {
+		t.Errorf("truncated summary should start with '…' (tail-keep), got: %q", summary)
+	}
+	if !strings.HasSuffix(summary, longContent[len(longContent)-10:]) {
+		t.Errorf("tail-keep summary must preserve the answer END, got: %q", summary)
 	}
 }
 

cmd/odek/subagent_delivery_test.go

@@ -32,7 +32,7 @@ func TestDelegateTasksDescription_ArtifactChannel(t *testing.T) {
 		"32 KB",
 		"artifact_read(id)",
 		"flat file in your artifact dir",
-		"trailing … means it was cut",
+		"leading … marks the cut",
 	} {
 		if !strings.Contains(desc, want) {
 			t.Errorf("Description() missing %q — the parent LLM cannot learn the artifact protocol", want)

cmd/odek/subagent_result_render_test.go

@@ -28,8 +28,11 @@ func TestExtractSummary_HeadlineCap(t *testing.T) {
 	if n := len([]rune(got)); n != subagentHeadlineMaxRunes+1 { // cap + ellipsis
 		t.Errorf("headline cap: got %d runes, want %d (cap + ellipsis)", n, subagentHeadlineMaxRunes+1)
 	}
-	if !strings.HasPrefix(got, long[:subagentHeadlineMaxRunes]) {
-		t.Error("headline must preserve the answer prefix")
+	if !strings.HasPrefix(got, "…") {
+		t.Error("tail-keep headline must mark the cut with a leading ellipsis")
+	}
+	if !strings.HasSuffix(got, long[len(long)-subagentHeadlineMaxRunes:]) {
+		t.Error("tail-keep headline must preserve the answer END")
 	}
 }
 

cmd/odek/subagent_tool.go

@@ -207,7 +207,7 @@ func (t *delegateTasksTool) Description() string {
 	return `Spawn sub-agent processes for independent sub-tasks. Each child has a fresh context — put everything it needs in goal/context. Children never prompt for approvals (denials are listed). Trust never increases downward. Depth is capped.
 
 Result delivery — two channels per sub-agent:
-- Headline: the sub-agent's final answer, capped at ~2000 characters. Treat it as a status summary; a trailing … means it was cut.
+- Headline: the sub-agent's final answer, capped at ~2000 characters keeping the END (verdicts, next actions) — a leading … marks the cut.
 - Artifacts: validated file deliverables (id, type, size, one-line summary). text/* ≤32 KB is inlined; fetch the rest with artifact_read(id). For artifact-heavy work, set guidance to write a flat file in your artifact dir and keep the final answer to a short headline.`
 }
 

internal/loop/budget_hints.go

@@ -242,11 +242,14 @@ func intBudgetBand(max, remaining int64, exhausted bool, t int, label string) st
 // set status/partial_reason without string-matching the markers themselves.
 func PartialSummaryReason(final string) (string, bool) {
 	switch {
-	case strings.HasPrefix(final, budgetSummaryMarker):
+	// Contains, not HasPrefix: the sub-agent headline is tail-kept, so an
+	// over-cap partial summary loses its leading bytes — the marker must
+	// still be detected anywhere in the text (markers are unique sentinels).
+	case strings.Contains(final, budgetSummaryMarker):
 		return "iteration_budget", true
-	case strings.HasPrefix(final, execBudgetSummaryMarker):
+	case strings.Contains(final, execBudgetSummaryMarker):
 		return "execution_budget", true
-	case strings.HasPrefix(final, timeBudgetSummaryMarker):
+	case strings.Contains(final, timeBudgetSummaryMarker):
 		return "time_budget", true
 	}
 	return "", false

internal/loop/loop.go

@@ -50,8 +50,6 @@ func formatLongToolRuntime(ms int64) string {
 	return fmt.Sprintf("%dm%02ds", sec/60, sec%60)
 }
 
-// dropStallFingerprints removes stall-map entries for one tool name so a
-// failing sibling cannot wipe a looping successful call's streak.
 func dropStallFingerprints(m map[string]int, toolName string) {
 	if m == nil {
 		return
@@ -64,6 +62,21 @@ func dropStallFingerprints(m map[string]int, toolName string) {
 	}
 }
 
+// dropStallMilestones mirrors dropStallFingerprints for the milestone map,
+// so a reset fingerprint re-arms at the base threshold instead of inheriting
+// an escalated milestone from earlier runs.
+func dropStallMilestones(m map[string]int, toolName string) {
+	if m == nil {
+		return
+	}
+	prefix := toolName + "\x00"
+	for k := range m {
+		if strings.HasPrefix(k, prefix) {
+			delete(m, k)
+		}
+	}
+}
+
 // evictLowestStallCount drops one fingerprint with the lowest repeat count
 // (key tie-break) so the 64-entry bound does not wipe the whole map.
 func evictLowestStallCount(m map[string]int) {
@@ -549,9 +562,10 @@ type Engine struct {
 	compactMu             sync.Mutex
 	digestGen             uint64
 	digestCancel          context.CancelFunc
-	digestInFlight        bool // a summarizer side call is running; new trims debounce instead of canceling
-	digestDirty           bool // drops arrived while the side call was in flight; refetch after it lands
-	digestCallStart       int  // pendingDropped index where the in-flight call's input begins
+	digestInFlight        bool           // a summarizer side call is running; new trims debounce instead of canceling
+	digestDirty           bool           // drops arrived while the side call was in flight; refetch after it lands
+	digestCallStart       int            // pendingDropped index where the in-flight call's input begins
+	toolStallMilestones   map[string]int // next stall-hint threshold per fingerprint (doubles per fire)
 	pendingDropped        []session.Message
 	pendingDroppedCovered int // prefix length of pendingDropped the ready digest actually summarized
 	pendingDigest         string
@@ -2493,6 +2507,7 @@ func (e *Engine) runLoop(ctx context.Context, in []session.Message) (answer stri
 	e.maxConsecutiveToolErrors = make(map[string]int)
 	// Reset per-session repeated-call (stall) tracking
 	e.toolRepeatCounts = nil
+	e.toolStallMilestones = nil
 	// Reset the run's mutation ledger and completion-nudge state.
 	e.externalChargeMu.Lock()
 	e.externalReserved = 0
@@ -3508,6 +3523,9 @@ func (e *Engine) runLoop(ctx context.Context, in []session.Message) (answer stri
 		const (
 			errThreshold   = 3 // consecutive errors before intervention
 			stallThreshold = 3 // consecutive identical successful calls before intervention
+			// bgPollStallThreshold: polling is legitimate (results change), so
+			// poll fingerprints get a 3× raised threshold before the hint.
+			bgPollStallThreshold = 3 * stallThreshold
 		)
 		var corrections []string
 		for idx, tc := range result.ToolCalls {
@@ -3527,6 +3545,7 @@ func (e *Engine) runLoop(ctx context.Context, in []session.Message) (answer stri
 				// this tool's fingerprints only so a looping sibling still
 				// accumulates toward the stall threshold.
 				dropStallFingerprints(e.toolRepeatCounts, toolName)
+				dropStallMilestones(e.toolStallMilestones, toolName)
 			} else {
 				e.maxConsecutiveToolErrors[toolName] = 0
 
@@ -3540,22 +3559,56 @@ func (e *Engine) runLoop(ctx context.Context, in []session.Message) (answer stri
 				// polling exists.
 				fp := toolName + "\x00" + tc.Function.Arguments
 				if isBGPollTool(toolName) {
-					// Background-job polling tools: leave the counters
-					// untouched — identical polling is normal, AND
-					// interleaved ordinary-call repetition must still
-					// count toward the threshold.
+					// Background-job polling tools: legitimate repetition, but
+					// BOUNDED — after 3× the normal threshold of identical
+					// polls (a pinned dead job id), fire the same hint. Count
+					// in the same fingerprint map with a raised milestone.
+					if e.toolRepeatCounts == nil {
+						e.toolRepeatCounts = make(map[string]int)
+					}
+					if _, ok := e.toolRepeatCounts[fp]; !ok && len(e.toolRepeatCounts) >= 64 {
+						evictLowestStallCount(e.toolRepeatCounts)
+						delete(e.toolStallMilestones, fp)
+					}
+					e.toolRepeatCounts[fp]++
+					milestone, mok := e.toolStallMilestones[fp]
+					if !mok {
+						milestone = bgPollStallThreshold
+					}
+					if e.toolRepeatCounts[fp] >= milestone {
+						pm := e.toolRepeatCounts[fp]
+						corrections = append(corrections, fmt.Sprintf(
+							"⚠️ You polled %q with identical arguments %d times with no state change%s. The job may be stuck or the id wrong: check bg_list for valid ids, read bg_output for the job's progress, or move on.",
+							toolName, pm, againSuffix(mok)))
+						e.emitSignal(SignalEvent{
+							Type:   "tool_recovery",
+							Tool:   toolName,
+							Detail: fmt.Sprintf("repeated identical poll (%dx%s)", pm, againDetail(mok)),
+						})
+						// Escalate via milestone, keep the count accurate.
+						if e.toolStallMilestones == nil {
+							e.toolStallMilestones = make(map[string]int)
+						}
+						e.toolStallMilestones[fp] = milestone * 2
+					}
 				} else {
 					if e.toolRepeatCounts == nil {
 						e.toolRepeatCounts = make(map[string]int)
 					}
 					if _, ok := e.toolRepeatCounts[fp]; !ok && len(e.toolRepeatCounts) >= 64 {
 						evictLowestStallCount(e.toolRepeatCounts)
+						delete(e.toolStallMilestones, fp)
 					}
 					e.toolRepeatCounts[fp]++
-					if e.toolRepeatCounts[fp] >= stallThreshold {
+					milestone, ok := e.toolStallMilestones[fp]
+					if !ok {
+						milestone = stallThreshold
+					}
+					if e.toolRepeatCounts[fp] >= milestone {
+						warned := e.toolRepeatCounts[fp] >= stallThreshold*2
 						correction := fmt.Sprintf(
-							"⚠️ You called %q with identical arguments %d times (possibly interleaved with other calls) with no new information. Change approach: vary the arguments, switch to a different tool, or move on to the next step — repeating the same call will not produce a different result.",
-							toolName, e.toolRepeatCounts[fp])
+							"⚠️ You called %q with identical arguments %d times (possibly interleaved with other calls) with no new information%s. Change approach: vary the arguments, switch to a different tool, or move on to the next step — repeating the same call will not produce a different result.",
+							toolName, e.toolRepeatCounts[fp], againSuffix(warned))
 						if e.planStore != nil {
 							if state, ok := e.planStore.Snapshot(); ok {
 								cls, _ := classifyToolCall(toolName, tc.Function.Arguments)
@@ -3578,12 +3631,16 @@ func (e *Engine) runLoop(ctx context.Context, in []session.Message) (answer stri
 						e.emitSignal(SignalEvent{
 							Type:   "tool_recovery",
 							Tool:   toolName,
-							Detail: fmt.Sprintf("repeated identical call (%dx, possibly interleaved)", e.toolRepeatCounts[fp]),
+							Detail: fmt.Sprintf("repeated identical call (%dx%s, possibly interleaved)", e.toolRepeatCounts[fp], againDetail(warned)),
 						})
-						// Reset this fingerprint's counter after injecting
-						// the suggestion (same semantics as the error-recovery
-						// counter).
-						e.toolRepeatCounts[fp] = 0
+						// Escalate, don't reset: the hint interval doubles
+						// (3 → 6 → 12 → …) so a hint-resistant loop gets
+						// progressively fewer interruptions while later hints
+						// say "again" — the loop is persistent, not correcting.
+						if e.toolStallMilestones == nil {
+							e.toolStallMilestones = make(map[string]int)
+						}
+						e.toolStallMilestones[fp] = milestone * 2
 					}
 				}
 			}
@@ -3795,12 +3852,34 @@ func (e *Engine) appendRemainingPlan(ctx context.Context, messages []session.Mes
 }
 
 // isBGPollTool reports whether the tool is a read-only background-job
-// polling tool exempt from stall detection (identical arguments are the
-// normal polling pattern; the result changes between calls).
+// polling tool. Poll fingerprints get an elevated stall threshold rather
+// than a total exemption (a pinned dead job id must not poll forever).
 func isBGPollTool(name string) bool {
 	return name == "bg_status" || name == "bg_output"
 }
 
+// isPow2 reports whether n is a positive power of two.
+func isPow2(n int) bool {
+	return n > 0 && n&(n-1) == 0
+}
+
+// againSuffix marks an escalated (repeat) stall hint so the model can tell
+// it apart from the first one — the loop is persistent, not self-correcting.
+func againSuffix(repeat bool) string {
+	if repeat {
+		return " again"
+	}
+	return ""
+}
+
+// againDetail is the signal-detail counterpart of againSuffix.
+func againDetail(repeat bool) string {
+	if repeat {
+		return ", again"
+	}
+	return ""
+}
+
 // lastUserMessage returns the content of the most recent user message.
 func lastUserMessage(messages []session.Message) string {
 	for i := len(messages) - 1; i >= 0; i-- {