devrites 6.9.6 → 7.0.0

package/engine/internal/lib/dispatch_contract.go

@@ -1,9 +1,13 @@
 package lib
 
 import (
+	"errors"
 	"fmt"
+	"os"
 	"regexp"
 	"strings"
+
+	"github.com/devrites/devrites/internal/acceptance"
 )
 
 // maxContractBytes bounds a wright contract read; packets stay <= 64 KiB.
@@ -22,11 +26,43 @@ var (
 	// allowedAfterRE marks a forbid match that is about not weakening tests,
 	// not about skipping their execution ("no tests weakened or deleted").
 	allowedAfterRE = regexp.MustCompile(`(?i)^[\s/,a-z-]{0,24}\b(?:weaken|delet|remov|disabl|skipp|xfail|loosen)`)
+	// agentContractRE names an installed DevRites role contract on any host.
+	agentContractRE = regexp.MustCompile(`[\w./~-]*agents/devrites-[a-z0-9-]+\.(?:md|toml)\b`)
+	// readWordRE is a read instruction ("Read first", "read:"), not "read-only".
+	readWordRE = regexp.MustCompile(`(?i)\bread(?:\s|:|$)`)
+	// blankLineRE ends the `Writer-safe checks:` block.
+	blankLineRE = regexp.MustCompile(`\n[ \t]*\r?\n`)
+	// sectionHeadRE is a Markdown heading or a "Label:" line opening a list.
+	sectionHeadRE = regexp.MustCompile(`^\s*(?:#{1,6}\s.*|[^:]*:[\s*]*)$`)
 )
 
+// lintContractRead refuses a packet line that tells the agent to read an
+// installed role contract, on the line itself or under a "Read ..." heading or
+// label: a named agent already has it as its system prompt. Canonical sources
+// under pack/ are reviewable files, not the agent's own contract.
+func lintContractRead(kind, path string, raw []byte) error {
+	inRead := false
+	for i, line := range strings.Split(string(raw), "\n") {
+		if sectionHeadRE.MatchString(line) {
+			inRead = readWordRE.MatchString(line)
+		}
+		if !inRead && !readWordRE.MatchString(line) {
+			continue
+		}
+		for _, ref := range agentContractRE.FindAllString(line, -1) {
+			if !strings.Contains(ref, "pack/") {
+				return fmt.Errorf("%s %s:%d tells the agent to read a role contract (%q); a named agent already has its contract as its system prompt, and context --role names it in the bundle — drop the line",
+					kind, path, i+1, ref)
+			}
+		}
+	}
+	return nil
+}
+
 // lintWrightContract refuses a build wright contract that forbids the wright's
-// own writer-safe verification or names none, so a blind round is rejected
-// before launch rather than discovered after the wright returns.
+// own writer-safe verification, names none, or tells the wright to read its
+// installed role contract, so a blind round is rejected before launch rather
+// than discovered after the wright returns.
 func lintWrightContract(path string) error {
 	if path == "" {
 		return fmt.Errorf("a build wright wave needs --contract <file> holding the exact wright contract (with a `Writer-safe checks:` line)")
@@ -44,8 +80,52 @@ func lintWrightContract(path string) error {
 				path, i+1, strings.TrimSpace(line[loc[0]:loc[1]]))
 		}
 	}
+	if err := lintContractRead("wright contract", path, raw); err != nil {
+		return err
+	}
 	if !writerSafeLineRE.Match(raw) {
 		return fmt.Errorf("wright contract %s names no `Writer-safe checks:` line; list the syntax/type/lint, unit/self-check and narrow smoke commands the wright runs before returning", path)
 	}
 	return nil
 }
+
+// lintWrightContractFor is lintWrightContract plus the feature's gates.md: when
+// the ledger has a live `RUN: writer` row, the contract's `Writer-safe checks:`
+// block must name `gates precheck`, so the wright runs those rows and `check
+// windows` before returning instead of a repair round finding them after. An
+// absent gates.md requires nothing.
+func lintWrightContractFor(root, slug, path string) error {
+	if err := lintWrightContract(path); err != nil {
+		return err
+	}
+	ledger, err := readWorkspaceArtifact(root, slug, acceptance.GatesFile)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("wright contract %s: %w", path, err)
+	}
+	writers := acceptance.ParseLedger(string(ledger)).WriterGates()
+	if len(writers) == 0 {
+		return nil
+	}
+	raw, err := readBoundedRegularFile(path, maxContractBytes)
+	if err != nil {
+		return fmt.Errorf("wright contract %s: %w", path, err)
+	}
+	// The block runs from the `Writer-safe checks:` line to the first blank
+	// line after its first listed check.
+	loc := writerSafeLineRE.FindIndex(raw)
+	if loc == nil {
+		return fmt.Errorf("wright contract %s changed while it was linted", path)
+	}
+	block := raw[loc[0]:]
+	if end := blankLineRE.FindIndex(block[loc[1]-1-loc[0]:]); end != nil {
+		block = block[:loc[1]-1-loc[0]+end[0]]
+	}
+	if !strings.Contains(string(block), "gates precheck") {
+		return fmt.Errorf("wright contract %s: %s marks %s `RUN: writer`, so its `Writer-safe checks:` must include `devrites-engine gates precheck %s --worktree <path>`; the wright runs those rows and `check windows` and fixes failures before returning",
+			path, acceptance.GatesFile, writers[0].ID, slug)
+	}
+	return nil
+}

package/engine/internal/lib/dispatch_packet.go

@@ -1,9 +1,16 @@
 package lib
 
 import (
+	"errors"
 	"fmt"
+	"os"
+	"path/filepath"
 	"regexp"
+	"slices"
+	"strconv"
 	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
 )
 
 // seedingRE matches packet text that hands a reviewer a conclusion instead of
@@ -12,20 +19,105 @@ import (
 var seedingRE = regexp.MustCompile(`\b[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+-PASS\b` +
 	`|(?i:\bno-findings\b)` +
 	`|(?i:^\s*(?:outcome|counts|verdict)\s*:\s*[^<\s])` +
-	`|(?i:\b(?:already|previously)\s+(?:passed|passes|green|printed|verified|approved|clean)\b)` +
-	`|(?i:\b(?:critical|important)\s*[:=]?\s*0\b)`)
+	`|(?i:\b(?:already|previously)\s+(?:passed|passes|green|printed|verified|approved|clean|fixed|closed|resolved)\b)` +
+	`|(?i:\b(?:critical|important)\s*[:=]?\s*0\b)` +
+	// Phrasings observed in voided reviews: a parent/sibling report, a passed
+	// check, a returned severity or finding, a green outcome, a return file.
+	`|(?i:\b(?:parent|root|sibling|drafter|wright|implementer)(?:\s+self-attack)?\s+(?:observed|reports?|reported|concluded|confirmed|exposes|exposed)\b)` +
+	`|(?i:\b(?:check|gate|scope|tests?)\s+passed\b)` +
+	`|(?i:\breturned\s+(?:critical|important|minor|findings|no-findings)\b)` +
+	`|(?i:\b(?:critical|important|minor)\s+F\d+\b)` +
+	`|(?i:\bclosed\s+by\b)` +
+	`|(?i:\b(?:makes|made|turned|went)\s+[\w/-]*\s*green\b)` +
+	`|packets/\S+\.return\.md`)
+
+// roleTagRE matches a role-tagged finding fingerprint ("Plan F1", "DevEx S2").
+// The tag is a reviewer role's leading word: Perf for performance-reviewer.
+var roleTagRE = regexp.MustCompile(`\b(Plan|Doubt|Code|DevEx|Test|Security|Spec|Strategy|Perf|Frontend|Simplifier)\s+[FS]\d+\b`)
+
+// countsTemplateRE matches a Counts line whose every value is a placeholder
+// (the return template), which names keys but no conclusion.
+var countsTemplateRE = regexp.MustCompile(`(?i)^\s*counts\s*:(?:\s+[a-z]+=<[^<>]*>)+\s*$`)
+
+// roleBase is the canonical role a --role names: an optional "devrites-"
+// agent-name prefix and ".lane" suffix dropped.
+func roleBase(role string) string {
+	base, _, _ := strings.Cut(strings.TrimPrefix(role, "devrites-"), ".")
+	return base
+}
 
 // isReviewerRole reports whether role is an independent read-only reviewer:
-// a *-reviewer, *-auditor, or test-analyst, with an optional ".lane" suffix.
+// a *-reviewer, *-auditor, or test-analyst.
 func isReviewerRole(role string) bool {
-	base, _, _ := strings.Cut(role, ".")
+	base := roleBase(role)
 	return strings.HasSuffix(base, "-reviewer") || strings.HasSuffix(base, "-auditor") || base == "test-analyst"
 }
 
-// lintReviewerPacket refuses a reviewer packet that seeds a conclusion, so a
-// voided review is rejected before launch rather than discovered after it.
+// lintKnownRoles refuses a --role that names no pack agent, so a free-form
+// label ("test-analyst-022-r5") cannot skip the reviewer lints. The agent path
+// resolves as context --role does: the phase skill's loads manifest, else the
+// devrites-<role> convention, in any project-level host install; a Codex
+// install keeps role agents at .codex/agents/<name>.toml.
+// shortcut: only project-level installs are checked (a global-only install or
+// none skips the check); check the user install too if free-form roles recur there.
+func lintKnownRoles(root, phase string, roles []string) error {
+	project := filepath.Dir(root)
+	var skillsRoots []string
+	if dir, err := resolveSkillsRoot(root, ""); err == nil {
+		if rel, err := filepath.Rel(project, dir); err == nil && rel != ".." && !strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+			skillsRoots = append(skillsRoots, dir)
+		}
+	}
+	for _, rel := range []string{".omp/skills", ".agents/skills", ".pi/skills", ".devin/skills"} {
+		dir := filepath.Join(project, filepath.FromSlash(rel))
+		if info, err := os.Stat(filepath.Join(dir, "devrites-lib")); err == nil && info.IsDir() {
+			skillsRoots = append(skillsRoots, dir)
+		}
+	}
+	manifests := make([]loadsManifest, len(skillsRoots))
+	for i, dir := range skillsRoots {
+		if raw, err := os.ReadFile(filepath.Join(dir, "rite-"+strings.ToLower(phase), "SKILL.md")); err == nil { // #nosec G304 -- resolved under a project skills root
+			manifests[i], _, _ = parseLoadsManifest(string(raw))
+		}
+	}
+	isRegular := func(path string) bool {
+		info, err := os.Stat(path)
+		return err == nil && info.Mode().IsRegular()
+	}
+	for _, role := range roles {
+		base := roleBase(role)
+		known := len(skillsRoots) == 0
+		for i, dir := range skillsRoots {
+			if !devritespaths.ValidSlug(base) {
+				break
+			}
+			rel := filepath.FromSlash(roleAgentPath(manifests[i], base))
+			if isRegular(filepath.Join(dir, "..", "agents", rel)) ||
+				isRegular(filepath.Join(project, ".codex", "agents", strings.TrimSuffix(filepath.Base(rel), ".md")+".toml")) {
+				known = true
+				break
+			}
+		}
+		if !known {
+			return fmt.Errorf("role %q names no pack agent; use a canonical role, optionally with a .<lane> suffix", role)
+		}
+	}
+	return nil
+}
+
+// lintReviewerPacket refuses a reviewer packet that seeds a conclusion or
+// tells the reviewer to read its installed role contract, so a voided review
+// is rejected before launch rather than discovered after it.
 // Placeholder text inside <...> (an output template) is not a conclusion.
+// With no wave roles, every role-tagged fingerprint is refused.
 func lintReviewerPacket(path string) error {
+	return lintReviewerWavePacket(path, nil)
+}
+
+// lintReviewerWavePacket is lintReviewerPacket for a wave: a role-tagged
+// fingerprint passes only when roles hold exactly one reviewer role and the
+// tag names it.
+func lintReviewerWavePacket(path string, roles []string) error {
 	if path == "" {
 		return fmt.Errorf("a reviewer wave needs --packet <file> holding the exact packet the reviewers receive")
 	}
@@ -33,19 +125,143 @@ func lintReviewerPacket(path string) error {
 	if err != nil {
 		return fmt.Errorf("reviewer packet %s: %w", path, err)
 	}
+	var reviewers []string
+	for _, role := range roles {
+		if base := roleBase(role); isReviewerRole(base) && !slices.Contains(reviewers, base) {
+			reviewers = append(reviewers, base)
+		}
+	}
 	for i, line := range strings.Split(string(raw), "\n") {
+		if countsTemplateRE.MatchString(line) {
+			continue
+		}
 		for _, loc := range seedingRE.FindAllStringIndex(line, -1) {
 			if insidePlaceholder(line, loc[0], loc[1]) {
 				continue
 			}
-			return fmt.Errorf("reviewer packet %s:%d seeds a conclusion (%q); a packet carries scope, paths, diff and rubric only — never a gate result, a reviewer outcome or count, or a claim that something already passed. Weigh root proof at reconciliation instead",
+			return fmt.Errorf("reviewer packet %s:%d seeds a conclusion (%q); a packet carries scope, paths, diff and rubric only — never a gate result, a reviewer outcome or count, or a claim that something already passed (agents.md § Independence). Weigh root proof at reconciliation instead",
 				path, i+1, strings.TrimSpace(line[loc[0]:loc[1]]))
 		}
+		for _, m := range roleTagRE.FindAllStringSubmatchIndex(line, -1) {
+			tag := strings.ToLower(line[m[2]:m[3]])
+			if insidePlaceholder(line, m[0], m[1]) || (len(reviewers) == 1 && strings.HasPrefix(reviewers[0], tag)) {
+				continue
+			}
+			return fmt.Errorf("reviewer packet %s:%d carries fingerprint %q from another role; a recheck packet lists only fingerprints that same role raised, so send it to that role's recheck alone (agents.md § Independence)",
+				path, i+1, line[m[0]:m[1]])
+		}
 	}
-	return nil
+	return lintContractRead("reviewer packet", path, raw)
 }
 
 func insidePlaceholder(line string, start, end int) bool {
 	open := strings.LastIndex(line[:start], "<")
 	return open >= 0 && open > strings.LastIndex(line[:start], ">") && strings.Contains(line[end:], ">")
 }
+
+// severityCountKeys is the Counts vocabulary of a reviewer role that
+// returnCountKeys does not list.
+var severityCountKeys = []string{"critical", "important", "suggestion", "nit", "fyi", "gap"}
+
+// returnCountKeys is the closed, ordered Counts vocabulary of the reviewer
+// roles that differ from severityCountKeys. The agent-template head test reads
+// this table, so the engine and the templates share one source.
+var returnCountKeys = map[string][]string{
+	"plan-reviewer":       {"critical", "important", "suggestion", "nit", "fyi", "gap", "contract", "mechanism"},
+	"simplifier-reviewer": {"suggestion", "nit", "fyi", "gap"},
+}
+
+func countKeys(role string) []string {
+	if keys, ok := returnCountKeys[roleBase(role)]; ok {
+		return keys
+	}
+	return severityCountKeys
+}
+
+var countRE = regexp.MustCompile(`^([a-z]+)=([0-9]{1,6})$`)
+
+// parseReturnHead reads a reviewer return's strict head: line 1
+// "Outcome: findings|no-findings|gap", line 2 "Counts: key=N ..." with keys
+// from the role's vocabulary. findings needs a non-gap count above 0 and
+// no-findings needs every count at 0. It returns the outcome and the counts as
+// "key=N,key=N"; an error means the head is malformed.
+func parseReturnHead(role, text string) (outcome, counts string, err error) {
+	lines := strings.SplitN(strings.TrimLeft(text, "\r\n"), "\n", 3)
+	if len(lines) < 2 {
+		return "", "", errors.New("no Outcome/Counts head on lines 1-2")
+	}
+	outcome, ok := strings.CutPrefix(strings.TrimSpace(lines[0]), "Outcome: ")
+	if !ok || (outcome != "findings" && outcome != "no-findings" && outcome != "gap") {
+		return "", "", fmt.Errorf("line 1 is not \"Outcome: findings|no-findings|gap\": %q", strings.TrimSpace(lines[0]))
+	}
+	rest, ok := strings.CutPrefix(strings.TrimSpace(lines[1]), "Counts:")
+	fields := strings.Fields(rest)
+	if !ok || len(fields) == 0 {
+		return "", "", fmt.Errorf("line 2 is not \"Counts: key=N ...\": %q", strings.TrimSpace(lines[1]))
+	}
+	allowed := countKeys(role)
+	seen := map[string]bool{}
+	total, nonGap := 0, 0
+	for _, field := range fields {
+		m := countRE.FindStringSubmatch(field)
+		if m == nil || !slices.Contains(allowed, m[1]) || seen[m[1]] {
+			return "", "", fmt.Errorf("line 2 has Counts entry %q, which is not a distinct key=N with key in %s", field, strings.Join(allowed, ","))
+		}
+		seen[m[1]] = true
+		n, _ := strconv.Atoi(m[2])
+		total += n
+		if m[1] != "gap" {
+			nonGap += n
+		}
+	}
+	if outcome == "findings" && nonGap == 0 {
+		return "", "", errors.New("line 1 says findings but no non-gap count is above 0")
+	}
+	if outcome == "no-findings" && total > 0 {
+		return "", "", errors.New("line 1 says no-findings but a count is above 0")
+	}
+	return outcome, strings.Join(fields, ","), nil
+}
+
+var siteLineRE = regexp.MustCompile(`(?::[0-9]+)+(?:-[0-9]+)?$`)
+
+// findingKeys returns one role|slice|file|section|severity key per "Finding:"
+// row and the number of "Late:" lines. The site drops its line number so a
+// re-raise after an edit still matches, and spaces become "_" so each key is
+// one note token.
+// shortcut: cells split on every "|", so a quoted "|" shifts the cells; parse
+// the quote if keys come out wrong.
+func findingKeys(role, slice, text string) (keys []string, late int) {
+	for _, line := range strings.Split(text, "\n") {
+		line = strings.TrimSpace(line)
+		if strings.HasPrefix(line, "Late:") {
+			late++
+			continue
+		}
+		row, ok := strings.CutPrefix(line, "Finding:")
+		if !ok {
+			continue
+		}
+		cells := strings.Split(row, "|")
+		file, section := "", ""
+		if len(cells) > 1 {
+			file = siteLineRE.ReplaceAllString(strings.TrimSpace(cells[1]), "")
+		}
+		for _, cell := range cells[min(2, len(cells)):] {
+			if cited, ok := strings.CutPrefix(strings.TrimSpace(cell), "breaks "); ok {
+				section, _, _ = strings.Cut(cited, `"`)
+				break
+			}
+		}
+		severity, _, _ := strings.Cut(strings.TrimSpace(cells[0]), " ")
+		keys = append(keys, strings.Join([]string{role, slice, keyToken(file), keyToken(section), keyToken(strings.ToLower(severity))}, "|"))
+	}
+	return keys, late
+}
+
+func keyToken(s string) string {
+	if fields := strings.Fields(s); len(fields) > 0 {
+		return strings.Join(fields, "_")
+	}
+	return "-"
+}

package/engine/internal/lib/environment_report.go

@@ -59,11 +59,10 @@ func EnvironmentReportFor(devritesRoot, projectRoot string) (EnvironmentReport,
 		EngineVersion: version.Version,
 		ProjectRoot:   abs,
 		Manifest:      probePath(abs, devritespaths.ManifestName),
+		// codebase-memory-mcp keeps its index in a central store; only its
+		// optional persisted artifact lives in the repository.
 		Indexes: []PathProbe{
-			probePath(abs, ".codegraph"),
-			probePath(abs, ".code-review-graph"),
 			probePath(abs, ".codebase-memory"),
-			probePath(abs, "graph.json"),
 		},
 	}
 	if devritesRoot != "" {

package/engine/internal/lib/handoff.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 
 	"github.com/devrites/devrites/internal/acceptance"
@@ -32,10 +33,14 @@ var readNextOrder = []string{
 
 // RunHandoff emits the deterministic resume record for one feature workspace:
 // cursor fields, blocking question gates, the acceptance-ledger reduction,
-// recorded dead ends, and the canonical read-next order. It never writes; the
-// record is a faithful reduction of durable artifacts so a fresh agent (or a
-// handoff writer) does not depend on transcript memory to resume.
+// recorded dead ends, in-flight dispatch waves, and the canonical read-next
+// order. The record is a faithful reduction of durable artifacts so a fresh
+// agent (or a handoff writer) does not depend on transcript memory to resume.
+// It writes nothing unless --resume is given: then it appends one resume
+// metric so `metrics summary` can time each resume to the next dispatch.
 func RunHandoff(root string, args []string, stdout, stderr io.Writer) int {
+	resume := slices.Contains(args, "--resume")
+	args = slices.DeleteFunc(slices.Clone(args), func(a string) bool { return a == "--resume" })
 	slug, code, err := ActiveSlug(root, args)
 	if err != nil {
 		fmt.Fprintf(stderr, "handoff: %v\n", err)
@@ -76,6 +81,7 @@ func RunHandoff(root string, args []string, stdout, stderr io.Writer) int {
 	writeHandoffQuestions(featureDir, stdout)
 	writeHandoffLedger(featureDir, stdout)
 	writeHandoffDeadEnds(featureDir, stdout)
+	writeHandoffWaves(root, slug, stdout)
 
 	if report.Complete() {
 		fmt.Fprintln(stdout, "missing_required: none")
@@ -83,6 +89,9 @@ func RunHandoff(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stdout, "missing_required: %s\n", strings.Join(report.MissingFiles, ", "))
 	}
 	fmt.Fprintf(stdout, "read_next: %s\n", strings.Join(readNext(featureDir), ", "))
+	if resume {
+		recordMetric(root, slug, string(report.Phase), "resume", "root", 0)
+	}
 	return 0
 }
 
@@ -161,6 +170,27 @@ func writeHandoffDeadEnds(featureDir string, stdout io.Writer) {
 	}
 }
 
+// writeHandoffWaves lists dispatch waves whose agents have not all returned,
+// with the reduction observe uses, so a resume reconciles a running cohort
+// instead of re-dispatching it.
+func writeHandoffWaves(root, slug string, stdout io.Writer) {
+	f, _, err := loadDispatch(root, slug)
+	if err != nil {
+		fmt.Fprintf(stdout, "inflight_waves: unreadable (%v)\n", err)
+		return
+	}
+	waves := inflightWaves(f)
+	if len(waves) == 0 {
+		fmt.Fprintln(stdout, "inflight_waves: none")
+		return
+	}
+	fmt.Fprintf(stdout, "inflight_waves: %d\n", len(waves))
+	for _, w := range waves {
+		fmt.Fprintf(stdout, "inflight_wave: %s phase=%s state=%s pending=%s slices=%s\n",
+			w.Wave, w.Phase, w.State, orDash(strings.Join(w.Pending, ",")), orDash(strings.Join(w.Slices, ",")))
+	}
+}
+
 func deadEnds(data []byte) []string {
 	var ends []string
 	inSection := false

package/engine/internal/lib/metrics.go

@@ -127,17 +127,21 @@ func metricsRecord(root string, args []string, stdout, stderr io.Writer) int {
 // bundle emission). It never fails the caller: a metrics write is observability,
 // not a gate.
 func recordMetric(root, slug, phase, event, role string, bytes int64) {
+	appendMetric(root, slug, metricEvent{Phase: phase, Event: event, Role: role, Bytes: bytes})
+}
+
+// recordMetricNote is recordMetric for an event that carries a note, such as a
+// return's reviewer outcome or an abandon reason.
+func recordMetricNote(root, slug, phase, event, role, note string) {
+	appendMetric(root, slug, metricEvent{Phase: phase, Event: event, Role: role, Note: note})
+}
+
+func appendMetric(root, slug string, entry metricEvent) {
 	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
 	if err != nil {
 		return
 	}
-	entry := metricEvent{
-		TS:    time.Now().UTC().Format(time.RFC3339),
-		Phase: phase,
-		Event: event,
-		Role:  role,
-		Bytes: bytes,
-	}
+	entry.TS = time.Now().UTC().Format(time.RFC3339)
 	line, err := json.Marshal(entry)
 	if err != nil {
 		return
@@ -197,14 +201,20 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 		byKind map[string]int
 	}
 	type roleAgg struct {
-		events int
-		bytes  int64
+		events   int
+		bytes    int64
+		outcomes map[string]int
+		returns  []storedReturn
 	}
 	phases := map[string]*phaseAgg{}
 	roles := map[string]*roleAgg{}
 	totalBytes := int64(0)
 	totalEvents := 0
 	bad := 0
+	// Each resume's minutes to the next dispatch, in ledger (append) order:
+	// "none" when another resume came first, "open" when no dispatch followed.
+	var resumeGaps []string
+	var pendingResume *time.Time
 	// A reader, not a Scanner: one event line carries an unbounded --note. A
 	// final line without a newline is handled, then the next read is ("", EOF).
 	reader := bufio.NewReader(f)
@@ -234,14 +244,36 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 		agg.events++
 		agg.bytes += ev.Bytes
 		agg.byKind[ev.Event]++
+		if ts, err := time.Parse(time.RFC3339, ev.TS); err == nil && (ev.Event == "resume" || ev.Event == "dispatch") {
+			if ev.Event == "resume" {
+				if pendingResume != nil {
+					resumeGaps = append(resumeGaps, "none")
+				}
+				pendingResume = &ts
+			} else if pendingResume != nil {
+				resumeGaps = append(resumeGaps, strconv.FormatFloat(ts.Sub(*pendingResume).Minutes(), 'f', 0, 64))
+				pendingResume = nil
+			}
+		}
 		if ev.Role != "" {
 			ragg, ok := roles[ev.Role]
 			if !ok {
-				ragg = &roleAgg{}
+				ragg = &roleAgg{outcomes: map[string]int{}}
 				roles[ev.Role] = ragg
 			}
 			ragg.events++
 			ragg.bytes += ev.Bytes
+			if ev.Event == "return" {
+				fields := strings.Fields(ev.Note)
+				if len(fields) > 0 {
+					if outcome, ok := strings.CutPrefix(fields[0], "outcome="); ok {
+						ragg.outcomes[outcome]++
+					}
+				}
+				if rec, ok := parseStoredReturn(fields); ok {
+					ragg.returns = append(ragg.returns, rec)
+				}
+			}
 		}
 		totalEvents++
 		totalBytes += ev.Bytes
@@ -274,9 +306,28 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintln(stdout, "  roles:")
 		for _, role := range orderedRoles {
 			agg := roles[role]
-			fmt.Fprintf(stdout, "    %-24s events=%d bytes=%d\n", role, agg.events, agg.bytes)
+			fmt.Fprintf(stdout, "    %-24s events=%d bytes=%d", role, agg.events, agg.bytes)
+			if len(agg.outcomes) > 0 {
+				tally := make([]string, 0, len(agg.outcomes))
+				for outcome, n := range agg.outcomes {
+					tally = append(tally, fmt.Sprintf("%s=%d", outcome, n))
+				}
+				sort.Strings(tally)
+				fmt.Fprintf(stdout, " outcomes: %s", strings.Join(tally, " "))
+			}
+			if len(agg.returns) > 0 {
+				resolved, reraised, open, late := findingResolution(agg.returns)
+				fmt.Fprintf(stdout, " resolution: resolved=%d re-raised=%d open=%d late=%d", resolved, reraised, open, late)
+			}
+			fmt.Fprintln(stdout)
 		}
 	}
+	if pendingResume != nil {
+		resumeGaps = append(resumeGaps, "open")
+	}
+	if len(resumeGaps) > 0 {
+		fmt.Fprintf(stdout, "  resumes    count=%d minutes_to_dispatch=%s\n", len(resumeGaps), strings.Join(resumeGaps, ","))
+	}
 	fmt.Fprintf(stdout, "  total      events=%d bytes=%d", totalEvents, totalBytes)
 	if bad > 0 {
 		fmt.Fprintf(stdout, " unparsed=%d", bad)
@@ -285,6 +336,63 @@ func metricsSummary(root string, args []string, stdout, stderr io.Writer) int {
 	return 0
 }
 
+// storedReturn is one return recorded with dispatch return --result: its
+// slice, Finding: keys, and Late: line count.
+type storedReturn struct {
+	slice string
+	keys  []string
+	late  int
+}
+
+// parseStoredReturn reads the slice=, late= and finding= tokens of a return
+// note; a note without slice= was not recorded with --result.
+func parseStoredReturn(fields []string) (storedReturn, bool) {
+	var rec storedReturn
+	found := false
+	for _, field := range fields {
+		if v, ok := strings.CutPrefix(field, "slice="); ok {
+			rec.slice, found = v, true
+		} else if v, ok := strings.CutPrefix(field, "late="); ok {
+			rec.late, _ = strconv.Atoi(v)
+		} else if v, ok := strings.CutPrefix(field, "finding="); ok {
+			rec.keys = append(rec.keys, v)
+		}
+	}
+	return rec, found
+}
+
+// findingResolution classifies each raised finding key of one role, in ledger
+// order: re-raised when a later return on the same slice raises it again,
+// resolved when a later return on that slice does not, open when no later
+// return on that slice exists yet.
+func findingResolution(returns []storedReturn) (resolved, reraised, open, late int) {
+	for i, rec := range returns {
+		late += rec.late
+		for _, key := range rec.keys {
+			rechecked, again := false, false
+			for _, next := range returns[i+1:] {
+				if next.slice != rec.slice {
+					continue
+				}
+				rechecked = true
+				if slices.Contains(next.keys, key) {
+					again = true
+					break
+				}
+			}
+			switch {
+			case again:
+				reraised++
+			case rechecked:
+				resolved++
+			default:
+				open++
+			}
+		}
+	}
+	return resolved, reraised, open, late
+}
+
 // sliceCostSummary reports, per slice named on dispatch waves, the build wright
 // rounds, slice-bound Vet rechecks, and agent-minutes (role start to return; a
 // wave naming several slices splits its minutes evenly). Abandoned waves are