Spec #137: per-Series poll failure state, completion hint, and outbound owner notification (#174)

Implements spec #137 (spec 4 of 4 from wayfinder map #114).

Closes #137.

Tickets: #164, #165, #166, #167, #168, #169, #170, #171, #172, #173 — all closed, landed on this branch.

## Summary
- #164/#168: sixth outcome word `not_found`; per-Site completed marker predicate.
- #165/#169: `poll_failures` row is the failure state; the pass remembers a Site-reported completion.
- #166/#171: two new admin filters (`failing`, `unverified`); outbound owner notification + stall condition.
- #167/#170: a failure names itself on the Series page; the completion hint reaches the owner and decides nothing.
- #172: the other three fault conditions (no-browser-route, sidecar-down, adapter-broken) feeding the notifier.
- #173: the landing verdict line shares the same `latest.FaultsFrom` judgement the notifier uses, so the page and the push cannot disagree.

`cd backend && go test ./...` green on the merged branch (8 packages).

Reviewed-on: #174
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>

backend/internal/web/admin.go

@@ -4,14 +4,16 @@ import (
 	"log"
 	"net/http"
 	"strconv"
-	"time"
 
+	"bookmarkmanager/backend/internal/latest"
 	"bookmarkmanager/backend/internal/store"
 )
 
 // ownerWindow is the staleness boundary the Series list's "not checked in
-// 12h" filter compares against. Declared once; later admin tickets read it.
-const ownerWindow = 12 * time.Hour
+// 12h" filter compares against. It reads latest.OwnerWindow — the one place
+// the class-level twelve hours lives, shared with the owner-notice
+// conditions (issue #171).
+const ownerWindow = latest.OwnerWindow
 
 // adminView is the shared shell data for an administrative page and the roster
 // fragment returned after a Reader action.

backend/internal/web/admin_lanes.go

@@ -56,6 +56,10 @@ type laneRow struct {
 	// offer Resume from the moment the owner presses Pause, with no pass
 	// having run to record it (issue #147).
 	Paused bool
+	// FailingHref is the one navigation the row offers: the Site's name
+	// links to that Site's failing Series. The chips beside it stay
+	// unlinked; the withdrawn promise lives on outcomeChips (issue #167).
+	FailingHref string
 }
 
 // chip is one named outcome count over the owner's window.
@@ -223,6 +227,7 @@ func buildLaneRow(p store.LanePass, o store.SiteOutcomes, now time.Time) laneRow
 	if p.GapMS > 0 {
 		row.Gap = (time.Duration(p.GapMS) * time.Millisecond).Truncate(time.Second).String()
 	}
+	row.FailingHref = seriesListHref(store.SeriesFilterFailing, p.Site, "", 0)
 	row.Chips = outcomeChips(o)
 	row.HasChips = len(row.Chips) > 0
 	row.StatePhrase, row.StateGood, row.Attention = laneState(p, now)
@@ -232,17 +237,24 @@ func buildLaneRow(p store.LanePass, o store.SiteOutcomes, now time.Time) laneRow
 
 // outcomeChips lists a Site's nonzero window sums in the taxonomy's fixed
 // order, so the chips never reorder as the window changes. None observed is
-// written by the template, not drawn as a confident zero count.
+// written by the template, not drawn as a confident zero count. The names are
+// spelled through outcomeWord, the one vocabulary the failure surface shares
+// with the Series list's fact line (issue #167). The counts stay unlinked
+// permanently — a withdrawn promise: two of the six words write no per-Series
+// state, and the other four count attempts inside the owner window while the
+// failing filter lists Series failing now, so neither set contains the other
+// and no chip can be a door to its list.
 func outcomeChips(o store.SiteOutcomes) []chip {
 	fixed := []struct {
 		name  string
 		count int
 	}{
-		{"refused", o.Refused},
-		{"unreachable", o.Unreachable},
-		{"no chapter", o.NoChapter},
-		{"unfetchable", o.Unfetchable},
-		{"errors", o.Errors},
+		{outcomeWord("refused"), o.Refused},
+		{outcomeWord("unreachable"), o.Unreachable},
+		{outcomeWord("no_chapter"), o.NoChapter},
+		{outcomeWord("unfetchable"), o.Unfetchable},
+		{outcomeWord("not_found"), o.NotFound},
+		{outcomeWord("errors"), o.Errors},
 	}
 	var out []chip
 	for _, f := range fixed {

backend/internal/web/admin_overview.go

@@ -2,8 +2,10 @@ package web
 
 import (
 	"fmt"
+	"log"
 	"time"
 
+	"bookmarkmanager/backend/internal/latest"
 	"bookmarkmanager/backend/internal/store"
 )
 
@@ -23,10 +25,10 @@ type overviewView struct {
 	// as stale + never_checked: a never-checked Series is already counted on
 	// its own filter, and the verdict wants the inclusive number.
 	Unchecked int
-	// Hygiene is the seven problem filters in the Series list's own render
-	// order plus the finished figure riding last (informational); Library is
-	// the library split plus the roster. Every figure is a door into the list
-	// that counts it, except a zero.
+	// Hygiene is the problem filters in the Series list's own render order
+	// plus the informational tail — finished, then site completed — riding
+	// last; Library is the library split plus the roster. Every figure is a
+	// door into the list that counts it, except a zero.
 	Hygiene []fig
 	Library []fig
 	// Sites is the per-Site library shape table, one row per Site with any
@@ -60,10 +62,13 @@ type siteRow struct {
 }
 
 // overviewView assembles the landing page from the store's read model: one
-// SeriesShapes pass per filter summed in Go (the shipped surface offers nine
+// SeriesShapes pass per filter summed in Go (the shipped surface offers ten
 // grouped passes, not a stats query — #140), the pass log's latest pass per
-// Site, and the roster. A failure in any read is a 500 with a logged reason,
-// never a page of silent zeroes.
+// Site, and the roster. A failure in the SeriesShapes, pass or roster reads
+// is a 500 with a logged reason, never a page of silent zeroes. The three
+// fault-input reads (RefusingSince, SidecarOK, NoChapterShare) fail open:
+// a failing read logs and contributes no fault, so the landing page still
+// renders — the same fail-open the poller uses for owner notices.
 func (h *Handler) overviewView() (overviewView, error) {
 	now := time.Now()
 	cutoff := now.Add(-ownerWindow).UnixMilli()
@@ -92,12 +97,36 @@ func (h *Handler) overviewView() (overviewView, error) {
 
 	view := overviewView{Waiting: waiting(passes)}
 	view.Unchecked = totals[store.SeriesFilterStale] + totals[store.SeriesFilterNeverChecked]
-	view.Verdict, view.HasCounts = overviewVerdict(passes, now)
+	var refusingSince map[string]int64
+	if m, err := h.store.RefusingSince(now.UnixMilli()); err != nil {
+		log.Printf("admin overview: refusing since: %v", err)
+	} else {
+		refusingSince = m
+	}
+	var sidecarOK map[string]int64
+	if m, err := h.store.SidecarOK(latest.BrowserBackedSites()); err != nil {
+		log.Printf("admin overview: sidecar ok: %v", err)
+	} else {
+		sidecarOK = m
+	}
+	var noChapterShare map[string]float64
+	if m, err := h.store.NoChapterShare(cutoff); err != nil {
+		log.Printf("admin overview: no-chapter share: %v", err)
+	} else {
+		noChapterShare = m
+	}
+	faults := latest.FaultsFrom(latest.FaultInput{
+		Passes:         passes,
+		RefusingSince:  refusingSince,
+		SidecarOK:      sidecarOK,
+		NoChapterShare: noChapterShare,
+	}, now)
+	view.Verdict, view.HasCounts = overviewVerdict(passes, faults)
 
-	// The hygiene figures, in seriesFilterOrder's tail: the seven problem
-	// filters in permanent-then-fixable order, then the finished figure last —
-	// informational, not a problem, and last because seriesFilterOrder appends
-	// it there. The All filter's count belongs to the Library block, not to a
+	// The hygiene figures, in seriesFilterOrder's tail: the problem filters
+	// in permanent-then-fixable order, then the informational tail — finished
+	// and site completed — riding last because seriesFilterOrder appends them
+	// there. The All filter's count belongs to the Library block, not to a
 	// "hygiene" figure.
 	hygiene := make([]fig, 0, len(seriesFilterOrder)-1)
 	for _, name := range seriesFilterOrder[1:] {
@@ -165,28 +194,26 @@ func door(label string, count int, href string) fig {
 	return fig{Label: label, Href: href, Count: count}
 }
 
-// overviewVerdict decides the landing page's one line from the latest pass
-// per Site: no passes at all is "no Lane has reported yet" — never confident
-// zeroes; otherwise the count of Lanes whose last pass needs the owner, or
-// "all lanes healthy". The count comes from the same laneState judgement the
-// Lanes page colours on, so the two pages cannot disagree on what a fault is.
-func overviewVerdict(passes []store.LanePass, now time.Time) (phrase string, counts bool) {
+// overviewVerdict decides the landing page's one line: no passes at all is
+// "no Lane has reported yet" — never confident zeroes; otherwise the count of
+// faults from the shared FaultsFrom judgement, so the page and the push
+// cannot disagree. Zero faults is "all lanes healthy". A sidecar-down fault
+// carries Site == "" and is still one fault. The Lanes page's per-row
+// laneState is a different question (is this Lane's last pass healthy) from
+// the notice class, and its known false positives live there deliberately, so
+// the two now differ.
+func overviewVerdict(passes []store.LanePass, faults []latest.Fault) (phrase string, counts bool) {
 	if len(passes) == 0 {
 		return "no Lane has reported yet", false
 	}
-	attention := 0
-	for _, p := range passes {
-		if _, _, attn := laneState(p, now); attn {
-			attention++
-		}
-	}
-	if attention == 0 {
+	n := len(faults)
+	if n == 0 {
 		return "all lanes healthy", true
 	}
-	if attention == 1 {
+	if n == 1 {
 		return "1 lane needs a look", true
 	}
-	return fmt.Sprintf("%d lanes need a look", attention), true
+	return fmt.Sprintf("%d lanes need a look", n), true
 }
 
 // waiting sums Due over the latest pass per Site: how many Series the Lanes

backend/internal/web/admin_series.go

@@ -25,21 +25,25 @@ const seriesPageSize = 50
 // the labels are read by later admin tickets too, so the map and the
 // constants cannot drift apart.
 var seriesFilterLabels = map[string]string{
-	store.SeriesFilterAll:          "All series",
-	store.SeriesFilterNoURL:        "No series URL",
-	store.SeriesFilterNoChapter:    "Never read a chapter",
-	store.SeriesFilterNoReaders:    "No Readers",
-	store.SeriesFilterNeverChecked: "Never checked",
-	store.SeriesFilterStale:        "Not checked in 12h",
-	store.SeriesFilterNoCover:      "No cover",
-	store.SeriesFilterReaderReport: "Latest from a Reader",
-	store.SeriesFilterFinished:     "Finished",
+	store.SeriesFilterAll:           "All series",
+	store.SeriesFilterNoURL:         "No series URL",
+	store.SeriesFilterNoChapter:     "Never read a chapter",
+	store.SeriesFilterNoReaders:     "No Readers",
+	store.SeriesFilterNeverChecked:  "Never checked",
+	store.SeriesFilterStale:         "Not checked in 12h",
+	store.SeriesFilterNoCover:       "No cover",
+	store.SeriesFilterReaderReport:  "Latest from a Reader",
+	store.SeriesFilterFailing:       "Failing over 12h",
+	store.SeriesFilterUnverified:    "Unverified Reader number",
+	store.SeriesFilterFinished:      "Finished",
+	store.SeriesFilterSiteCompleted: "Site says completed",
 }
 
 // seriesFilterOrder is the select's render order: All first, then the
-// permanent repairs, then the fixable ones (issue #140). Finished rides the
-// tail, last — deliberate, not a repair — and the Overview's stats block
-// renders the same tail, which is what sits the finished figure last there.
+// permanent repairs, then the fixable ones (issue #140). Finished and the
+// site-completed hint ride the tail — deliberate, not repairs — and the
+// Overview's stats block renders the same tail, which is what sits the
+// finished and site-completed figures last there.
 var seriesFilterOrder = []string{
 	store.SeriesFilterAll,
 	store.SeriesFilterNoURL,
@@ -49,7 +53,10 @@ var seriesFilterOrder = []string{
 	store.SeriesFilterStale,
 	store.SeriesFilterNoCover,
 	store.SeriesFilterReaderReport,
+	store.SeriesFilterFailing,
+	store.SeriesFilterUnverified,
 	store.SeriesFilterFinished,
+	store.SeriesFilterSiteCompleted,
 }
 
 // seriesListView is the Series list page's data. The template renders strings
@@ -119,6 +126,11 @@ type seriesRowView struct {
 	// page, where a press that retires a Series from the Lane is on purpose
 	// and confirm-gated (issue #158).
 	Finished bool
+	// Failure names the standing failure and how long it has stood — "not
+	// found · 3d ago", "" while no failure row stands. Its own field, never a
+	// Notes chip: the chips cap at two plus a tail, so the one fact that
+	// names the failure would be the most likely to be truncated away.
+	Failure string
 }
 
 // adminSeries renders the filterable, bookmarkable Series list: filter, Site,
@@ -679,6 +691,9 @@ func seriesRow(a store.AdminSeries, i int, now time.Time) seriesRowView {
 		row.Ch = "—"
 	}
 	row.Age = checkedAge(now, a.LatestCheckedAt)
+	if a.FailureOutcome != "" {
+		row.Failure = outcomeWord(a.FailureOutcome) + " · " + checkedAge(now, a.FailingSince)
+	}
 	notes := seriesNotes(a, now)
 	if n := len(notes); n > 2 {
 		row.Notes, row.More = notes[:2], n-2
@@ -689,6 +704,20 @@ func seriesRow(a store.AdminSeries, i int, now time.Time) seriesRowView {
 	return row
 }
 
+// outcomeWord spells the wire failure word as the Lanes chips spell it — a
+// space, not the underscore: not_found reads "not found", no_chapter "no
+// chapter". The remaining words are their own spelling, so an unknown word
+// degrades to itself rather than vanishing from the page.
+func outcomeWord(wire string) string {
+	switch wire {
+	case "not_found":
+		return "not found"
+	case "no_chapter":
+		return "no chapter"
+	}
+	return wire
+}
+
 // seriesNotes are a row's hygiene chips in the design's order: no URL, no
 // cover, orphan, stale, reader sighting.
 func seriesNotes(a store.AdminSeries, now time.Time) []string {

backend/internal/web/admin_series_detail.go

@@ -64,6 +64,15 @@ type seriesDetailView struct {
 	// stands. It rides the meta fragment both presses swap, so the answer
 	// itself shows how long the Series has been finished.
 	FinishedSince string
+	// Unverified is the sentence beside the Latest Chapter correction
+	// control while a Reader's number stands behind a failure past the
+	// owner window: the value is unconfirmed and the owner should not trust
+	// it. It never names the Reader. "" otherwise.
+	Unverified string
+	// SiteCompleted is the hint's line, "" while the Site has said nothing or
+	// the owner has finished the Series: "the site says this work is
+	// completed (since 3d ago)". A hint, never a control (issue #170).
+	SiteCompleted string
 }
 
 // adminSeriesDetail renders one Series' page, keyed by the composite
@@ -151,6 +160,17 @@ func (h *Handler) seriesDetailView(a store.AdminSeries) seriesDetailView {
 	v.Corrected = correctedAge(time.Now(), a.LatestCorrectedAt)
 	v.Finished = a.FinishedAt != 0
 	v.FinishedSince = finishedAge(time.Now(), a.FinishedAt)
+	// Unverified: a Reader's number standing behind a failure that has outlived
+	// the owner window is a number nobody has re-checked since — say so next to
+	// the correction control, without naming the Reader. A machine read or a
+	// failure still inside the window carries no sentence; the failure itself
+	// has not yet outlived the twelve hours' worth of trust.
+	if a.RaisedByReader && a.FailureOutcome != "" && a.FailingSince < time.Now().Add(-ownerWindow).UnixMilli() {
+		v.Unverified = "Unverified Reader number: the page has been failing for over 12h, so this Reader-reported chapter is unconfirmed."
+	}
+	if a.SiteCompletedAt != 0 && a.FinishedAt == 0 {
+		v.SiteCompleted = "the site says this work is completed (since " + checkedAge(time.Now(), a.SiteCompletedAt) + ")"
+	}
 
 	// Provenance: the actor class behind the current number, evaluated in the
 	// order the classes outrank one another — the owner's stamp, which a

backend/internal/web/templates/lanes.html

@@ -26,7 +26,7 @@
     </div>
     {{range .Rows}}
     <div class="trow{{if .Attention}} attention{{end}}">
-      <span class="c-site">{{.Site}}</span>
+      <a class="c-site" href="{{.FailingHref}}">{{.Site}}</a>
       <span>{{.Due}}</span>
       <span>{{.Checked}}</span>
       <span>{{.Gap}}</span>

backend/internal/web/templates/series-detail.html

@@ -19,6 +19,7 @@
       <input type="number" name="chapter" step="any" placeholder="{{.Chapter}}" required>
       <button type="submit" class="ghost">Set</button>
     </div>
+    {{if .Unverified}}<p class="hint">{{.Unverified}}</p>{{end}}
   </form>
   <form class="dform" hx-post="/admin/series/{{.Key}}/series-url" hx-target="#detail-meta" hx-swap="outerHTML">
     <h3>Repair series URL</h3>
@@ -46,6 +47,7 @@
 {{else}}
 <div class="dform">
   <div class="field"><button type="button" class="ghost" onclick="document.getElementById('confirm-finish').hidden = false">Finish</button></div>
+  {{if .SiteCompleted}}<p class="hint">{{.SiteCompleted}}</p>{{end}}
   <div class="confirm-row calm" id="confirm-finish" role="group" aria-live="polite" hidden>
     <span>Mark this Series finished?</span>
     <div>

backend/internal/web/templates/series-list.html

@@ -47,7 +47,7 @@
   <span class="c-ch">{{.Ch}}</span>
   <span>{{.Age}}</span>
   <span class="c-rd">{{.Readers}}</span>
-  <span class="c-note">{{range .Notes}}<span class="mark">{{.}}</span>{{end}}{{if .More}}<span class="mark mark-faint">+{{.More}}</span>{{end}}{{if .Finished}}<span class="mark mark-faint">finished</span>{{end}}</span>
+  <span class="c-note">{{if .Failure}}<span class="mark">{{.Failure}}</span>{{end}}{{range .Notes}}<span class="mark">{{.}}</span>{{end}}{{if .More}}<span class="mark mark-faint">+{{.More}}</span>{{end}}{{if .Finished}}<span class="mark mark-faint">finished</span>{{end}}</span>
   <span class="c-act">{{if .CanPoll}}<a class="ghost act" hx-post="/admin/series/{{.Key}}/poll" hx-target="closest .trow" hx-swap="outerHTML" hx-vals='{"band":{{if .Band}}1{{else}}0{{end}}}' href="#">Check now</a>{{end}}{{if .CanRemove}}<button class="ghost danger" hx-post="/admin/series/{{.Key}}/remove" hx-target="closest .trow" hx-swap="outerHTML" hx-include="#filterbar" hx-vals='{"band":{{if .Band}}1{{else}}0{{end}}}' hx-confirm="Removes this series and its stored cover. No Reader has it bookmarked; one re-bookmarking it recreates the row.">Remove</button>{{end}}</span>
   {{if .RemovalRefused}}<span class="row-msg">a Reader has bookmarked this Series again</span>{{end}}
 </div>