Review a long record within a bound sized to it, and let a proposal waiting on its author leave the knowledge base healthy (hq issue 508)

A judgement over one bus call's 30 seconds is collected by its ticket from
claude-code, so an eleven-clause record can be reviewed; a proposal out of
review tries is told to the operator, not raised as the module's fault, so
it no longer holds the module's own rollouts.

modules/mesh-knowledge/cmd/mesh-knowledge/main.go

@@ -202,25 +202,76 @@ func busReserver(kind, title string) (int, error) {
 }
 
 // busJudgement asks the agent module on this node for one judgement (ADR 0278).
-func busJudgement(node string) Judgement {
+func busJudgement(node string) Judgement { return judgementOver(stdio.Ask, node) }
+
+// The bound a judgement asks scales with its question (novox/hq issue 508): ADR 0297, eleven clauses and eleven
+// links, was never reviewed within the agent module's 25 seconds, while short records took 14 to 25. Each KiB of
+// question adds JudgePerKiB to JudgeFloor, up to MostJudgeWithin, which the agent module takes at most. A sized
+// bound was chosen over asking clause by clause: every judgement pays the agent's start, which alone is most of
+// those 14 to 25 seconds, so a dozen clause-sized judgements would each risk the same 25 seconds, take minutes
+// together, and still need a judgement of the whole record for what binds its clauses together.
+const (
+	JudgeFloor      = 25 * time.Second
+	JudgePerKiB     = 2 * time.Second
+	MostJudgeWithin = 120 * time.Second
+)
+
+// JudgeWithin is the bound a judgement of this question asks.
+func JudgeWithin(question string) time.Duration {
+	return min(JudgeFloor+time.Duration(len(question)>>10)*JudgePerKiB, MostJudgeWithin)
+}
+
+// judgementOver asks the agent module through ask. A bound past one bus call's 30 seconds is answered pending with
+// a ticket when the judgement is not done in the call, and collected from the node that holds it with
+// claude_code_judged (novox/hq issue 508).
+func judgementOver(ask func(key string, body any) (json.RawMessage, error), node string) Judgement {
 	return func(question string, schema map[string]any, model string) (json.RawMessage, string, error) {
 		key := "claude-code.claude_code_judge"
 		if node != "" {
 			key += "@" + node
 		}
-		raw, err := stdio.Ask(key, map[string]any{"question": question, "schema": schema, "model": model})
-		if err != nil {
-			return nil, "", err
+		within := JudgeWithin(question)
+		body := map[string]any{"question": question, "schema": schema, "model": model}
+		if within > JudgeFloor {
+			body["within"] = int(within / time.Second)
 		}
-		var out struct {
-			Answer json.RawMessage `json:"answer"`
-			Model  string          `json:"model"`
-			Node   string          `json:"node"`
+		raw, err := ask(key, body)
+		if err != nil && body["within"] != nil && strings.Contains(err.Error(), "not within") {
+			// An agent module from before issue 508 takes no within: asked again without it, under its own bound.
+			delete(body, "within")
+			raw, err = ask(key, body)
 		}
-		if err := json.Unmarshal(raw, &out); err != nil || len(out.Answer) == 0 {
-			return nil, "", fmt.Errorf("the agent module's answer is not a judgement: %.200s", raw)
+		// Past the judgement's bound the agent module ends it and says so; the deadline only guards against a
+		// module that answers pending for ever.
+		deadline := time.Now().Add(within + time.Minute)
+		for {
+			if err != nil {
+				return nil, "", err
+			}
+			var out struct {
+				Answer  json.RawMessage `json:"answer"`
+				Model   string          `json:"model"`
+				Node    string          `json:"node"`
+				Ticket  string          `json:"ticket"`
+				Pending bool            `json:"pending"`
+			}
+			if err := json.Unmarshal(raw, &out); err != nil {
+				return nil, "", fmt.Errorf("the agent module's answer is not a judgement: %.200s", raw)
+			}
+			if !out.Pending {
+				if len(out.Answer) == 0 {
+					return nil, "", fmt.Errorf("the agent module's answer is not a judgement: %.200s", raw)
+				}
+				return out.Answer, fmt.Sprintf("the agent on %s (%s)", out.Node, out.Model), nil
+			}
+			if out.Ticket == "" || out.Node == "" {
+				return nil, "", fmt.Errorf("the agent module answered pending with no ticket or node: %.200s", raw)
+			}
+			if time.Now().After(deadline) {
+				return nil, "", fmt.Errorf("the agent on %s still had not answered %s after its bound of %s", out.Node, out.Ticket, within)
+			}
+			raw, err = ask("claude-code.claude_code_judged@"+out.Node, map[string]any{"ticket": out.Ticket})
 		}
-		return out.Answer, fmt.Sprintf("the agent on %s (%s)", out.Node, out.Model), nil
 	}
 }
 
@@ -501,9 +552,10 @@ type HealthAnswer struct {
 	At      time.Time `json:"at,omitempty"`
 }
 
-// Health is how the knowledge base is: unhealthy when its database cannot serve, when a rule that judges the
-// whole record set fails, or when a proposed record ran out of review tries — the mesh raises a condition naming
-// the rule, the records, or the records not reviewed.
+// Health is whether the knowledge base works: unhealthy when its database cannot serve, or when a rule that judges
+// the whole record set fails — the mesh raises a condition naming the rule and the records. A proposal that ran out
+// of review tries waits on its author, not on the module: it is told to its author and the operator, and named
+// here, but leaves the module healthy, so it never holds the module's own rollouts (novox/hq issue 508).
 func (k *KB) Health(ready Healther) HealthAnswer {
 	ctx, cancel := context.WithTimeout(context.Background(), 8*time.Second)
 	defer cancel()
@@ -525,33 +577,38 @@ func (k *KB) Health(ready Healther) HealthAnswer {
 	if err != nil {
 		return HealthAnswer{State: "unhealthy", Why: "the records cannot be read: " + err.Error()}
 	}
-	unreviewed := Unreviewed(all)
-	if len(findings)+len(unreviewed) > 0 {
-		var parts []string
-		if len(unreviewed) > 0 {
-			if len(unreviewed) > 8 {
-				unreviewed = append(unreviewed[:8], fmt.Sprintf("and %d more", len(unreviewed)-8))
-			}
-			parts = append(parts, fmt.Sprintf("%d proposed record(s) could not be reviewed in %d tries and wait for their authors to propose them again: %s",
-				len(Unreviewed(all)), MostReviewTries, strings.Join(unreviewed, "; ")))
+	waiting := ""
+	if unreviewed := Unreviewed(all); len(unreviewed) > 0 {
+		n := len(unreviewed)
+		if n > 8 {
+			unreviewed = append(unreviewed[:8], fmt.Sprintf("and %d more", n-8))
 		}
-		if len(says) > 0 {
-			if len(says) > 8 {
-				says = append(says[:8], fmt.Sprintf("and %d more", len(says)-8))
-			}
-			parts = append(parts, fmt.Sprintf("%d rule(s) that judge the whole record set fail: %s", len(findings), strings.Join(says, "; ")))
-		}
-		return HealthAnswer{State: "unhealthy", Why: strings.Join(parts, ". ")}
+		waiting = fmt.Sprintf("%d proposed record(s) could not be reviewed in %d tries and wait for their authors to propose them again: %s",
+			n, MostReviewTries, strings.Join(unreviewed, "; "))
 	}
-	return HealthAnswer{State: "healthy", Healthy: true, Why: "the database serves, every rule that judges the whole record set holds, and no proposal ran out of review tries"}
+	if len(says) > 0 {
+		if len(says) > 8 {
+			says = append(says[:8], fmt.Sprintf("and %d more", len(says)-8))
+		}
+		why := fmt.Sprintf("%d rule(s) that judge the whole record set fail: %s", len(findings), strings.Join(says, "; "))
+		if waiting != "" {
+			why += ". " + waiting
+		}
+		return HealthAnswer{State: "unhealthy", Why: why}
+	}
+	why := "the database serves and every rule that judges the whole record set holds"
+	if waiting != "" {
+		why += "; " + waiting
+	}
+	return HealthAnswer{State: "healthy", Healthy: true, Why: why}
 }
 
 func healthTool(status string, now func() time.Time) stdio.Tool {
 	return stdio.Tool{Name: HealthTool,
 		Description: "How the knowledge base is, as its watch last saw it: healthy when its database serves this version and every " +
 			"rule that judges the whole record set holds; unhealthy otherwise, naming the rule and the records — a decision accepted " +
-			"that nothing cites, a supersession or a change said on one end only, a record extending a superseded one — or when a " +
-			"proposed record ran out of review tries, naming it.",
+			"that nothing cites, a supersession or a change said on one end only, a record extending a superseded one. A " +
+			"proposed record that ran out of review tries is named but leaves it healthy: it waits on its author (novox/hq issue 508).",
 		Run: func(map[string]any) (any, error) { return ReadStatus(status, now()), nil }}
 }