Merge lane-go: titles, verdicts, human stage, line result format, stale-client guard

Integrates nine commits of reviewed work from the lane-go branch after the
automated resolver failed on this merge five times (each attempt dying on the
malformed-result defect whose fix is contained in this same merge).

Integration decisions:
- Search: kept main's shipped design (Store.Search + SearchResponse.Results) and
  dropped lane-go's parallel, older attempt (an unused Message.Matches field, an
  absent runs.search, and two partial TUI plumbing blocks). lane-go itself did not
  compile: protocol.SearchMatch was undefined and model.go referenced searchNav,
  requestSearch and applyRunNav, which exist nowhere. Those partial TUI blocks are
  removed; the queued TUI omni-search item will implement the surface properly on
  main's design.
- Both sides' additions are kept where they are independent: run titles and
  provenance, the human decision stage and its CLI/TUI surface, the derived stage
  verdict, the stale-client guard, the line-oriented result format, and main's
  search command.
- The search key's help label is now "/ omni search"; the two tests asserting the
  old label are updated rather than the label reverted.
- docs/cli.md and the packaged operations reference carry both sides' text.

Verified: go build ./... , go vet ./... and the full go test ./... suite pass.
This commit is contained in:
2026-10-16 22:21:43 +01:00
669 changed files with 7205 additions and 276 deletions
+60
View File
@@ -0,0 +1,60 @@
package protocol
import (
"encoding/json"
"reflect"
"sort"
"strings"
"sync"
)
// ProtocolVersion is the integer wire protocol this build speaks. Ordering
// between peers compares this integer; build strings are for naming only and are
// never parsed or sorted to infer ordering.
const ProtocolVersion = 1
// MaxSupportedProtocol is the newest server protocol this client can interpret.
// A server reporting a higher value is refused rather than silently misread.
const MaxSupportedProtocol = ProtocolVersion
var (
knownFieldsOnce sync.Once
knownFields map[string]struct{}
)
// KnownFields returns the set of top-level JSON keys protocol.Message models,
// derived once from the struct tags and cached. The map is read-only.
func KnownFields() map[string]struct{} {
knownFieldsOnce.Do(func() {
knownFields = map[string]struct{}{}
message := reflect.TypeOf(Message{})
for index := 0; index < message.NumField(); index++ {
name := strings.Split(message.Field(index).Tag.Get("json"), ",")[0]
if name == "" || name == "-" {
continue
}
knownFields[name] = struct{}{}
}
})
return knownFields
}
// UnknownFields returns the sorted top-level JSON keys in data that protocol.Message
// does not model. It performs one bounded map decode plus O(1) set lookups, so a
// forward-compatible frame is never a per-frame reflection walk. A frame that is
// not a JSON object (or cannot be parsed) reports no unknown fields.
func UnknownFields(data []byte) []string {
var raw map[string]json.RawMessage
if err := json.Unmarshal(data, &raw); err != nil {
return nil
}
known := KnownFields()
var unknown []string
for key := range raw {
if _, ok := known[key]; !ok {
unknown = append(unknown, key)
}
}
sort.Strings(unknown)
return unknown
}
+52
View File
@@ -0,0 +1,52 @@
package protocol
import (
"fmt"
"reflect"
"testing"
)
func TestUnknownFieldsReportsOnlyUnmodeledSortedKeys(t *testing.T) {
if got := UnknownFields([]byte(`{"type":"pong"}`)); got != nil {
t.Fatalf("fully modeled frame reported %v", got)
}
got := UnknownFields([]byte(`{"type":"pong","zzz":1,"aaa":2}`))
if !reflect.DeepEqual(got, []string{"aaa", "zzz"}) {
t.Fatalf("unknown fields = %v, want sorted [aaa zzz]", got)
}
}
func TestUnknownFieldsIgnoresMalformedAndNonObjectFrames(t *testing.T) {
for _, data := range []string{
`not json`,
`[1,2,3]`,
`"a string"`,
`42`,
`null`,
} {
if got := UnknownFields([]byte(data)); got != nil {
t.Fatalf("frame %q reported unknown fields %v", data, got)
}
}
}
func TestKnownFieldsCachesTheModeledKeySet(t *testing.T) {
first := KnownFields()
second := KnownFields()
if len(first) == 0 {
t.Fatal("known field set is empty")
}
if _, ok := first["type"]; !ok {
t.Fatal("known field set is missing the modeled type key")
}
if _, ok := first["build"]; !ok {
t.Fatal("known field set is missing the modeled build key")
}
if _, ok := first["protocol"]; !ok {
t.Fatal("known field set is missing the modeled protocol key")
}
// The sync.Once must return the same cached map on every call.
if fmt.Sprintf("%p", first) != fmt.Sprintf("%p", second) {
t.Fatal("KnownFields re-derived the set instead of using the cache")
}
}
+13 -1
View File
@@ -102,10 +102,16 @@ type PipelineSummary struct {
UpdatedAt string `json:"updated_at"`
}
// Message is the JSON envelope shared by the server and client.
// Message is the JSON envelope shared by the server and client. It also carries
// the omni-search request/response: a client sends Type "search" with an ID, the
// Query text, an optional Kind type filter and an optional Limit, and the server
// replies with Type "search_results", the echoed ID and ranked Matches. Every
// search fields are optional so older peers ignore them. See search.go for the
// kind constants and wire-shape detail.
type Message struct {
DefaultHarness string `json:"default_harness,omitempty"`
Build *buildinfo.Info `json:"build,omitempty"`
Protocol int `json:"protocol,omitempty"`
DefaultModel string `json:"default_model,omitempty"`
Evidence []SessionEvidence `json:"evidence,omitempty"`
Usage *UsageStats `json:"usage,omitempty"`
@@ -121,13 +127,19 @@ type Message struct {
Error string `json:"error,omitempty"`
Name string `json:"name,omitempty"`
Source string `json:"source,omitempty"`
Title string `json:"title,omitempty"`
Version int `json:"version,omitempty"`
Query string `json:"query,omitempty"`
Kind string `json:"kind,omitempty"`
Pipelines []PipelineSummary `json:"pipelines,omitempty"`
PipelineID int64 `json:"pipeline_id,omitempty"`
Detail *PipelineDetail `json:"detail,omitempty"`
RunID int64 `json:"run_id,omitempty"`
RunDetail *RunDetail `json:"run_detail,omitempty"`
Runs []RunSummary `json:"runs,omitempty"`
Stage string `json:"stage,omitempty"`
Option string `json:"option,omitempty"`
Feedback string `json:"feedback,omitempty"`
Input map[string]any `json:"input,omitempty"`
AllowTools bool `json:"allow_tools,omitempty"`
WritePaths []string `json:"write_paths,omitempty"`
+101 -3
View File
@@ -1,5 +1,7 @@
package protocol
import "strings"
const (
RunPipeline = "run_pipeline"
RunStarted = "run_started"
@@ -9,10 +11,84 @@ const (
Run = "run"
CancelRun = "cancel_run"
RetryRun = "retry_run"
DecideRun = "decide_run"
SetRunTitle = "set_run_title"
GetRunEvidence = "get_run_evidence"
RunEvidence = "run_evidence"
)
// Waiting statuses. A human stage pauses its run without a live goroutine, so
// the run and its step persist these statuses and the decision path resumes
// them. Store, server, CLI and TUI read the one pair below, never a literal.
const (
RunStatusWaiting = "waiting"
RunStatusRunning = "running"
StepStatusWaiting = "waiting"
// NotifyWaiting is the notification event a human stage emits when it parks
// the run. It is the same value the `on=` policy accepts.
NotifyWaiting = "waiting"
)
// Waiting evidence keys. A human stage records its operator instructions and
// its ordered selectable options in the step output, so inspect and the TUI are
// self-contained without re-reading the pinned graph.
const (
WaitingPromptKey = "prompt"
WaitingOptionsKey = "options"
)
// Decision evidence keys. A decided human step records the operator's chosen
// option and optional feedback in its output, so the choice stays visible in
// inspect and the TUI. They are the one definition of those keys.
const (
DecisionOptionKey = "option"
DecisionFeedbackKey = "feedback"
)
// NewWaitingEvidence builds the self-contained evidence a human stage persists
// at wait time: the operator instructions and the ordered options to choose.
func NewWaitingEvidence(prompt string, options []string) map[string]any {
ordered := make([]any, len(options))
for i, option := range options {
ordered[i] = option
}
return map[string]any{WaitingPromptKey: prompt, WaitingOptionsKey: ordered}
}
// WaitingPrompt reads the recorded operator instructions from a waiting step's
// output, or "" when none were recorded.
func WaitingPrompt(output map[string]any) string {
prompt, _ := output[WaitingPromptKey].(string)
return prompt
}
// WaitingOptions reads the recorded selectable options from a waiting step's
// output, accepting the string and generic forms JSON decoding produces.
func WaitingOptions(output map[string]any) []string {
switch options := output[WaitingOptionsKey].(type) {
case []string:
return options
case []any:
result := make([]string, 0, len(options))
for _, option := range options {
if text, ok := option.(string); ok {
result = append(result, text)
}
}
return result
}
return nil
}
// DecisionEvidence reads the recorded choice and feedback from a decided human
// step's output, or empty strings when none were recorded. It is the read side
// of DecisionOptionKey/DecisionFeedbackKey.
func DecisionEvidence(output map[string]any) (option, feedback string) {
option, _ = output[DecisionOptionKey].(string)
feedback, _ = output[DecisionFeedbackKey].(string)
return option, feedback
}
type SessionEvidence struct {
Sequence int `json:"sequence"`
SessionID string `json:"session_id"`
@@ -23,15 +99,20 @@ type SessionEvidence struct {
}
type RunSummary struct {
ID int64 `json:"id"`
PipelineID int64 `json:"pipeline_id"`
Name string `json:"name"`
ID int64 `json:"id"`
PipelineID int64 `json:"pipeline_id"`
Name string `json:"name"`
// Title is the operator-facing, bounded single-line description of what the
// run is for, generated from its prompt. It is never empty for a new run;
// historical rows predating the title column may omit it.
Title string `json:"title,omitempty"`
Version int `json:"version"`
ContentHash string `json:"content_hash"`
Status string `json:"status"`
Executing bool `json:"executing"`
Outcome string `json:"outcome"`
CurrentStage string `json:"current_stage"`
Workspace string `json:"workspace,omitempty"`
CreatedAt string `json:"created_at"`
FinishedAt string `json:"finished_at"`
Diagnostic string `json:"diagnostic"`
@@ -39,9 +120,20 @@ type RunSummary struct {
CompletedSteps int `json:"completed_steps"`
}
// Label is the operator-facing name of a run: the generated Title when the
// server stored one, otherwise the pipeline Name (historical rows predate
// titles). It is the single definition shared by the CLI and TUI.
func (r RunSummary) Label() string {
if title := strings.TrimSpace(r.Title); title != "" {
return title
}
return r.Name
}
type RunStep struct {
Control *ControlEvidence `json:"control,omitempty"`
FileChanges *StageFileChanges `json:"file_changes,omitempty"`
Verdict *StageVerdict `json:"verdict,omitempty"`
Notifications []NotificationReceipt `json:"notifications,omitempty"`
Artifacts []StageArtifact `json:"artifacts,omitempty"`
Sequence int `json:"sequence"`
@@ -126,4 +218,10 @@ type RunDetail struct {
Input map[string]any `json:"input"`
Output map[string]any `json:"output"`
Steps []RunStep `json:"steps"`
// TitleSource is "model" when Title came from the shared summariser or
// "fallback" when it was derived from the prompt; TitleModel names the model
// that produced a model title. They are retained so a diagnosis can tell the
// two apart and see which model was used.
TitleSource string `json:"title_source,omitempty"`
TitleModel string `json:"title_model,omitempty"`
}
+191
View File
@@ -0,0 +1,191 @@
package protocol
import (
"encoding/json"
"path"
"strings"
)
// VerdictReasonKeys is the single ordered definition of the output keys a stage
// may use to state why it chose its outcome. The first key carrying usable text
// wins. Store, server and TUI all read this one list, so the order never drifts.
// "feedback" is last so it only states the reason when no model-authored key
// does: an operator's decision feedback is exactly the human stage's reason.
var VerdictReasonKeys = []string{"verdict", "reason", "decision", "summary", "implementation_summary", "feedback"}
// VerdictReasonCap bounds a verdict reason to this many runes, whether it was
// generated by the model or derived at read time. It is the same cap the
// summariser's OutputCap uses (summarise references this constant), so the two
// cannot drift.
const VerdictReasonCap = 200
// Verdict reason provenance. ReasonSource tells a diagnosis whether the stored
// one-liner came from the model, was derived at read time, or is honestly absent.
const (
VerdictReasonModel = "model"
VerdictReasonFallback = "fallback"
VerdictReasonAbsent = "absent"
)
// StageVerdict is the plain-language outcome of one completed stage visit: the
// chosen option (the step's outcome and the target it routed to), a one-line
// reason with its provenance, and the recorded artifacts the reason refers to. A
// nil RunStep.Verdict means there is no verdict (for example a running step); an
// empty struct is never serialised.
type StageVerdict struct {
Option string `json:"option"`
Reason string `json:"reason,omitempty"`
ReasonSource string `json:"reason_source,omitempty"`
Artifacts []string `json:"artifacts,omitempty"`
}
// DeriveVerdictReason reads the first usable reason line from a step's output in
// the shared key order. It accepts a string value, or JSON-encodes a non-string
// one (as OutputPreview does), normalises it to one safe line and bounds it to
// VerdictReasonCap runes. It returns "" when no key carries usable text and never
// synthesises a reason.
func DeriveVerdictReason(output map[string]any) string {
for _, key := range VerdictReasonKeys {
value, ok := output[key]
if !ok || value == nil {
continue
}
text, ok := value.(string)
if !ok {
encoded, err := json.Marshal(value)
if err != nil {
continue
}
text = string(encoded)
}
text = NormalizeText(text)
if text == "" || text == "[]" || text == "{}" {
continue
}
return capVerdictReason(text)
}
return ""
}
// VerdictOption states a step's chosen option plainly: its outcome and the target
// it routed to, with the terminal shorthands rendered as words.
func VerdictOption(outcome, target string) string {
target = ResolveTarget(outcome, target)
switch target {
case SuccessEnd:
target = "success"
case FailureEnd:
target = "failure"
}
return outcome + " → " + target
}
// ReferencedVerdictArtifacts returns the names of the artifacts actually recorded
// for a visit that the reason refers to, in their recorded order and deduplicated.
// A name is included when it (or its basename, for a slashed path) appears in the
// reason text, or when it is named in the output's screenshots list. Only recorded
// artifacts can be returned: a name the model invented that is not a real recorded
// file is never exposed.
func ReferencedVerdictArtifacts(reason string, output map[string]any, artifacts []StageArtifact) []string {
var names []string
seen := map[string]bool{}
for _, artifact := range artifacts {
name := artifact.Name
if name == "" || seen[name] {
continue
}
base := path.Base(name)
if !verdictMentionsArtifact(reason, name, base) && !screenshotsNameArtifact(output, name, base) {
continue
}
seen[name] = true
names = append(names, name)
}
return names
}
// verdictMentionsArtifact reports whether the reason text names an artifact by its
// full recorded name or by its basename.
func verdictMentionsArtifact(reason, name, base string) bool {
if reason == "" {
return false
}
if strings.Contains(reason, name) {
return true
}
return base != name && strings.Contains(reason, base)
}
// screenshotsNameArtifact reports whether the output's screenshots list names an
// artifact by its full recorded name or by its basename. The list may be a single
// string, a []string or a generic []any of strings.
func screenshotsNameArtifact(output map[string]any, name, base string) bool {
value, ok := output["screenshots"]
if !ok {
return false
}
for _, candidate := range screenshotNames(value) {
candidate = strings.TrimSpace(candidate)
if candidate != "" && (candidate == name || candidate == base) {
return true
}
}
return false
}
// screenshotNames flattens a screenshots value to its string entries, accepting
// the single-string, []string and generic []any forms stages emit.
func screenshotNames(value any) []string {
switch typed := value.(type) {
case string:
return []string{typed}
case []string:
return typed
case []any:
names := make([]string, 0, len(typed))
for _, item := range typed {
if name, ok := item.(string); ok {
names = append(names, name)
}
}
return names
}
return nil
}
// NewStageVerdict builds the verdict for one stage visit. It returns nil when the
// step carries neither an outcome nor a target (a running step has no verdict). A
// stored model reason is kept with its provenance; otherwise the read-time
// fallback derives the reason from the output, or marks it absent when no key
// carries usable text. Referenced artifacts are matched against the recorded
// artifacts only.
func NewStageVerdict(outcome, target string, output map[string]any, artifacts []StageArtifact, storedReason, storedSource string) *StageVerdict {
if outcome == "" && target == "" {
return nil
}
verdict := &StageVerdict{Option: VerdictOption(outcome, target)}
if reason := strings.TrimSpace(storedReason); reason != "" {
verdict.Reason = capVerdictReason(reason)
verdict.ReasonSource = storedSource
if verdict.ReasonSource == "" {
verdict.ReasonSource = VerdictReasonModel
}
} else if reason := DeriveVerdictReason(output); reason != "" {
verdict.Reason = reason
verdict.ReasonSource = VerdictReasonFallback
} else {
verdict.ReasonSource = VerdictReasonAbsent
}
verdict.Artifacts = ReferencedVerdictArtifacts(verdict.Reason, output, artifacts)
return verdict
}
// capVerdictReason bounds a reason to VerdictReasonCap runes without splitting a
// rune (rune slicing is inherently UTF-8-safe).
func capVerdictReason(text string) string {
runes := []rune(text)
if len(runes) <= VerdictReasonCap {
return text
}
return string(runes[:VerdictReasonCap])
}
+176
View File
@@ -0,0 +1,176 @@
package protocol
import (
"encoding/json"
"strings"
"testing"
"unicode/utf8"
)
func TestRunStepVerdictRoundTrip(t *testing.T) {
step := RunStep{
Sequence: 2,
Stage: "review",
Outcome: "success",
Target: "deliver",
Verdict: &StageVerdict{
Option: "success → deliver",
Reason: "Tests passed and evidence is retained",
ReasonSource: VerdictReasonModel,
Artifacts: []string{"captures/shot.png"},
},
}
encoded, err := json.Marshal(step)
if err != nil {
t.Fatal(err)
}
var decoded RunStep
if err := json.Unmarshal(encoded, &decoded); err != nil {
t.Fatal(err)
}
if decoded.Verdict == nil {
t.Fatal("verdict lost in round trip")
}
if decoded.Verdict.Option != step.Verdict.Option || decoded.Verdict.Reason != step.Verdict.Reason ||
decoded.Verdict.ReasonSource != step.Verdict.ReasonSource ||
len(decoded.Verdict.Artifacts) != 1 || decoded.Verdict.Artifacts[0] != "captures/shot.png" {
t.Fatalf("verdict fields lost in round trip: %+v", decoded.Verdict)
}
}
// TestRunStepOmitsAbsentVerdict mirrors TestRunStepOmitsAbsentArtifacts: a nil
// verdict marshals without the key (absent, not {}) and an absent key decodes nil.
func TestRunStepOmitsAbsentVerdict(t *testing.T) {
encoded, err := json.Marshal(RunStep{Sequence: 1, Stage: "one"})
if err != nil {
t.Fatal(err)
}
if strings.Contains(string(encoded), "verdict") {
t.Fatalf("nil verdict must be omitted, not serialised: %s", encoded)
}
var decoded RunStep
if err := json.Unmarshal([]byte(`{"sequence":1}`), &decoded); err != nil {
t.Fatal(err)
}
if decoded.Verdict != nil {
t.Fatalf("absent verdict must decode nil: %+v", decoded.Verdict)
}
}
func TestDeriveVerdictReasonKeyOrder(t *testing.T) {
cases := []struct {
name string
output map[string]any
want string
}{
{"verdict wins", map[string]any{"summary": "s", "reason": "r", "verdict": "v"}, "v"},
{"reason before decision", map[string]any{"summary": "s", "decision": "d", "reason": "r"}, "r"},
{"decision before summary", map[string]any{"summary": "s", "decision": "d"}, "d"},
{"summary before implementation_summary", map[string]any{"implementation_summary": "i", "summary": "s"}, "s"},
{"implementation_summary alone", map[string]any{"implementation_summary": "i"}, "i"},
{"non-string is encoded", map[string]any{"summary": 42}, "42"},
{"empty values skipped to a later key", map[string]any{"reason": " ", "summary": "s"}, "s"},
{"feedback states the reason when nothing else does", map[string]any{"option": "go", "feedback": "looks good"}, "looks good"},
{"summary still wins over feedback", map[string]any{"summary": "s", "feedback": "f"}, "s"},
{"none yields nothing", map[string]any{"other": "x", "screenshots": []any{"a.png"}}, ""},
{"nil output yields nothing", nil, ""},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := DeriveVerdictReason(tc.output); got != tc.want {
t.Fatalf("DeriveVerdictReason(%v) = %q, want %q", tc.output, got, tc.want)
}
})
}
}
func TestDeriveVerdictReasonIsBoundedRuneSafe(t *testing.T) {
long := strings.Repeat("é", VerdictReasonCap+50)
got := DeriveVerdictReason(map[string]any{"summary": long})
if len([]rune(got)) != VerdictReasonCap {
t.Fatalf("got %d runes, want the %d cap", len([]rune(got)), VerdictReasonCap)
}
if !utf8.ValidString(got) {
t.Fatal("bounded reason is not valid UTF-8")
}
}
func TestNewStageVerdictBoundsStoredReasonRuneSafe(t *testing.T) {
long := strings.Repeat("é", VerdictReasonCap+50)
verdict := NewStageVerdict("success", "#success", nil, nil, long, VerdictReasonModel)
if verdict == nil || len([]rune(verdict.Reason)) != VerdictReasonCap || !utf8.ValidString(verdict.Reason) {
t.Fatalf("stored reason not bounded rune-safely: %+v", verdict)
}
}
func TestVerdictOptionRendersTerminals(t *testing.T) {
cases := []struct{ outcome, target, want string }{
{"success", "#success", "success → success"},
{"error", "#failure", "error → failure"},
{"success", "review", "success → review"},
{"error", "#", "error → failure"},
}
for _, tc := range cases {
if got := VerdictOption(tc.outcome, tc.target); got != tc.want {
t.Fatalf("VerdictOption(%q,%q) = %q, want %q", tc.outcome, tc.target, got, tc.want)
}
}
}
func TestReferencedVerdictArtifactsMatchesRecordedOnly(t *testing.T) {
artifacts := []StageArtifact{{Name: "captures/shot.png"}, {Name: "report.txt"}, {Name: "unrelated.log"}}
// A name and a basename in the reason both match a recorded artifact; a name
// that is not recorded is never invented into the list.
got := ReferencedVerdictArtifacts("see captures/shot.png and the shot.png capture, plus ghost.png", nil, artifacts)
want := []string{"captures/shot.png"}
if len(got) != 1 || got[0] != want[0] {
t.Fatalf("reason matches = %v, want %v (missing.png is not a recorded file)", got, want)
}
// The screenshots list matches independently of the reason text.
got = ReferencedVerdictArtifacts("no file names here", map[string]any{"screenshots": []any{"unrelated.log"}}, artifacts)
if len(got) != 1 || got[0] != "unrelated.log" {
t.Fatalf("screenshots matches = %v, want unrelated.log", got)
}
// A single-string screenshots value is accepted too.
got = ReferencedVerdictArtifacts("", map[string]any{"screenshots": "report.txt"}, artifacts)
if len(got) != 1 || got[0] != "report.txt" {
t.Fatalf("string screenshots matches = %v, want report.txt", got)
}
// Duplicates are collapsed, and matches keep the recorded order.
dupes := []StageArtifact{{Name: "report.txt"}, {Name: "report.txt"}, {Name: "captures/shot.png"}}
got = ReferencedVerdictArtifacts("report.txt and captures/shot.png", nil, dupes)
if len(got) != 2 || got[0] != "report.txt" || got[1] != "captures/shot.png" {
t.Fatalf("deduped ordered matches = %v", got)
}
// A screenshots entry with no recorded match is never exposed.
if got := ReferencedVerdictArtifacts("", map[string]any{"screenshots": []any{"ghost.png"}}, artifacts); len(got) != 0 {
t.Fatalf("unrecorded screenshots entry exposed: %v", got)
}
// No reason, no screenshots: no artifacts.
if got := ReferencedVerdictArtifacts("", nil, artifacts); len(got) != 0 {
t.Fatalf("artifacts exposed without a reference: %v", got)
}
}
func TestNewStageVerdict(t *testing.T) {
// A running step carries neither outcome nor target and has no verdict.
if got := NewStageVerdict("", "", nil, nil, "", ""); got != nil {
t.Fatalf("running step verdict = %+v, want nil", got)
}
// A completed visit with no recorded artifacts still carries Option and Reason.
got := NewStageVerdict("success", "review", map[string]any{"summary": "did the work"}, nil, "", "")
if got == nil || got.Option != "success → review" || got.Reason != "did the work" ||
got.ReasonSource != VerdictReasonFallback || len(got.Artifacts) != 0 {
t.Fatalf("fallback verdict = %+v", got)
}
// A stored model line wins over the output and records its provenance.
got = NewStageVerdict("success", "review", map[string]any{"summary": "output text"}, nil, "the model line", VerdictReasonModel)
if got == nil || got.Reason != "the model line" || got.ReasonSource != VerdictReasonModel {
t.Fatalf("stored verdict = %+v", got)
}
// No usable reason key: honest absence with no invented text.
got = NewStageVerdict("success", "#success", map[string]any{"other": "x"}, nil, "", "")
if got == nil || got.Reason != "" || got.ReasonSource != VerdictReasonAbsent {
t.Fatalf("absent-reason verdict = %+v", got)
}
}