Live camera view in the app, and the green light that was lying about it

Two changes, and the second was found by verifying the first.

## Watching a camera from the app, in another building

Snapshots answer "is that camera working". They do not answer "what is
happening in my shop right now", which is what somebody who opens the app away
from the counter is asking. Head office's browser already had that answer -
LiveHub plus cameras.Live, where the shop PC asks outbound whether anybody is
watching and pushes JPEG frames for as long as somebody is - and the app could
not reach it.

cloud.CameraLive opens that feed and the app's own loopback relay re-emits it
as multipart MJPEG. That is the trick: frames arrive base64 over SSE, an <img>
cannot render that, and an <img> renders MJPEG natively - so a tile is an
ordinary <img> pointed at loopback whether the camera is in this room or
another city.

- Reconnecting happens in the relay, not the page. The server caps one push at
  five minutes, so doing it here means the <img> never sees the stream end.
- The headers are flushed before the first frame. Go writes them on the first
  body write, so without that the whole response waits for the shop PC to
  start pushing. Measured against production: 30 seconds and not even a
  Content-Type, which surfaces as the request timing out.
- One camera at a time. Watching makes a shop PC upload, so a grid that went
  live at once would put an estate's worth of cameras on the wire because
  somebody opened a page.
- live.mjpeg is behind the same per-run token as the engine routes, and a
  wrong token is a 404 that never reaches head office at all.
- CameraLive uses its own HTTP client: the shared one's 30s timeout covers the
  whole response and would sever a working view every thirty seconds - the
  trap that made the server set WriteTimeout to zero for its own SSE endpoint.

## A camera read "Connected" for 34 minutes after the shop PC went blind

Which is why the verification above looked like a failure: head office
registered the viewer and no frame ever came.

reportWith returns early when the engine is unreachable - correctly, it has
nothing to say - so the last state it sent stays in the database looking
current. Measured live: cam2 and entrance both reading Connected, in green,
with last_seen_at 34 minutes old, while the heartbeat from the same PC said
cameras_up 0 of 0. Two surfaces reading two stored fields and disagreeing.

false could not be the answer. It means "this camera is not connecting", which
sends an installer to check cabling on a camera that was working perfectly the
last time anybody could ask it. So there are four states and one function:

  connected       reported recently, and working
  not_connecting  reported recently, and the stream will not open
  waiting         no shop PC has ever reported this camera
  stale           reported once, and not lately

- Connected is CLEARED when stale or waiting. A stale true left in place stays
  available to every client reading the field directly, and leaves two fields
  on one object disagreeing - how the shops screen once came out labelled
  Working, in green, above "2 of 3 cameras not connecting".
- Computed in scanCamera, so every camera anybody reads passes through it. A
  state computed per handler is one a handler forgets, and this had already
  reached three screens.
- CameraStaleAfter is 5 minutes: five missed reports, not one. Same reasoning
  as three missed heartbeats - an indicator that cries wolf gets ignored.
- An unparseable last_seen_at is stale. It should be impossible, which is why
  it must not fall through to the state that says everything is fine.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KGcjxF1cNLcuwc3DAPcnfj

server/internal/api/camera_state_test.go

@@ -0,0 +1,96 @@
+package api
+
+import (
+	"testing"
+	"time"
+)
+
+func ptr(b bool) *bool { return &b }
+
+// The state this was written for. Two cameras read "Connected", in green, on
+// the live estate thirty-four minutes after the shop computer had stopped
+// being able to see either of them - because the agent correctly reports
+// nothing when it cannot reach the engine, and the last value it sent stays
+// in the database looking current.
+func TestAStaleReportIsNotAConnectedCamera(t *testing.T) {
+	now := time.Date(2026, 9, 30, 11, 13, 0, 0, time.UTC)
+	c := Camera{Connected: ptr(true),
+		LastSeenAt: now.Add(-34 * time.Minute).Format(time.RFC3339)}
+	c.CameraState(now)
+
+	if c.State != CameraStale {
+		t.Errorf("state = %q, want %q", c.State, CameraStale)
+	}
+	// Cleared, not merely overruled. A stale true left in place stays
+	// available to every client that reads the field directly, and leaves two
+	// fields on one object disagreeing.
+	if c.Connected != nil {
+		t.Errorf("connected = %v, want null - nobody currently knows", *c.Connected)
+	}
+	if c.StateNote == "" {
+		t.Error("a stale camera said nothing about what to do")
+	}
+}
+
+// One missed report is a dropped packet. Warning on it would put an alarm on a
+// healthy estate every few minutes, and an indicator that cries wolf is one
+// people learn to ignore.
+func TestOneMissedReportIsStillConnected(t *testing.T) {
+	now := time.Now()
+	c := Camera{Connected: ptr(true),
+		LastSeenAt: now.Add(-90 * time.Second).Format(time.RFC3339)}
+	c.CameraState(now)
+	if c.State != CameraConnected {
+		t.Errorf("state = %q after 90s, want %q", c.State, CameraConnected)
+	}
+	if c.Connected == nil || !*c.Connected {
+		t.Error("a fresh report lost its connected flag")
+	}
+}
+
+// "Nobody has ever told us" and "nobody has told us lately" need different
+// sentences: the first is a camera head office added a minute ago and the
+// shop computer has not picked up, the second is a shop computer that has
+// stopped. Sending an installer to the wrong one wastes a journey.
+func TestNeverReportedIsNotTheSameAsStopped(t *testing.T) {
+	now := time.Now()
+	var never Camera
+	never.CameraState(now)
+	if never.State != CameraWaiting {
+		t.Errorf("state = %q, want %q", never.State, CameraWaiting)
+	}
+
+	stopped := Camera{LastSeenAt: now.Add(-time.Hour).Format(time.RFC3339)}
+	stopped.CameraState(now)
+	if stopped.State == never.State {
+		t.Fatal("a camera nobody has reported and one that stopped read the same")
+	}
+	if stopped.StateNote == never.StateNote {
+		t.Error("two states that need different actions gave the same advice")
+	}
+}
+
+// A camera the shop computer CAN see and cannot open is the one case where
+// "check the cabling" is the right advice, and it must stay distinguishable
+// from the three where it is not.
+func TestAFreshFailureSaysCheckTheCamera(t *testing.T) {
+	now := time.Now()
+	c := Camera{Connected: ptr(false), LastSeenAt: now.Format(time.RFC3339)}
+	c.CameraState(now)
+	if c.State != CameraNotConnect {
+		t.Errorf("state = %q, want %q", c.State, CameraNotConnect)
+	}
+	if c.Connected == nil || *c.Connected {
+		t.Error("a reported failure must stay false, not become unknown")
+	}
+}
+
+// An unparseable timestamp is not a working camera. It should not be possible,
+// which is exactly why it must not fall through to "connected".
+func TestAnUnreadableTimestampIsStale(t *testing.T) {
+	c := Camera{Connected: ptr(true), LastSeenAt: "not a time"}
+	c.CameraState(time.Now())
+	if c.State != CameraStale || c.Connected != nil {
+		t.Errorf("state = %q connected = %v, want stale and unknown", c.State, c.Connected)
+	}
+}

server/internal/api/types.go

@@ -655,6 +655,11 @@ type Camera struct {
 	Snapshot   Image  `json:"snapshot"`
 	SnapshotAt string `json:"snapshot_at,omitempty"`
 
+	// State is the ONE answer a screen should render, because there are four
+	// of them and only three were ever expressed. See CameraState.
+	State     string `json:"state"`
+	StateNote string `json:"state_note,omitempty"`
+
 	// Check is the last attempt to prove this camera works. Always present so
 	// a client can tell "never checked" from "checked and failed" without
 	// guessing from an absent field.
@@ -962,3 +967,70 @@ type DeviceSession struct {
 	// hand.
 	Current bool `json:"current"`
 }
+
+// Camera states, and why a fourth one had to exist.
+//
+// A shop computer reports each camera's state about once a minute. When it
+// cannot reach the recognition engine it reports NOTHING - correctly, because
+// it has nothing to say - and the last value it sent stays in the database
+// unchanged. Measured on the live estate: two cameras reading **Connected**,
+// in green, thirty-four minutes after the shop computer had stopped being
+// able to see either of them, while the heartbeat from the same PC said
+// 0 of 0 cameras. Both surfaces were reading stored fields and disagreeing.
+//
+// `false` could not be the answer. It means "this camera is not connecting",
+// which sends an installer to check cabling on a camera that was working
+// perfectly the last time anybody could ask it. The honest statement is that
+// nobody currently knows - and that is a different sentence from "nobody has
+// ever told us", which is what an unreported camera needs. Two states that
+// need different actions must never share a word; the same rule that keeps
+// `artifact` apart from `no_faces` in the commissioning verdicts.
+const (
+	CameraConnected  = "connected"      // reported recently, and working
+	CameraNotConnect = "not_connecting" // reported recently, and not
+	CameraWaiting    = "waiting"        // no shop computer has ever reported
+	CameraStale      = "stale"          // reported once, and not lately
+)
+
+// CameraStaleAfter is five missed reports, not one.
+//
+// The agent reports on a 60 s tick, so one miss is a dropped packet or a slow
+// upload. Calling that stale would put a warning on a healthy estate every few
+// minutes, and an indicator that cries wolf is one people learn to ignore -
+// which is the same reasoning that makes a site offline after three missed
+// heartbeats rather than one.
+const CameraStaleAfter = 5 * time.Minute
+
+// CameraState decides the four states, and nulls Connected when it is not
+// entitled to an opinion.
+//
+// Connected is CLEARED rather than left alone on purpose. Leaving a stale true
+// in place would keep the lie available to every client that reads the field
+// directly - a mobile app, a script, an older build of our own desktop app -
+// and would leave two fields on one object disagreeing, which is precisely how
+// the shops screen once came out labelled Working in green above "2 of 3
+// cameras not connecting".
+func (c *Camera) CameraState(now time.Time) {
+	switch {
+	case c.LastSeenAt == "":
+		c.State = CameraWaiting
+		c.StateNote = "No shop computer has reported on this camera yet."
+		c.Connected = nil
+		return
+	}
+	seen, err := time.Parse(time.RFC3339, c.LastSeenAt)
+	if err != nil || now.Sub(seen) > CameraStaleAfter {
+		c.State = CameraStale
+		c.StateNote = "The shop computer has stopped reporting this camera. " +
+			"Check that the computer is on and Behavision is running on it."
+		c.Connected = nil
+		return
+	}
+	if c.Connected != nil && *c.Connected {
+		c.State = CameraConnected
+		return
+	}
+	c.State = CameraNotConnect
+	c.StateNote = "The shop computer cannot open this camera's stream. " +
+		"Check the address, the password and the cabling."
+}

server/internal/store/api_cameras.go

@@ -59,6 +59,11 @@ func scanCamera(row pgx.Row) (api.Camera, error) {
 	// The KEY travels in ImageKey, which is json:"-", and the handler swaps it
 	// for a signed link. Same rule as an arrival's face.
 	c.Snapshot.Key = snapKey
+	// Here rather than in a handler, because every camera anybody reads comes
+	// through this function and a state computed per caller is a state one
+	// caller forgets - which is how a stale `connected` reached three screens
+	// at once.
+	c.CameraState(time.Now())
 	return c, nil
 }
 

server/internal/web/dist/index.html

@@ -6,7 +6,7 @@
     <meta name="color-scheme" content="dark" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     <title>Behavision</title>
-    <script type="module" crossorigin src="/assets/index-Ckr5hGZd.js"></script>
+    <script type="module" crossorigin src="/assets/index-BuVkBNdU.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-D4KGRSVS.css">
   </head>
   <body>