Docs refresh: architecture, agents and README reflect what was built (Maestro 3b22e48b) (#214)

Co-authored-by: orchestrator-agent <20+orchestrator-agent@code.cubecraftcreations.com>

AGENTS.md

@@ -78,17 +78,18 @@ behaviour, exercise it (hit the endpoint, render the page).
 | Path | Purpose |
 | --- | --- |
 | `cmd/server` | Entry point. Wiring only — no business logic. |
+| `cmd/vapidgen` | Prints a new VAPID key pair for Web Push. |
 | `internal/config` | `MEALQUEST_*` environment config; secrets from `*_FILE`. |
 | `internal/server` | HTTP server, routes, `/health`. |
 | `internal/frontend` | `go:embed` of the built PWA with SPA fallback. |
-| `internal/*` (planned) | `auth`, `db`, `store`, `secretbox`, `household`, `dinners`, `recipes`, `ai/llm`, `ai/harness`, `ai/skills`, `suggest`, `plan`, `shopping`, `ideas`, `gcal`, `notify`, `push`, `chat`, `jobs`, `scheduler`. |
-| `migrations/` | SQL migrations (planned). |
+| `internal/*` | `auth`, `forwarded`, `secureurl`, `db`, `store`, `secretbox`, `household`, `dinners`, `recipes`, `ai/llm`, `ai/harness`, `ai/skills`, `ai/aisettings`, `suggest`, `plan`, `shopping`, `ideas`, `home`, `gcal`, `notify`, `push`, `chat`, `vapid`, `jobs`, `scheduler` — one line each in [ARCHITECTURE.md](docs/ARCHITECTURE.md#repository-layout). |
+| `migrations/` | SQL migrations, embedded and applied at boot by `internal/store`; sqlc queries in `migrations/queries/`. |
 | `web/` | React PWA source. |
-| `deploy/` | Deployment files (planned). |
+| `deploy/` | Deployment files: compose stack, systemd units, [deploy runbook](deploy/RUNBOOK.md) and the automated deploy (`auto-deploy.sh` with `systemd/mealquest-auto-deploy.*`). |
 | `docs/` | Project documentation, including [ARCHITECTURE.md](docs/ARCHITECTURE.md). |
 | `design/` | Requirements and UI handoff. **Read-only reference** — do not edit. |
 | `Dockerfile` | Multi-stage image build, at the repository root. |
-| `Makefile` | `dev`, `test`, `build`, `docker`. |
+| `Makefile` | `dev`, `test`, `build`, `docker`; `sqlc` and `sqlc-check` regenerate and check `internal/db`. |
 | `.gitea/workflows/ci.yml` | CI quality floor. |
 
 Design references:
@@ -104,7 +105,10 @@ Design references:
 - **Task branches:** `task/<slug>_<task-uuid>`, branched from the feature branch.
 - Task pull requests **squash-merge into the feature branch**.
 - The feature pull request merges into `dev`.
-- **Only `overseer` merges `dev` → `main`** (a release).
+- **Only `overseer` merges `dev` → `main`** (a release). On the production
+  host, `mealquest-auto-deploy.timer` then deploys the new `main` once its
+  CI passes ([deploy/RUNBOOK.md](deploy/RUNBOOK.md) "Automated deploys");
+  nothing deploys `dev` or a feature branch.
 - Never push directly to `dev` or `main`.
 - Authors never review, approve, merge or close their own work.
 - Never store credentials in the repository; environment or ignored files only.

README.md

@@ -7,9 +7,27 @@ builds a weekly plan, pushes it to Google Calendar, and generates a shopping
 list grouped by dinner, kept as a browsable weekly history. It ships as a
 single Go service with the React PWA embedded in the binary.
 
-> Status: this repository is the Feature 01 scaffold (Go service with
-> `/health`, embedded PWA skeleton, Makefile, Dockerfile, CI). The planned
-> application is described in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Production runs at <https://mealquest.cubecraftlabs.com> for one household,
+signed in through Authentik.
+
+## Stack
+
+- **Backend:** Go 1.25 (`CGO_ENABLED=0`, one static binary), chi router,
+  SQLite through `modernc.org/sqlite` with sqlc queries and embedded
+  migrations, Authentik OIDC, `log/slog`. AI calls go to an
+  OpenAI-compatible, Anthropic or Ollama endpoint over plain HTTP; recipes
+  come from SearXNG or Brave search and the recipe page's schema.org data.
+  Google Calendar, Google Chat and Web Push are the integrations.
+- **Frontend:** React 19, TypeScript, Vite, React Router 7, TanStack Query 5,
+  `vite-plugin-pwa`, CSS Modules over the design tokens; tests with Vitest,
+  Testing Library and jsdom.
+- **Deployment:** a Docker Compose stack (the service, Litestream
+  replication to the NAS, a SearXNG sidecar) behind Traefik, with systemd
+  units for the firewall, nightly media backup and the automated deploy of
+  `main`.
+
+The approved dependency list is in [AGENTS.md](AGENTS.md); nothing else is
+added without the owner's approval.
 
 ## Running it locally
 
@@ -28,6 +46,15 @@ invalid variable.
 | `make test`    | `gofmt` check, `go vet`, `go test -race`, web typecheck and tests. |
 | `make build`   | Build the PWA, embed it, build the static binary `bin/mealquest`. |
 | `make docker`  | Build the container image from the root `Dockerfile`.           |
+| `make sqlc-check` | Regenerate `internal/db` with sqlc and fail if it drifted.   |
+
+## Deploying and operating
+
+[deploy/RUNBOOK.md](deploy/RUNBOOK.md) is the deploy runbook: build, ship and
+restart, verifying the deployed version, rollback and the automated deploy.
+Database restore, the boot configuration and other host procedures are in
+CTXD: project `mealquest`, file `RUNBOOKS.MD`. Only `overseer` releases, by
+merging `dev` into `main`.
 
 ## Where to read next
 

cmd/server/main.go

@@ -23,6 +23,7 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/gcal"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/home"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ideas"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
@@ -30,6 +31,7 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/plan"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/push"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/server"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/shopping"
@@ -129,7 +131,12 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
-	dinnerSvc, err := dinners.NewService(db, grounder, runner, logger)
+	// The scheduler is made before the services whose changes wake it.
+	sched, err := scheduler.New(db, settings, logger)
+	if err != nil {
+		return err
+	}
+	dinnerSvc, err := dinners.NewService(db, grounder, runner, sched.Wake, logger)
 	if err != nil {
 		return err
 	}
@@ -151,7 +158,7 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
-	planSvc, err := plan.NewService(db, weekDrafter(ai, guard), runner, googleSvc, notifier, cfg.PublicURL, logger)
+	planSvc, err := plan.NewService(db, weekDrafter(ai, guard), runner, googleSvc, notifier, sched.Wake, cfg.PublicURL, logger)
 	if err != nil {
 		return err
 	}
@@ -171,6 +178,11 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
+	homeSvc, err := home.NewService(settings, planSvc, suggestSvc, shopSvc, notifier)
+	if err != nil {
+		return err
+	}
+
 	sessions, err := auth.NewSessionManager(db, cfg.SessionIdle, cfg.SessionMax)
 	if err != nil {
 		return err
@@ -187,17 +199,46 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
-	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, search, ai, chatSvc, dinnerSvc, suggestSvc, planSvc, shopSvc, googleSvc, pushSvc, ideasSvc, runner, photos, frontend.Assets())
+	if err := sched.Register(suggestSvc.WeeklySchedule()); err != nil {
+		return err
+	}
+	if err := sched.Register(planSvc.DraftSchedule()); err != nil {
+		return err
+	}
+	for _, sch := range planSvc.ReminderSchedules() {
+		if err := sched.Register(sch); err != nil {
+			return err
+		}
+	}
+	if err := sched.Register(planSvc.RotationCheckSchedule()); err != nil {
+		return err
+	}
+	if err := sched.Register(shopSvc.ChatAutosendSchedule()); err != nil {
+		return err
+	}
+	if err := sched.Register(shopSvc.RolloverSchedule()); err != nil {
+		return err
+	}
+	purge, err := harness.PurgeSchedule(db, logger)
+	if err != nil {
+		return err
+	}
+	if err := sched.Register(purge); err != nil {
+		return err
+	}
+
+	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, search, ai, chatSvc, dinnerSvc, suggestSvc, planSvc, shopSvc, googleSvc, pushSvc, ideasSvc, homeSvc, runner, photos, frontend.Assets())
 	if err != nil {
 		return err
 	}
 
 	// Start fails the jobs a previous process left running before any
-	// worker runs. The job workers and the notification worker stop, and
-	// are waited for, before the database closes.
+	// worker runs. The job workers, the notification worker and the
+	// scheduler stop, and are waited for, before the database closes.
 	workersCtx, stopWorkers := context.WithCancel(ctx)
 	defer func() {
 		stopWorkers()
+		sched.Wait()
 		runner.Wait()
 		notifier.Wait()
 	}()
@@ -213,6 +254,11 @@ func run(cfg config.Config, logger *slog.Logger) error {
 	if _, err := dinnerSvc.FailInterruptedGroundings(ctx); err != nil {
 		return err
 	}
+	// The scheduler starts last: its catch-up may enqueue jobs and
+	// notifications, so their workers must already run.
+	if err := sched.Start(workersCtx); err != nil {
+		return err
+	}
 	srv := &http.Server{
 		Addr:              cfg.HTTPAddr,
 		Handler:           router,

deploy/RUNBOOK.md

@@ -0,0 +1,357 @@
+# MealQuest deploy runbook
+
+The one way to deploy MealQuest to production: the docker compose project
+`mealquest` on office-srvr `10.60.1.14` (see
+[ARCHITECTURE.md](../docs/ARCHITECTURE.md#topology)). Production runs `main`
+or a release tag; only `overseer` merges `dev` → `main`. Every deploy builds
+on the host, from the checked-out commit, with `make docker`.
+
+Host setup (clone, firewall, the systemd unit, Traefik, DNS, Litestream) and
+the database restore are in CTXD project `mealquest`, `RUNBOOKS.MD`. This
+file is the build, restart, verification and rollback procedure; where it
+uses a CTXD section, it names it.
+
+All commands run on `10.60.1.14` as `overseer`, in bash, from the checkout
+`/home/overseer/mealquest`. A block that ends with `FAILED` or a non-zero
+`$?` stops the deploy: do not go on to the next step.
+
+## How the image carries its version
+
+`make docker` runs `docker build --build-arg VERSION=<version>` and tags the
+image `mealquest:<version>`, where `<version>` is
+`git describe --tags --always` of the checkout (a release tag such as
+`v1.0.0`, otherwise the short SHA), with `-dirty` added when a tracked file
+is modified. The [Dockerfile](../Dockerfile) links it into the binary, and
+`/health` reports it:
+
+```json
+{"status":"ok","version":"v1.0.0"}
+```
+
+Never pass `--build-arg VERSION` by hand, and never build with
+`docker compose build` or `docker compose up --build`: compose passes no
+version, so that image reports `dev`.
+
+The compose service `mealquest` runs the image named `mealquest-mealquest`
+(compose's name for the image it would build; check with
+`docker compose -f deploy/compose.yaml config --images mealquest`). It
+already exists, so `docker compose up` uses it and never builds. A deploy
+points that name at the `make docker` image with `docker tag`. Every
+`mealquest:<version>` image is kept for rollback; do not prune them.
+
+## Prerequisites
+
+- `make`, `git`, `curl`, `python3` and Docker Engine with Compose on the
+  host (`make` is not in the base install: `sudo apt-get install make`).
+- `deploy/.env` (git-ignored, owner `overseer`, mode 0600) sets every
+  variable [`deploy/.env.example`](.env.example) sets, with
+  `MEALQUEST_BIND_ADDRESS=10.60.1.14`. It must not set the variables
+  `deploy/compose.yaml` fixes (`MEALQUEST_HTTP_ADDR`, `MEALQUEST_DATA_DIR`,
+  `MEALQUEST_SEARXNG_URL` and the `*_FILE` variables). Creating it: CTXD
+  `RUNBOOKS.MD` "Stack and first deploy" > "3. Environment file".
+- `deploy/secrets/` (git-ignored, mode 0700) holds `secret_key`,
+  `oidc_client_secret`, `google_client_secret`, `vapid_private_key` and
+  `litestream_key`, each owned by `10001:10001` with mode 0600, and
+  `searxng.env`, owned by `overseer` with mode 0600. Creating them: CTXD
+  `RUNBOOKS.MD` "Stack and first deploy" > "4. Secrets".
+- The compose file is the checkout's [`deploy/compose.yaml`](compose.yaml);
+  the systemd unit [`mealquest.service`](systemd/mealquest.service) starts
+  and stops it and is the only way the stack starts.
+- DNS and Traefik already route `https://mealquest.cubecraftlabs.com` to
+  `10.60.1.14:8090` (CTXD `RUNBOOKS.MD` "Reverse proxy (Traefik)", "DNS").
+
+Check `deploy/.env` and the secrets before every deploy (a new release may
+add a variable; the service refuses to boot without it). Both commands must
+print nothing:
+
+```sh
+cd /home/overseer/mealquest
+comm -23 <(grep -oE '^MEALQUEST_[A-Z_]+' deploy/.env.example | sort -u) \
+         <(grep -oE '^MEALQUEST_[A-Z_]+' deploy/.env | sort -u)   # variables missing from deploy/.env
+sudo find deploy/secrets -type f ! -perm 600                       # secrets not mode 0600
+```
+
+## Deploy
+
+### 1. Build
+
+Record the release production is running now, check out the new release
+and build its image. Nothing restarts.
+
+The rollback target is the version the running service reports on
+`/health`, read before the checkout changes, never the checkout's `HEAD`:
+after a failed or deferred deploy the checkout can be ahead of production.
+The block resolves that version to a commit and prints it as the rollback
+SHA. A running version of `dev` or `*-dirty` names no commit: the block
+fails, and the rollback target must be established by hand before going on.
+
+The checkout must be clean (the same test as the Makefile's `GIT_DIRTY`:
+no modified tracked file outside the generated `internal/frontend/dist`).
+The block computes the image tag exactly as `make docker` does, `-dirty`
+included, and checks that image exists after the build.
+
+```sh
+cd /home/overseer/mealquest && (
+set -euo pipefail
+fail() { echo "$*" >&2; exit 1; }
+built=
+trap 'st=$?
+if [ "$st" -eq 0 ] && [ -n "$built" ]; then echo "built: $built"
+else [ "$st" -ne 0 ] || st=1; echo "build FAILED (status $st)" >&2; fi
+exit "$st"' EXIT
+bind=$(grep -E '^MEALQUEST_BIND_ADDRESS=' deploy/.env | cut -d = -f 2-)
+[ -n "$bind" ] || fail "deploy/.env sets no MEALQUEST_BIND_ADDRESS"
+running=$(curl -fsS "http://$bind:8090/health" | python3 -c 'import json, sys; print(json.load(sys.stdin)["version"])') \
+  || fail "http://$bind:8090/health did not return a version: no running release to roll back to"
+case "$running" in
+  dev|*-dirty) fail "the running release reports $running, which names no commit" ;;
+esac
+git fetch --tags origin
+rollback=$(git rev-parse --verify --quiet "$running^{commit}") \
+  || fail "running version $running is not a commit in this repository"
+echo "rollback SHA: $rollback (running version $running)"   # RECORD it for rollback
+git checkout --detach "refs/remotes/origin/main^{commit}"   # or the release tag, e.g. v1.0.0
+dirty=$(git status --porcelain --untracked-files=no -- . ':(exclude)internal/frontend/dist')
+[ -z "$dirty" ] || fail "the checkout has modified tracked files; clean it first:
+$dirty"
+v=$(git describe --tags --always)${dirty:+-dirty}   # the Makefile's VERSION
+make docker
+docker image inspect "mealquest:$v" > /dev/null 2>&1 || fail "no image mealquest:$v: the build failed"
+built="mealquest:$v"
+)
+```
+
+### 2. Ship and restart
+
+1. **Pre-restart gates.** Run CTXD `RUNBOOKS.MD` "Routine deploy and
+   rollback" > "Deploy" step 2 (a verified pre-deploy restore point; record
+   it with the rollback SHA) and step 3 (boot-required configuration). The
+   restart applies migrations the previous release refuses, so without that
+   restore point there is no rollback. If either fails, do not restart:
+   production stays on the previous release.
+2. **Point the stack at the new image and restart.** `docker compose pull`
+   fetches the pinned `litestream` and `searxng` images before anything
+   stops; `mealquest` is never pulled. The restart applies the firewall,
+   then runs `down` and `up -d`, and returns once `mealquest` passes its
+   healthcheck (`/health` inside the container).
+
+```sh
+cd /home/overseer/mealquest && (
+set -euo pipefail
+fail() { echo "$*" >&2; exit 1; }
+up=
+trap 'st=$?
+if [ "$st" -eq 0 ] && [ -n "$up" ]; then echo "restarted on: $up"
+else [ "$st" -ne 0 ] || st=1; echo "restart FAILED (status $st)" >&2; fi
+exit "$st"' EXIT
+v=$(git describe --tags --always)
+docker compose -f deploy/compose.yaml pull litestream searxng
+docker tag "mealquest:$v" mealquest-mealquest
+sudo systemctl restart mealquest
+for s in mealquest litestream searxng; do
+  id=$(docker compose -f deploy/compose.yaml ps --status running --quiet "$s")
+  [ -n "$id" ] || fail "$s is not running"
+done
+id=$(docker compose -f deploy/compose.yaml ps --quiet mealquest)
+health=$(docker inspect -f '{{.State.Health.Status}}' "$id")
+[ "$health" = healthy ] || fail "mealquest is $health, not healthy"
+up="mealquest:$v"
+)
+```
+
+On failure read `journalctl -u mealquest` and
+`docker compose -f deploy/compose.yaml logs mealquest`: a configuration
+error names the variable. Fix it or roll back.
+
+### 3. Verify the deployed version and a real screen
+
+A `/health` 200 alone proves only that some build is up. This step checks,
+on the LAN address and through Traefik, that:
+
+- `/health` reports exactly the checkout's `git describe --tags --always`;
+- `/` and the Plan screen's route `/plan` serve the built PWA shell (the
+  React root and a hashed `/assets/` script, not the placeholder page an
+  unbuilt embed serves);
+- that script is served as JavaScript.
+
+```sh
+cd /home/overseer/mealquest && (
+set -euo pipefail
+fail() { echo "$*" >&2; exit 1; }
+want=
+trap 'st=$?
+if [ "$st" -eq 0 ] && [ -n "$want" ]; then echo "deployed and verified: $want ($(git rev-parse HEAD))"
+else [ "$st" -ne 0 ] || st=1; echo "verification FAILED (status $st): the deploy is not verified" >&2; fi
+exit "$st"' EXIT
+v=$(git describe --tags --always)
+for base in http://10.60.1.14:8090 https://mealquest.cubecraftlabs.com; do
+  got=$(curl -fsS "$base/health" | python3 -c 'import json, sys; print(json.load(sys.stdin)["version"])') \
+    || fail "$base/health did not return a version"
+  [ "$got" = "$v" ] || fail "$base/health reports version $got, the checkout is $v"
+  for path in / /plan; do
+    page=$(curl -fsS "$base$path") || fail "$base$path did not return 200"
+    grep -q '<div id="root"></div>' <<< "$page" || fail "$base$path is not the PWA shell"
+    js=$(grep -oE 'src="/assets/[^"]+\.js"' <<< "$page" | head -n 1 | cut -d '"' -f 2) || true
+    [ -n "$js" ] || fail "$base$path references no built /assets/ script"
+    type=$(curl -fsS -o /dev/null -w '%{content_type}' "$base$js") || fail "$base$js did not return 200"
+    case "$type" in
+      text/javascript*) ;;
+      *) fail "$base$js is $type, not JavaScript" ;;
+    esac
+  done
+  echo "$base: version $got, PWA shell and $js served"
+done
+want=$v
+)
+```
+
+- `deployed and verified: <version> (<SHA>)` and `$?` = `0` → open
+  `https://mealquest.cubecraftlabs.com` in a browser: sign in and the Home
+  screen renders with the household's data. Then record the deployed
+  version and SHA, the rollback SHA, the pre-deploy restore point and the
+  date in the release's Maestro task.
+- `verification FAILED`, any error or a non-zero `$?` → the deploy is not
+  done. A version mismatch means the stack runs a different image than the
+  checkout: repeat step 2, or roll back.
+
+## Rollback to a previous release
+
+Rolling back points `mealquest-mealquest` at the previous release's
+`mealquest:<version>` image again; that release's checkout keeps the
+compose file and the version check consistent with it.
+
+1. **Check whether the rollback crosses a migration** with CTXD
+   `RUNBOOKS.MD` "Routine deploy and rollback" > "Rollback to a previous
+   SHA" (its first block), run against the rollback SHA that deploy step 1
+   recorded. If it prints versions unknown to the rollback SHA, restore the
+   database to the pre-deploy restore point first (CTXD `RUNBOOKS.MD`
+   "Restore the database", with `-timestamp <restore point>`); changes
+   since then are lost, so tell the household.
+2. **Check out the rollback SHA and retag its image.** An image built before
+   this runbook was not tagged `mealquest:<version>`; `make docker` builds
+   it from the same commit.
+
+```sh
+cd /home/overseer/mealquest && (
+set -euo pipefail
+fail() { echo "$*" >&2; exit 1; }
+P=<rollback SHA>   # recorded by step 1, from the running release's /health
+back=
+trap 'st=$?
+if [ "$st" -eq 0 ] && [ -n "$back" ]; then echo "rolled back to: $back"
+else [ "$st" -ne 0 ] || st=1; echo "rollback FAILED (status $st)" >&2; fi
+exit "$st"' EXIT
+git checkout --detach "$P"
+v=$(git describe --tags --always)
+docker image inspect "mealquest:$v" > /dev/null 2>&1 || make docker
+docker image inspect "mealquest:$v" > /dev/null 2>&1 || fail "no image mealquest:$v"
+docker tag "mealquest:$v" mealquest-mealquest
+sudo systemctl restart mealquest
+back="mealquest:$v"
+)
+```
+
+3. **Run step 3 above** unchanged. The rollback is done only when it prints
+   `deployed and verified:` with the previous release's version.
+
+## Automated deploys
+
+[`auto-deploy.sh`](auto-deploy.sh), installed as
+`/usr/local/sbin/mealquest-auto-deploy`, runs this runbook's deploy unattended:
+step 1 (build), the prerequisite `deploy/.env` and secrets check, CTXD
+`RUNBOOKS.MD` "Deploy" steps 2 (pre-deploy restore point) and 3
+(boot-required configuration), step 2 (ship and restart) and step 3
+(verify). No check is skipped or weakened, and it stops at the first
+failure. Every failure before the restart leaves production on the previous
+release.
+
+### What runs, and when
+
+[`mealquest-auto-deploy.timer`](systemd/mealquest-auto-deploy.timer) starts
+[`mealquest-auto-deploy.service`](systemd/mealquest-auto-deploy.service)
+at every quarter hour (`OnCalendar=*-*-* *:0/15:00`), plus up to 5 minutes'
+random delay; a check missed while the host was down runs as soon as it is
+back (`Persistent=true`). The service runs the script as `overseer` from the
+checkout, and only while `mealquest.service` is active: a stack stopped on
+purpose (a database or media restore) is skipped, not redeployed. Output goes
+to the journal (`journalctl -u mealquest-auto-deploy`).
+
+Each run fetches `origin` and compares `origin/main` with the last
+`deployed=` SHA in the deploy record `/home/overseer/mealquest-auto-deploy.log`:
+
+| `origin/main` | Result |
+| --- | --- |
+| is the last deployed SHA | No-op: exit 0, no output. |
+| CI (Gitea commit status) `pending` | Exit 0, no output; the next run checks again. |
+| CI `failure`, `error`, `warning`, or no status yet | Error in the journal, exit 1, nothing deployed. |
+| the last record line is `FAILED` for this SHA | Error in the journal, exit 1, nothing deployed: a failed deploy is never retried by the timer. |
+| CI `success` | Deploy. |
+
+The CI status is read from
+`https://code.cubecraftlabs.com/api/v1/repos/Maniacs_Mansion/MealQuest/commits/<SHA>/status`
+(public; no credential). A commit merged moments before a run can briefly
+report no status, which fails that run; the next run reads it again.
+
+A deploy appends one line to the record:
+
+```text
+2026-10-12T15:04:05Z previous=<rollback SHA> deployed=<SHA> restore_point=2026-10-12T15:01:59Z
+```
+
+`previous` is the rollback SHA (from the running release's `/health`,
+never the checkout) and `restore_point` the verified pre-deploy restore
+point: record both in the release's Maestro task. A failed deploy appends
+`<date> FAILED target=<SHA> status=<exit status>` and logs
+`auto-deploy FAILED (status <n>)` to the journal, adding whether it failed
+before the restart (production untouched) or after it (read
+`journalctl -u mealquest`, then fix or roll back). Either way the checkout is
+left at the target commit; the running release on `/health` stays the
+rollback target.
+
+### Install on the host
+
+The script and units are installed copies: repeat this whenever a release
+changes `deploy/auto-deploy.sh` or the units. From the checkout, at a release
+that contains them:
+
+```sh
+cd /home/overseer/mealquest
+sudo install -m 0755 deploy/auto-deploy.sh /usr/local/sbin/mealquest-auto-deploy
+sudo install -m 0644 deploy/systemd/mealquest-auto-deploy.service \
+  deploy/systemd/mealquest-auto-deploy.timer /etc/systemd/system/
+sudo systemctl daemon-reload
+```
+
+The timer refuses to deploy until the record holds a deploy, so seed it with
+one manual deploy of the release production should run (below), then start
+the timer:
+
+```sh
+sudo /usr/local/sbin/mealquest-auto-deploy --ref refs/remotes/origin/main
+sudo systemctl enable --now mealquest-auto-deploy.timer
+systemctl list-timers mealquest-auto-deploy.timer
+```
+
+To stop automated deploys: `sudo systemctl disable --now mealquest-auto-deploy.timer`.
+
+### Manual override
+
+```sh
+sudo /usr/local/sbin/mealquest-auto-deploy --ref <ref>
+```
+
+deploys an explicit ref (a SHA, tag or `origin/<branch>`) through the same
+blocks, bypassing the CI and no-op gates: for a roll-forward fix, a re-run
+after a `FAILED` record, or seeding the record. Run as root, the script
+re-executes itself as `overseer`; it holds a lock, so it never runs alongside
+the timer's run. It prints `deployed and verified:` and exits 0 only when
+step 3 passed.
+
+### Rollback
+
+Rollback is not automated: follow "Rollback to a previous release" above
+and CTXD `RUNBOOKS.MD` "Routine deploy and rollback" > "Rollback to a
+previous SHA", using the `previous` SHA and `restore_point` from the record.
+The timer does not undo a manual rollback: `origin/main` is still the last
+recorded deploy, so its runs are no-ops until `main` moves, and a new `main`
+then deploys as usual. Disable the timer if the rollback must hold.

deploy/auto-deploy.sh

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# MealQuest automated deploy: deploy/RUNBOOK.md, run unattended.
+#
+#   mealquest-auto-deploy              deploy origin/main if it is new and CI passed
+#   mealquest-auto-deploy --ref <ref>  deploy <ref> now, bypassing the CI and no-op gates
+#
+# Installed as /usr/local/sbin/mealquest-auto-deploy and run as overseer by
+# mealquest-auto-deploy.service (deploy/systemd); install, semantics and the
+# manual override: deploy/RUNBOOK.md "Automated deploys". Run as root (sudo)
+# it re-executes itself as overseer.
+#
+# Without --ref: exit 0 with no output when origin/main is the last deployed
+# SHA in the deploy record or its CI is pending; exit 1, deploying nothing,
+# when its CI failed or reports no status, or when the last attempt to deploy
+# that SHA failed. Every deploy runs the runbook's blocks in order and stops
+# at the first failure; nothing before the restart touches production. A
+# verified deploy appends one line to the deploy record:
+#   <UTC date> previous=<SHA> deployed=<SHA> restore_point=<UTC date>
+# a failed one appends:
+#   <UTC date> FAILED target=<SHA> status=<exit status>
+set -euo pipefail
+
+CHECKOUT=/home/overseer/mealquest
+RECORD=/home/overseer/mealquest-auto-deploy.log
+LOCK=/home/overseer/mealquest-auto-deploy.lock
+STATUS_API=https://code.cubecraftlabs.com/api/v1/repos/Maniacs_Mansion/MealQuest/commits
+PUBLIC=https://mealquest.cubecraftlabs.com
+D=/var/lib/docker/volumes/mealquest-data/_data
+COMPOSE=(docker compose -f deploy/compose.yaml)
+
+fail() { echo "$*" >&2; exit 1; }
+
+if [ "$(id -u)" -eq 0 ]; then
+  exec sudo -u overseer -H -- "$0" "$@"
+fi
+[ "$(id -un)" = overseer ] || fail "run as overseer (or root), not $(id -un)"
+
+ref=
+case "$#" in
+  0) ;;
+  2) [ "$1" = --ref ] && [ -n "$2" ] || fail "usage: $0 [--ref <ref>]"; ref=$2 ;;
+  *) fail "usage: $0 [--ref <ref>]" ;;
+esac
+
+exec 9>> "$LOCK"
+flock -n 9 || fail "another mealquest-auto-deploy run holds $LOCK"
+
+cd "$CHECKOUT"
+git fetch --quiet --tags origin || fail "git fetch origin failed"
+
+if [ -n "$ref" ]; then
+  target=$(git rev-parse --verify --quiet "$ref^{commit}") || fail "$ref is not a commit in $CHECKOUT"
+else
+  # The full remote-tracking ref: a bare origin/main resolves a tag or local
+  # branch of that name first, which could deploy a commit not on main.
+  target=$(git rev-parse --verify --quiet "refs/remotes/origin/main^{commit}") \
+    || fail "refs/remotes/origin/main is not a commit in $CHECKOUT"
+  [ -f "$RECORD" ] || fail "no deploy record at $RECORD: seed it with one manual deploy (deploy/RUNBOOK.md \"Automated deploys\")"
+  last=$(grep -oE 'deployed=[0-9a-f]{40}' "$RECORD" | tail -n 1 | cut -d = -f 2) || true
+  [ -n "$last" ] || fail "$RECORD records no deploy: seed it with one manual deploy (deploy/RUNBOOK.md \"Automated deploys\")"
+  [ "$target" != "$last" ] || exit 0
+  if tail -n 1 "$RECORD" | grep -q " FAILED target=$target status="; then
+    fail "auto-deploy of $target already failed (see $RECORD and the journal): fix it, then deploy with --ref"
+  fi
+  state=$(curl -fsS --max-time 30 "$STATUS_API/$target/status" \
+    | python3 -c 'import json, sys; d = json.load(sys.stdin); print(d["state"] if d["total_count"] else "absent")') \
+    || fail "could not read the CI status of $target from $STATUS_API"
+  case "$state" in
+    success) ;;
+    pending) exit 0 ;;
+    *) fail "CI for origin/main $target is $state, not success: not deploying" ;;
+  esac
+fi
+
+echo "auto-deploy: deploying $target${ref:+ (--ref $ref)}"
+restarted=
+W=
+on_exit() {
+  local st=$?
+  [ -z "$W" ] || rm -rf "$W" || st=1
+  if [ "$st" -ne 0 ]; then
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) FAILED target=$target status=$st" >> "$RECORD"
+    if [ -n "$restarted" ]; then
+      echo "auto-deploy FAILED (status $st) after the restart: production may be down or unverified; read journalctl -u mealquest, then fix or roll back (deploy/RUNBOOK.md)" >&2
+    else
+      echo "auto-deploy FAILED (status $st): production untouched" >&2
+    fi
+  fi
+  exit "$st"
+}
+trap on_exit EXIT
+
+# deploy/RUNBOOK.md "Deploy" > "1. Build": record the rollback SHA from the
+# RUNNING release, check out the target, reject a dirty checkout, build.
+bind=$(grep -E '^MEALQUEST_BIND_ADDRESS=' deploy/.env | cut -d = -f 2-) || fail "deploy/.env sets no MEALQUEST_BIND_ADDRESS"
+[ -n "$bind" ] || fail "deploy/.env sets no MEALQUEST_BIND_ADDRESS"
+running=$(curl -fsS "http://$bind:8090/health" | python3 -c 'import json, sys; print(json.load(sys.stdin)["version"])') \
+  || fail "http://$bind:8090/health did not return a version: no running release to roll back to"
+case "$running" in
+  dev|*-dirty) fail "the running release reports $running, which names no commit" ;;
+esac
+rollback=$(git rev-parse --verify --quiet "$running^{commit}") \
+  || fail "running version $running is not a commit in this repository"
+echo "rollback SHA: $rollback (running version $running)"
+git checkout --quiet --detach "$target"
+dirty=$(git status --porcelain --untracked-files=no -- . ':(exclude)internal/frontend/dist')
+[ -z "$dirty" ] || fail "the checkout has modified tracked files; clean it first:
+$dirty"
+v=$(git describe --tags --always)${dirty:+-dirty}   # the Makefile's VERSION
+make docker
+docker image inspect "mealquest:$v" > /dev/null 2>&1 || fail "no image mealquest:$v: the build failed"
+echo "built: mealquest:$v"
+
+# deploy/RUNBOOK.md "Prerequisites": deploy/.env sets every variable of the
+# target's .env.example, and every secret is mode 0600.
+missing=$(comm -23 <(grep -oE '^MEALQUEST_[A-Z_]+' deploy/.env.example | sort -u) \
+                   <(grep -oE '^MEALQUEST_[A-Z_]+' deploy/.env | sort -u))
+[ -z "$missing" ] || fail "deploy/.env is missing: $missing"
+loose=$(sudo find deploy/secrets -type f ! -perm 600)
+[ -z "$loose" ] || fail "secrets not mode 0600: $loose"
+
+# CTXD RUNBOOKS.MD "Routine deploy and rollback" > "Deploy" step 2: a verified
+# pre-deploy restore point. The scripts are CTXD "Count check". They and the
+# check files live in a private mktemp directory (mode 0700), not at shared
+# /tmp paths, and python runs with -I: the snapshot runs as root, and a
+# shared directory on its import path would let any local user run code as
+# root.
+W=$(mktemp -d)
+cat > "$W/mqcount.py" <<'EOF'
+import sqlite3, sys, hashlib
+c = sqlite3.connect(sys.argv[1])
+tabs = [r[0] for r in c.execute("select name from sqlite_master where type=\"table\" and name not like \"sqlite_%\" and name not like \"_litestream%\" order by name")]
+for t in ("dinners", "week_plans", "schema_migrations"):
+    print(t, c.execute(f"select count(*) from {t}").fetchone()[0])
+h = hashlib.sha256()
+for t in tabs:
+    for row in c.execute(f"select * from \"{t}\" order by rowid"):
+        h.update(repr(row).encode())
+print("tables", len(tabs), "content-sha256", h.hexdigest()[:16])
+print("integrity", c.execute("pragma integrity_check").fetchone()[0])
+EOF
+cat > "$W/mqsnap.py" <<'EOF'
+import os, sqlite3, sys
+src, dst = sys.argv[1], sys.argv[2]
+if os.path.exists(dst):
+    sys.exit(f"{dst} already exists")
+s = sqlite3.connect(f"file:{src}?mode=ro", uri=True)
+d = sqlite3.connect(dst)
+s.backup(d)
+s.close()
+result = d.execute("pragma integrity_check").fetchall()
+d.close()
+if result != [("ok",)]:
+    sys.exit(f"snapshot integrity_check failed: {result}")
+print("snapshot", dst, "integrity ok")
+EOF
+point=$(
+set -eu
+point=
+trap 'st=$?
+rm -rf "$W" || st=1
+sudo sh -c "rm -f $D/predeploy-check.db*" || st=1
+if [ "$st" -eq 0 ] && [ -n "$point" ]; then echo "pre-deploy restore point: $point" >&2; echo "$point"
+else [ "$st" -ne 0 ] || st=1; echo "verification FAILED (status $st): do not restart" >&2; fi
+exit "$st"' EXIT
+exec 3>&1 1>&2   # block output to the journal; only the restore point to $point
+mkdir "$W/mqcheck"
+# a. Replication running, no log errors (grep: 0 match, 1 none, 2+ error), newest LTX listed
+id=$("${COMPOSE[@]}" ps --status running --quiet litestream) || fail "docker compose ps failed"
+[ -n "$id" ] || fail "litestream is not running"
+"${COMPOSE[@]}" logs --since 24h litestream > "$W/mqcheck/litestream.log" || fail "docker compose logs failed"
+gs=0
+grep -i error "$W/mqcheck/litestream.log" > "$W/mqcheck/litestream.errors" || gs=$?
+case "$gs" in
+  0) cat "$W/mqcheck/litestream.errors"; fail "litestream logged errors in the last 24h";;
+  1) ;;
+  *) fail "the litestream log scan failed (status $gs)";;
+esac
+"${COMPOSE[@]}" exec -T litestream \
+  litestream ltx -config /etc/litestream.yml -level all /data/mealquest.db
+# b. Restore replica to a scratch file (live files untouched), move off the volume, snapshot live
+"${COMPOSE[@]}" run --rm --no-deps litestream \
+  restore -config /etc/litestream.yml -o /data/predeploy-check.db /data/mealquest.db
+sudo sh -c "mv $D/predeploy-check.db* $W/mqcheck/"
+sudo python3 -I "$W/mqsnap.py" "$D/mealquest.db" "$W/mqcheck/live.db"
+sudo chown -R "$(id -un)" "$W/mqcheck"
+sudo ls -ln "$D"
+# mealquest.db-wal and -shm owned by 10001, never 0 (CTXD "Count check")
+root=$(sudo find "$D" -maxdepth 1 \( -name mealquest.db-wal -o -name mealquest.db-shm \) -uid 0)
+[ -z "$root" ] || fail "owned by root, not 10001 (CTXD RUNBOOKS.MD \"Count check\"): $root"
+# c. Restored replica: integrity ok and identical counts/content-sha256 to the live snapshot
+python3 -I "$W/mqcount.py" "$W/mqcheck/predeploy-check.db" > "$W/mqcheck/restored.txt"
+python3 -I "$W/mqcount.py" "$W/mqcheck/live.db" > "$W/mqcheck/live.txt"
+cat "$W/mqcheck/restored.txt"
+grep -qx 'integrity ok' "$W/mqcheck/restored.txt" || fail "the restored replica failed integrity_check"
+diff "$W/mqcheck/restored.txt" "$W/mqcheck/live.txt" || fail "the restored replica differs from the live snapshot"
+# d. Restore point: after every check, before the restart
+point=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+exec 1>&3
+)
+
+# CTXD RUNBOOKS.MD "Routine deploy and rollback" > "Deploy" step 3:
+# boot-required configuration, secrets read the way the service reads them.
+[ -f deploy/.env ] || fail "missing deploy/.env"
+cid=$(grep -m 1 -E '^MEALQUEST_GOOGLE_CLIENT_ID=' deploy/.env | cut -d = -f 2- | tr -d '"' | tr -d "'") \
+  || fail "missing MEALQUEST_GOOGLE_CLIENT_ID in deploy/.env"
+[ -n "$cid" ] || fail "missing MEALQUEST_GOOGLE_CLIENT_ID in deploy/.env"
+[ -e deploy/secrets/google_client_secret ] || fail "missing deploy/secrets/google_client_secret"
+[ -s deploy/secrets/google_client_secret ] || fail "deploy/secrets/google_client_secret is empty"
+id=$("${COMPOSE[@]}" ps --status running --quiet mealquest) || fail "docker compose ps failed"
+[ -n "$id" ] || fail "the mealquest container is not running: start it (the check reads secrets the way the service does)"
+docker exec "$id" sh -c 'test -s /run/secrets/google_client_secret && test -r /run/secrets/google_client_secret' \
+  || fail "google_client_secret is not readable by the service user inside the container"
+echo "boot-required configuration present"
+
+# deploy/RUNBOOK.md "2. Ship and restart".
+"${COMPOSE[@]}" pull litestream searxng
+docker tag "mealquest:$v" mealquest-mealquest
+restarted=yes
+sudo systemctl restart mealquest
+for s in mealquest litestream searxng; do
+  id=$("${COMPOSE[@]}" ps --status running --quiet "$s")
+  [ -n "$id" ] || fail "$s is not running"
+done
+id=$("${COMPOSE[@]}" ps --quiet mealquest)
+health=$(docker inspect -f '{{.State.Health.Status}}' "$id")
+[ "$health" = healthy ] || fail "mealquest is $health, not healthy"
+echo "restarted on: mealquest:$v"
+
+# deploy/RUNBOOK.md "3. Verify the deployed version and a real screen".
+for base in "http://$bind:8090" "$PUBLIC"; do
+  got=$(curl -fsS "$base/health" | python3 -c 'import json, sys; print(json.load(sys.stdin)["version"])') \
+    || fail "$base/health did not return a version"
+  [ "$got" = "$v" ] || fail "$base/health reports version $got, the checkout is $v"
+  for path in / /plan; do
+    page=$(curl -fsS "$base$path") || fail "$base$path did not return 200"
+    grep -q '<div id="root"></div>' <<< "$page" || fail "$base$path is not the PWA shell"
+    js=$(grep -oE 'src="/assets/[^"]+\.js"' <<< "$page" | head -n 1 | cut -d '"' -f 2) || true
+    [ -n "$js" ] || fail "$base$path references no built /assets/ script"
+    type=$(curl -fsS -o /dev/null -w '%{content_type}' "$base$js") || fail "$base$js did not return 200"
+    case "$type" in
+      text/javascript*) ;;
+      *) fail "$base$js is $type, not JavaScript" ;;
+    esac
+  done
+  echo "$base: version $got, PWA shell and $js served"
+done
+
+deployed=$(git rev-parse HEAD)
+echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) previous=$rollback deployed=$deployed restore_point=$point" >> "$RECORD"
+echo "deployed and verified: $v ($deployed), previous $rollback, restore point $point"

deploy/systemd/mealquest-auto-deploy.service

@@ -0,0 +1,23 @@
+# Deploys origin/main to production when it is new and its CI passed
+# (/usr/local/sbin/mealquest-auto-deploy, from deploy/auto-deploy.sh).
+# Triggered by mealquest-auto-deploy.timer; output goes to the journal.
+# Installing it and the manual override: deploy/RUNBOOK.md "Automated deploys".
+#
+# ExecCondition= skips the run while mealquest.service is not active, so a
+# stack stopped on purpose (a database or media restore) is never redeployed
+# under the operator. It is deliberately not Requires=/Requisite= on
+# mealquest.service: those would start the stack, or stop this run when the
+# deploy itself restarts mealquest.service. Runs as overseer, who owns the
+# checkout and uses sudo for the runbook's privileged steps.
+[Unit]
+Description=MealQuest automated deploy of main
+Wants=network-online.target
+After=network-online.target docker.service mealquest.service
+
+[Service]
+Type=oneshot
+User=overseer
+Group=overseer
+WorkingDirectory=/home/overseer/mealquest
+ExecCondition=/usr/bin/systemctl is-active --quiet mealquest.service
+ExecStart=/usr/local/sbin/mealquest-auto-deploy

deploy/systemd/mealquest-auto-deploy.timer

@@ -0,0 +1,13 @@
+# Checks for a new main at every quarter hour (plus up to 5 minutes' random
+# delay). Persistent= runs a check at once when the host comes back if a
+# scheduled one was missed while it was down.
+[Unit]
+Description=Periodic MealQuest automated deploy
+
+[Timer]
+OnCalendar=*-*-* *:0/15:00
+RandomizedDelaySec=5min
+Persistent=true
+
+[Install]
+WantedBy=timers.target

docs/ARCHITECTURE.md

@@ -2,10 +2,8 @@
 
 This mirrors the architecture section of `CONTEXT.MD` in the CTXD project
 `mealquest`, which is the source of record; if the two disagree, CTXD wins and
-this file should be updated. It describes the **planned** application. The
-repository today is the Feature 01 scaffold: `cmd/server`, `internal/config`,
-`internal/server` (`/health`), `internal/frontend` (embedded PWA with SPA
-fallback), the `web/` skeleton, `Makefile`, `Dockerfile` and CI.
+this file should be updated. It describes the application as built; nothing
+it names is still only planned.
 
 Decision numbers (D-NNN) refer to `DECISIONS.MD` in CTXD.
 
@@ -46,20 +44,22 @@ headers, so sign-in works whichever peer the request arrives from.
 | `cmd/vapidgen` | Prints a new VAPID key pair for Web Push. |
 | `internal/config` | Env-only `MEALQUEST_*` config; secrets from `*_FILE`. |
 | `internal/server` | HTTP server, router, middleware. |
+| `internal/forwarded` | Client IP and scheme from `X-Forwarded-*`, trusted only from `MEALQUEST_TRUSTED_PROXY`. |
+| `internal/secureurl` | The transport rule for URLs that carry credentials (`secureurl.Check`). |
 | `internal/frontend` | Embedded PWA, SPA fallback. |
 | `internal/auth` | Authentik OIDC, sessions, CSRF. |
-| `internal/db`, `internal/store` | SQLite connections, sqlc queries. |
+| `internal/db`, `internal/store` | sqlc-generated queries; SQLite connections, migrations at boot, transactions. |
 | `internal/secretbox` | AES-256-GCM encryption for `_ct` columns. |
-| `internal/household`, `internal/dinners`, `internal/recipes` | Domain. |
-| `internal/ai/llm`, `internal/ai/harness`, `internal/ai/skills` | AI provider adapters, skill harness, skills. |
-| `internal/suggest`, `internal/plan`, `internal/shopping`, `internal/ideas` | Feature services. |
+| `internal/household`, `internal/dinners`, `internal/recipes` | Domain: household settings and local time, dinners (grounding, photo backfill), recipe search, fetch and grounding. |
+| `internal/ai/llm`, `internal/ai/harness`, `internal/ai/skills`, `internal/ai/aisettings` | AI provider adapters, skill harness, skills, AI settings. |
+| `internal/suggest`, `internal/plan`, `internal/shopping`, `internal/ideas`, `internal/home` | Feature services. |
 | `internal/gcal`, `internal/notify`, `internal/push`, `internal/chat` | Integrations. |
 | `internal/vapid` | VAPID key generation and validation. |
 | `internal/jobs`, `internal/scheduler` | Background jobs and schedules. |
-| `migrations/` | SQL migrations (no goose or golang-migrate). |
+| `migrations/` | SQL migrations, embedded and applied at boot by `internal/store` (no goose or golang-migrate); sqlc queries in `migrations/queries/`. |
 | `web/` | React PWA. |
-| `deploy/` | Deployment files. |
-| `docs/` | Documentation. |
+| `deploy/` | Production compose stack, systemd units, the [deploy runbook](../deploy/RUNBOOK.md) and the automated deploy (see Deployment). |
+| `docs/` | Documentation (this file). |
 | `design/` | Requirements and UI handoff (read-only reference). |
 
 ## Backend stack and conventions
@@ -259,6 +259,29 @@ automatic** (D-021).
   unarchived dinner still `pending` with no `ground_dinner` job for its revision
   queued or running is set `failed` with `interrupted`, so no dinner stays
   pending with nothing left to ground it.
+  Photo backfill. `POST /api/v1/settings/photo-backfill` (CSRF-checked)
+  enqueues a `backfill_dinner_photos` job and answers 202 `{id}` without
+  waiting for it; while one is queued or running it enqueues nothing and
+  answers with that job's id, so two passes never overlap, across restarts
+  too. The kind is refused by `POST /api/v1/jobs`. The job
+  grounds, one at a time with `Ground` on its name, every unarchived dinner
+  that is `failed` with no photo and no pasted `recipe_url` — grounded,
+  `manual` and `pending` dinners are never listed, and a pasted link is
+  never replaced by a search. Success sets grounding_status `grounded` as
+  the `ground_dinner` job does (the recipe keeps its source URL and site);
+  failure leaves the dinner `failed` with the new `grounding_error`, for
+  the fix-recipe flow. One dinner's failure never stops the others; a
+  dinner renamed, archived or grounded by hand meanwhile is left as it is.
+  Its result is `{dinners: [{dinner_id, outcome, reason}]}`, outcome
+  `grounded`, `failed` (with its reason) or `skipped`. A dinner whose write
+  fails is `failed` with `grounding_error` and left as it was; the others
+  still run, then the job fails with `internal_error`, keeping that result.
+  The responses returning a `dinners.Dinner` representation (the list; the
+  create, update, archive, favorite and grounding responses; the idea
+  responses) carry `photo_backfill_eligible`, and
+  `GET /api/v1/dinners/{id}` does not; it says whether the backfill grounds
+  that dinner, computed by the same condition it lists dinners by, so a
+  client offers a search only where one runs.
   `GET /api/v1/dinners/{id}/recipe-candidates`
   searches for the dinner's name and returns `{candidates: [{candidate_id,
   title, site_name, photo_url, minutes}]}`, at most 3, ranked as `Ground`
@@ -309,20 +332,24 @@ automatic** (D-021).
   `suggest_side_quests` for 5 Side quests (scope: the batch id), then
   grounds the survivors in the model's order with `Grounder.GroundMany`,
   as many as are still wanted at a time, until 5 are kept or none are
-  left. A Side quest no recipe grounds is dropped; each round's grounded
-  ones are stored before the next — a dinner with status `suggested`,
-  origin `side_quest`, grounding_status `grounded` with the recipe's
-  recipe_id, photo_id, method, minutes_total and difficulty and the
-  model's cuisine, and a `pending` suggestion with the name it is
-  suggested under, the reason and `cited_regular_ids` — unless, since the
-  job read its input, a dinner it repeats was added, a suggestion it
-  repeats passed, or a Regular it cites renamed or archived (checked in
-  the storing transaction). The job publishes
-  `{batch_id, stage, suggestion_ids, dropped}` as it goes (`suggesting`,
+  left. A Side quest no recipe grounds is dropped. A `replenish` batch
+  stores each round's grounded ones before the next; a `scheduled` or
+  `manual` batch, which notifies, holds them and stores them all in one
+  transaction once its last round is done. Each is stored as a dinner
+  with status `suggested`, origin `side_quest`, grounding_status
+  `grounded` with the recipe's recipe_id, photo_id, method,
+  minutes_total and difficulty and the model's cuisine, and a `pending`
+  suggestion with the name it is suggested under, the reason and
+  `cited_regular_ids` — unless, since the job read its input, a dinner
+  it repeats was added, a suggestion it repeats passed, or a Regular it
+  cites renamed or archived (checked in the storing transaction). The job
+  publishes `{batch_id, stage, suggestion_ids, dropped}` as it goes (`suggesting`,
   `grounding`, `done`). It fails with `no_regulars`, `ai_failed` (the
   skill or `normalize_recipe` failed; no Side quest is made up instead,
   D-017), `search_not_configured` or `search_failed`, and the batch is set
-  `failed`; Side quests stored before the failure stay in the deck. If
+  `failed`. A failed `scheduled` or `manual` batch has stored nothing; a
+  failed `replenish` batch's Side quests stored before the failure stay
+  in the deck. If
   recording the batch's end fails, its job fails; the job runner retries
   a job's final status write with backoff until it lands, each attempt
   bounded at 5 seconds; at shutdown an attempt that fails or times out is
@@ -480,15 +507,13 @@ automatic** (D-021).
   `changed`, and answers 200 with the plan. A date outside the week is 400 `invalid_date`, an unknown dinner or
   a week with no plan 404, any other dinner 409 `dinner_not_plannable`, and
   a dinner already on another day of the week 409 `dinner_already_planned`.
-- Rotation check (`plan.Service`, D-021). This release provides the
-  `MarkTried` service method and the rotation review read and decide APIs
-  below. The `rotation_check` schedule that is to call `MarkTried` for the
-  household-local day just past is planned (Feature 20, the scheduler) and
-  not wired yet: nothing in production calls `MarkTried`, so no Rotation
-  check opens automatically. `MarkTried(date)` moves every `quest_log` dinner planned on that date, on a plan of any
-  status, to `tried` and opens a `pending` `rotation_reviews` row for it;
-  a dinner already checked for that date is left as it is, so it is
-  idempotent. `GET /api/v1/rotation-reviews` returns `{reviews}`, the
+- Rotation check (`plan.Service`, D-021). The `rotation_check` schedule
+  calls `MarkTried` for the household-local day just past (see Scheduler).
+  `MarkTried(date)` moves every `quest_log` dinner planned on that date, on a plan of any
+  status, to `tried`, opens a `pending` `rotation_reviews` row for it and
+  emits its `rotation_review`, in one transaction;
+  a dinner already checked for that date is left as it is and not
+  notified again, so it is idempotent. `GET /api/v1/rotation-reviews` returns `{reviews}`, the
   pending checks whose dinner is still tried, oldest `plan_date` first,
   each `{dinner: {id, name, photo}, plan_date}`. `POST
   /api/v1/dinners/{id}/rotation-review` takes `{decision}`: `keep` makes
@@ -533,8 +558,8 @@ automatic** (D-021).
   received.
   `harness.Purge` deletes rows older than `harness.RunRetention` (30 days),
   clearing the `suggestion_batches` and `week_plans` references first. The
-  harness does not call it: the scheduler's daily `ai_runs` purge
-  (Feature 20) must call `harness.Purge` with `now - RunRetention`.
+  daily `ai_runs_purge` schedule (`harness.PurgeSchedule`) calls it with
+  its fire time less `RunRetention`.
 - **Concurrency guards** (`harness.Guard`, one per process): `harness.Run`
   takes a scope key, and concurrent runs of one skill with one scope share a
   single in-flight run and its result, error included (single-flight); runs
@@ -649,7 +674,8 @@ job failed, the freeze finds the list still untitled and makes its own
 `archive_title` attempt before freezing. A job that starts during a freeze
 waits for it, then finds the list titled (that title stands) or frozen
 untitled (the job fails `title_failed`), and stores nothing. The
-`week_rollover` schedule is to call `Freeze` for last week.
+`week_rollover` schedule (`shopping.Service.RolloverSchedule`) calls
+`Freeze` for last week, judging the week ended by its fire time.
 
 ## Recipe grounding
 
@@ -775,16 +801,106 @@ purge are fixed and not configurable.
 
 | Schedule | When | Does |
 | --- | --- | --- |
-| `suggestions_weekly` | Sunday 08:00 | New batch of Side quests. |
-| `plan_draft` | Friday 09:00 | AI drafts next week's plan. |
-| `shopping_chat_autosend` | Saturday 08:00 | Sends the Supply run to Google Chat. |
-| `day_of_reminder` | Daily 16:30 | Tonight's dinner reminder. |
-| `rotation_check` | Daily 09:00 | Asks "Keep it in rotation?" for tried dinners. |
-| `week_rollover` | Monday 00:05 (fixed) | Freezes last week's Supply run into the Supply archive. |
-| `ai_runs` purge | Daily (fixed) | Calls `harness.Purge` to delete `ai_runs` rows past 30-day retention (Feature 20). |
+| `suggestions_weekly` | Sunday 08:00 | New batch of Side quests (`suggest.Service.WeeklySchedule`). |
+| `plan_draft` | Friday 09:00 | AI drafts next week's plan (`plan.Service.DraftSchedule`). |
+| `shopping_chat_autosend` | Saturday 08:00 | Sends the coming week's Supply run to Google Chat (`shopping.Service.ChatAutosendSchedule`). |
+| `day_of_reminder` | Daily 16:30, and 15 minutes before a crock-pot start_by earlier than that | Tonight's dinner reminder and the crock-pot start reminder (`plan.Service.ReminderSchedules`). |
+| `rotation_check` | Daily 09:00 | Marks yesterday's Quest log dinners tried and asks "Keep it in rotation?" (`plan.Service.RotationCheckSchedule`). |
+| `week_rollover` | Monday 00:05 (fixed) | Freezes last week's Supply run into the Supply archive (`shopping.Service.RolloverSchedule`). |
+| `ai_runs_purge` | Daily 03:00 (fixed) | Calls `harness.Purge` to delete `ai_runs` rows past 30-day retention (`harness.PurgeSchedule`). |
 
 Runs are recorded in `schedule_runs` and executed through `jobs`.
 
+Job kinds (`internal/jobs`; each registered when `cmd/server` builds the
+service named, before the runner starts). `POST /api/v1/jobs` refuses a
+service-only kind; `GET /api/v1/jobs/{id}` reports any job.
+
+| Kind | Registered by | Enqueued by | Service-only |
+| --- | --- | --- | --- |
+| `noop` | `jobs.RegisterBuiltins` | `POST /api/v1/jobs` (does nothing; proves the runner works) | no |
+| `ground_dinner` | `dinners.Service` | Adding or renaming a `pending` dinner | no |
+| `backfill_dinner_photos` | `dinners.Service` | `POST /api/v1/settings/photo-backfill` | yes |
+| `suggestion_batch` | `suggest.Service` | `POST /api/v1/suggestions/batches`, a deck decision (replenish), `suggestions_weekly` | no |
+| `draft_week` | `plan.Service` | `POST /api/v1/plans/{weekStart}/draft`, `plan_draft` | yes |
+| `title_supply_run` | `shopping.Service` | Generating an untitled Supply run | yes |
+| `ideas_from_ingredients`, `quick_ideas` | `ideas.Service` | `POST /api/v1/ideas/from-ingredients`, `POST /api/v1/ideas/quick` | yes |
+
+`internal/scheduler` runs them. A schedule registers a name, a rule read
+from the settings (`scheduler.Daily`, `Weekly` or `WeeklyForNextWeek`, or `DailyAt` for a time read from data) and a
+run function; settings changes reach it through `SettingsService.Subscribe`
+and move the next fire time without a restart. Each fire time has a period
+key (`Rule.PeriodKey`): the local date for a daily rule, the ISO week of the
+fire date for a weekly one, or of the week after for `WeeklyForNextWeek`
+(`plan_draft`). Inserting `schedule_runs(schedule, period_key)` is the claim;
+a period already claimed is skipped, so a period runs at most once and a
+failed run is not retried. A claim that fails is not skipped: the pass is
+repeated every `scheduler.ClaimRetry` until the claim succeeds. A settings
+change is recorded with the instant it was saved, and fire times up to that
+instant follow the old rule and later ones the new, however late the
+scheduler applies it. At boot, and whenever the scheduler wakes late,
+every unclaimed fire time within 24 hours (`scheduler.CatchUpWindow`) is
+processed oldest first, each running once. A most recent fire time that
+passed longer ago is claimed without running (logged as missed) so it
+never runs later; older ones are not looked at. DST
+follows `household.LocalTime`: a skipped time fires later by the gap, a
+repeated time fires once, at its first occurrence.
+
+Each schedule is built by the service that does its work, as a
+`scheduler.Schedule` value, and registered in `cmd/server` before the
+scheduler starts: `suggest.Service.WeeklySchedule()` is `suggestions_weekly`.
+Its run calls `StartScheduledBatch(period.Week)`, which starts the same
+batch and job as `POST /api/v1/suggestions/batches` (`StartBatch(manual)`),
+with the `scheduled` trigger, and returns at once; the batch runs as a job. When a
+batch is already pending or running the period starts none and logs it.
+`plan.Service.DraftSchedule()` is `plan_draft`, keyed by the ISO week
+after the fire date (`scheduler.WeeklyForNextWeek`). Its run calls
+`StartScheduledDraft(period.Week)`, which enqueues the same `draft_week`
+job as `POST /api/v1/plans/{weekStart}/draft` without confirm, so a stored
+draft emits `plan_ready:{weekStart}` from the job and a failed one (e.g.
+`ai_failed`, recorded in `ai_runs`) emits nothing. When the week already
+has a plan, in any status, it enqueues nothing; when a draft of the week
+is already queued or running it joins it. Either way it logs it.
+`plan.Service.ReminderSchedules()` is `day_of_reminder`, two schedules
+of one name. The first is `Daily(reminder_time)`, period `YYYY-MM-DD`,
+and calls `EmitDayOfReminder(period.Date)`. The second has `Key` `start`,
+so its periods are `start:YYYY-MM-DD`, and a `scheduler.DailyAt` rule:
+for each date it reads the plan and fires 15 minutes
+(`plan.StartReminderLead`) before the day's `start_by` (the same
+computation the plan API shows) when the dinner is a crock-pot dinner
+whose `start_by` is earlier than that day's `reminder_time`; its run
+calls `EmitStartReminder(period.Date)`, which checks the same again. A
+date whose week has no plan emits neither and logs it. A `DailyAt` fire
+time is looked up from the data on every pass. A committed change that
+can move a `start_by` calls `Scheduler.Wake` (passed to `plan.NewService`
+and `dinners.NewService` as `wake`): a plan swap or stored draft, and a
+dinner's method or minutes changed by edit or grounding. The next pass
+comes at once, so a crock-pot dinner swapped in for tonight is still
+reminded 15 minutes before its `start_by`, not at the next hourly timer
+(`maxWait`); a lookup that fails is logged and repeated every
+`ClaimRetry`.
+`shopping.Service.ChatAutosendSchedule()` is `shopping_chat_autosend`,
+`WeeklyForNextWeek(chat_autosend_dow, chat_autosend_time)`, so its period
+names the coming week. Its run calls `Autosend(period.Week)`, which posts
+with `SendToChat(week, false)`, the household's own send, only when a
+webhook is stored, `list_ready`'s Chat channel is on
+(`notify.Service.ChannelOn`) and the week has a Supply run neither sent
+nor with a send unconfirmed; otherwise it posts nothing and logs why,
+with the key `list_ready:chat:{weekStart}`. It never resends; a send that
+fails is the period's error. `shopping.Service.RolloverSchedule()` is
+`week_rollover`, `Weekly(Monday, 00:05)`; its run freezes the week before
+the fire date's, and a week with no Supply run freezes nothing and logs
+it. `plan.Service.RotationCheckSchedule()` is `rotation_check`,
+`Daily(review_time)`, claimed as `rotation_check:YYYY-MM-DD` of the fire
+date (`Schedule.PeriodKey`). Its run calls `MarkTried` for the day before
+the fire date, which emits one `rotation_review` per Rotation check it
+opens; it never makes a dinner a Regular, and a day with no Quest log
+dinner planned opens none and logs the count.
+`harness.PurgeSchedule(store, logger)` is `ai_runs_purge`,
+`Daily(03:00)`, deleting rows created more than 30 days before the fire
+time.
+Fake-clock tests of a schedule live in `internal/scheduler`, where
+`SetClock` is visible to tests.
+
 ## Notifications
 
 - Events: `plan_ready`, `list_ready`, `day_of_reminder`, `new_suggestions`,
@@ -793,25 +909,43 @@ Runs are recorded in `schedule_runs` and executed through `jobs`.
 - Where each event is emitted, with its idempotency key. Each is stored by
   `notify.EmitTx` in the transaction of the change it is about, so the
   change and its notification commit together or not at all:
-  - `plan_ready:{weekStart}` (URL `/plan`) when a draft job stores the
-    AI's draft of a week. Only the first draft of a week notifies: a
+  - `plan_ready:{weekStart}` (URL `/plan?week={weekStart}`) when a draft job, asked for
+    by the API or the `plan_draft` schedule, stores the AI's draft of a
+    week. Only the first draft of a week notifies: a
     redraft (Rebuild week) has the same key, and a manual swap never
     drafts. Its title is "Next week's plan is ready" (or "This week's",
     or "The plan for the week of Oct 26") and its body the drafted
     dinners Monday to Sunday.
-  - `list_ready:{weekStart}` (URL `/plan/shopping`) when a week's Supply
+  - `list_ready:{weekStart}` (URL `/plan/shopping?week={weekStart}`) when a week's Supply
     run is first created, by `POST /shopping/{weekStart}/generate` or
     after Push to Calendar; remaking it does not notify.
-  - `new_suggestions:{batchId}` (URL `/discover`) when a `scheduled` or
-    `manual` suggestion batch first adds Side quests to the deck, in the
-    transaction storing them, so they are announced even when a later
-    round or recording the batch's end fails; it names that round's Side
-    quests, and a later round's emit stores nothing. A `replenish` batch
-    never notifies.
+  - `new_suggestions:{YYYY-Www}` for a `scheduled` batch, the ISO week it
+    was scheduled for (carried in its job, so a batch caught up late is
+    still keyed by its own week), or `new_suggestions:{batchId}` for a
+    `manual` one (URL `/discover`), once, when the batch's last round is
+    done, in the one transaction that stores all its Side quests, so they
+    and their notification commit together or not at all. Its title
+    counts every Side quest the batch stored ("5 new Side quests are in")
+    and its body names them. A batch that fails at any round, as when
+    `suggest_side_quests` or a later round's `normalize_recipe` fails (the
+    failure is in `ai_runs`), stores no Side quest and sends nothing, so
+    no stored Side quest goes unannounced. A `replenish` batch never
+    notifies. This is the only place `new_suggestions` is emitted; the
+    `suggestions_weekly` schedule does not emit it itself.
   - `day_of_reminder:{date}` (URL `/dinner/{id}`) through
-    `plan.Service.EmitDayOfReminder(date)`, which names the dinner planned
-    on the date and emits nothing for a week with no plan. The scheduler
-    calls it at `reminder_time` (Feature 20).
+    `plan.Service.EmitDayOfReminder(date)`, "Tonight: {dinner} · Recipe →",
+    naming the dinner planned on the date; it emits nothing for a week
+    with no plan. The `day_of_reminder` schedule calls it at
+    `reminder_time`.
+  - `day_of_reminder:start:{date}` (URL `/dinner/{id}`) through
+    `plan.Service.EmitStartReminder(date)`, "Start the crock pot by
+    {time}" with the dinner's name, only for a crock-pot dinner whose
+    `start_by` is earlier than `reminder_time`. The `day_of_reminder`
+    schedule calls it 15 minutes before `start_by`.
+  - `rotation_review:{dinnerId}:{planDate}` (URL `/`, where the Home card
+    asks) through `plan.Service.MarkTried(planDate)`, "How was {dinner}?
+    Keep it in rotation?", once per Rotation check it opens. The
+    `rotation_check` schedule calls it at `review_time` for yesterday.
 - Delivery goes through `notification_outbox`.
 - Web Push uses VAPID (`webpush-go`). Google Chat uses the stored incoming
   webhook.
@@ -1068,7 +1202,7 @@ Runs are recorded in `schedule_runs` and executed through `jobs`.
   request. 404 when the week has no Supply run, 409
   `archived` when it is in the Supply archive, 400 `invalid_request` for a
   bad body. `shopping.SendToChat(weekStart, resend)` is what
-  `shopping_chat_autosend` calls (Feature 20).
+  `shopping_chat_autosend` calls, through `Autosend`.
 - `PATCH /api/v1/shopping/items/{id}` takes `{needed}` (a required
   boolean; it sets the flag, it does not flip it) and answers `{id,
   needed, needed_count, total_count}` with the list's counts after the
@@ -1089,6 +1223,61 @@ Runs are recorded in `schedule_runs` and executed through `jobs`.
   for any other `by`. A frozen list is read through `GET
   /api/v1/shopping/{weekStart}` with `status` `archived`.
 
+## Home API (Feature 21)
+
+- `GET /api/v1/home` (`home.Service`) aggregates the Home screen from the
+  services that own each value, at "now" in the household's zone (never
+  UTC), and answers:
+
+  ```json
+  {
+    "dateLabel": "Friday, Oct 2",
+    "timezone": "America/Chicago",
+    "tonight": {"id": "…", "name": "…", "photo": "/media/…", "origin": "regular", "minutes_total": 40},
+    "sideQuestCount": 10,
+    "shoppingList": {"weekStart": "2026-10-05", "label": "Week 41 · Oct 5 – 11", "ready": true, "sentToChatAt": null},
+    "recentUpdates": {"unread": true}
+  }
+  ```
+
+  `tonight` is today's day of the current week's plan (`plan.Get`), null
+  when the week has no plan; it changes at the household's local
+  midnight, so the PWA reads Home again at the next local midnight of
+  `timezone`, the household's IANA zone. `photo` and `minutes_total` are
+  null when unknown. `sideQuestCount` is the pending cards of the deck,
+  read without writing (`suggest.PendingCount`): a Home read never fails
+  orphaned batches the way a `suggest.Deck` read does.
+  `shoppingList` is the upcoming week's Supply run when it has one, else
+  the current week's (`shopping.Get`); with neither, it is the current
+  week with `ready` false. `recentUpdates.unread` is true when a
+  notification was stored in `notification_outbox` after
+  `household_settings.updates_seen_at`, or at all while that is null
+  (`notify.StoredSince`); an event whose channels are all switched off is
+  never stored and never counts.
+- `GET /api/v1/updates` (`home.Service.Updates`, over `notify.Recent`)
+  answers the Recent updates sheet: the last 10 distinct events in
+  `notification_outbox`, newest first, one per event key whatever its
+  channels or delivery status (an event stored for push and Google Chat is
+  one update):
+
+  ```json
+  {"updates": [{"type": "plan_ready", "title": "…", "body": "…", "url": "/plan?week=2026-10-12", "created_at": "2026-10-09T14:00:00.000Z"}]}
+  ```
+
+  Every field comes from the stored payload, which never holds a webhook
+  URL or secret; `url` is the same-origin path the event opens.
+- `POST /api/v1/updates/seen` with `{"through": "<created_at>"}` (CSRF
+  header required) records that the household has seen its updates
+  through the newest one it was shown, and answers 204. The last-seen
+  instant is `household_settings.updates_seen_at` — the one place it is
+  stored. It only moves forward (`MarkUpdatesSeen`), so a `through` older
+  than the stored one is accepted and changes nothing, and an event
+  stored after `through` keeps `unread` true. It is not a settings edit:
+  `updated_by` and `updated_at` are left as they are and settings
+  subscribers are not told. 400 `invalid_request` for a body that is not
+  exactly that object, a `through` that is not RFC 3339, or one after
+  now.
+
 ## Frontend
 
 - React 19, TypeScript, Vite, React Router 7, TanStack Query 5,
@@ -1144,10 +1333,12 @@ fewer the server answers 400 `invalid_settings` naming
 `onboarding_completed` and changes nothing. Step 3 can be reached with
 fewer — by its URL, or after another member removes a Regular — so it then
 shows the server's reason with an "Add Regulars" button back to step 2.
-Notification permission is never asked for on page load; until Feature 19
-wires Web Push, "Turn on notifications" asks for nothing and says plainly
-that notifications are not on yet, offering "Finish setting up" (which
-completes onboarding as above) instead of a silent success. Offline on the
+Notification permission is never asked for on page load. "Turn on
+notifications" subscribes this device to Web Push from the tap and says
+how it ended — on, blocked by the browser, or unsupported (on iPhone and
+iPad, until MealQuest is on the Home Screen) — then offers only "Finish
+setting up" (which completes onboarding as above); a dismissed permission
+prompt can be asked again. Offline on the
 saved pages the settings cannot be read (the service worker never caches `/api/v1/settings`),
 so the saved pages open as they are.
 
@@ -1164,6 +1355,41 @@ are undone if the server refuses them. While any Regular is `pending`, the
 list is read again every 3 seconds (not while a change is in flight), and
 polling stops once none is.
 
+## Deployment
+
+Production is the compose project `mealquest` on 10.60.1.14
+([`deploy/compose.yaml`](../deploy/compose.yaml)): the `mealquest` image built
+from the root `Dockerfile`, `litestream` replicating the database to the
+NAS over SFTP, and `searxng` on the internal network only. Configuration is
+`deploy/.env` and file secrets in `deploy/secrets/`, neither committed. The
+services never restart themselves; systemd units in `deploy/systemd/` own
+the host:
+
+| Unit | Does |
+| --- | --- |
+| `mealquest-firewall.service` | Restricts port 8090 to Traefik in `DOCKER-USER`; required before the stack starts. |
+| `mealquest.service` | Starts and stops the compose stack. |
+| `mealquest-media-backup.timer` / `.service` | Backs up cached photos to the NAS nightly at 03:30. |
+| `mealquest-auto-deploy.timer` / `.service` | Automated deploy of `main` (below). |
+
+Releases: only `overseer` merges `dev` into `main`. The image carries its
+version (`git describe`: a release tag, else the short SHA), which
+`/health` reports. A deploy follows
+[`deploy/RUNBOOK.md`](../deploy/RUNBOOK.md) — build, pre-deploy restore
+point, boot-config check, ship and restart, verify the deployed SHA and a
+real screen — with rollback to the previous release. The automated deploy
+([`deploy/auto-deploy.sh`](../deploy/auto-deploy.sh), installed as
+`/usr/local/sbin/mealquest-auto-deploy`) runs those same steps unattended:
+its timer checks every quarter hour (plus up to 5 minutes' random delay),
+and deploys `refs/remotes/origin/main` only when it differs from the last
+SHA in the deploy record `/home/overseer/mealquest-auto-deploy.log`, its
+Gitea CI status is `success`, its last attempt did not fail, and
+`mealquest.service` is active. It stops at the first failure and never
+retries a failed SHA; `--ref <ref>` is the manual override. Installing,
+seeding the record and enabling the timer are host steps in the runbook's
+"Automated deploys". Database restore and the boot configuration are in
+CTXD `RUNBOOKS.MD`.
+
 ## Boundaries and gotchas
 
 - **Secrets never reach the client** — API keys, OAuth tokens and the Chat

internal/ai/harness/runs.go

@@ -34,8 +34,8 @@ const (
 	StatusProviderError RunStatus = "provider_error"
 )
 
-// RunRetention is how long ai_runs rows are kept. The daily purge calls
-// Purge with time.Now().Add(-RunRetention).
+// RunRetention is how long ai_runs rows are kept. The daily purge,
+// PurgeSchedule, calls Purge with its fire time less RunRetention.
 const RunRetention = 30 * 24 * time.Hour
 
 // runSaveTimeout bounds writing the ai_runs row of a run that has failed,
@@ -46,9 +46,6 @@ var runSaveTimeout = 5 * time.Second
 // Purge deletes the ai_runs rows created before olderThan and returns how
 // many it deleted. The suggestion_batches and week_plans references to
 // those rows are cleared first, in the same transaction.
-//
-// Nothing in this package calls Purge: the scheduler's daily ai_runs purge
-// (Feature 20) must call it with time.Now().Add(-RunRetention).
 func Purge(ctx context.Context, st *store.Store, olderThan time.Time) (int64, error) {
 	if olderThan.IsZero() {
 		return 0, errors.New("harness: purge ai_runs: zero cutoff")

internal/ai/harness/schedule.go

@@ -0,0 +1,46 @@
+package harness
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// PurgeTime is when, every day in the household zone, ai_runs_purge runs.
+// It is fixed, not a setting.
+const PurgeTime = "03:00"
+
+// PurgeSchedule is the ai_runs_purge schedule over st: every day at
+// PurgeTime it deletes the ai_runs rows created more than RunRetention
+// before the fire time with Purge, its period scheduler.Daily keyed
+// ai_runs_purge:YYYY-MM-DD. A purge caught up late deletes no row younger
+// than RunRetention; one that fails is the period's error and is not
+// retried, and the next day's purge deletes what it left.
+func PurgeSchedule(st *store.Store, logger *slog.Logger) (scheduler.Schedule, error) {
+	if st == nil {
+		return scheduler.Schedule{}, errors.New("harness: purge schedule: nil store")
+	}
+	if logger == nil {
+		return scheduler.Schedule{}, errors.New("harness: purge schedule: nil logger")
+	}
+	return scheduler.Schedule{
+		Name: scheduler.AIRunsPurge,
+		Rule: func(household.Settings) scheduler.Rule {
+			return scheduler.Daily(PurgeTime)
+		},
+		Run: func(ctx context.Context, p scheduler.Period) error {
+			cutoff := p.FireAt.Add(-RunRetention)
+			n, err := Purge(ctx, st, cutoff)
+			if err != nil {
+				return err
+			}
+			logger.InfoContext(ctx, "ai_runs purged", "period", p.Key, "deleted", n, "created_before", cutoff.UTC().Format(time.RFC3339))
+			return nil
+		},
+	}, nil
+}

internal/chat/chat_test.go

@@ -308,7 +308,7 @@ func TestSendThreadsByWeek(t *testing.T) {
 		ListReady(week, 19, 7),
 		DayOfReminder(mustDate(t, "2026-10-18"), "01J9DINNER", "Tacos"),
 		NewSuggestions("01J9BATCH", week, []string{"Pho"}),
-		RotationReview("01J9DINNER", "Pho", week),
+		RotationReview("01J9DINNER", "Pho", mustDate(t, "2026-10-14")),
 	}
 	for _, ev := range events {
 		if err := svc.Send(ctx, notify.Message{ID: "n1", EventKey: ev.Key, Channel: notify.ChannelChat, Payload: payloadOf(ev), Attempt: 1}); err != nil {
@@ -342,8 +342,8 @@ func TestSendThreadsByWeek(t *testing.T) {
 		t.Errorf("plan text = %q", reqs[0].Body["text"])
 	}
 
-	// The cards' "Open" buttons link under the public URL.
-	for i, wantLink := range map[int]string{0: "https://mealquest.example/plan", 1: "https://mealquest.example/plan/shopping"} {
+	// The cards' "Open" buttons link under the public URL to the event's week.
+	for i, wantLink := range map[int]string{0: "https://mealquest.example/plan?week=2026-10-12", 1: "https://mealquest.example/plan/shopping?week=2026-10-12"} {
 		data, _ := json.Marshal(reqs[i].Body["cardsV2"])
 		var cards []cardV2
 		if err := json.Unmarshal(data, &cards); err != nil || len(cards) != 1 {

internal/chat/messages.go

@@ -2,6 +2,7 @@ package chat
 
 import (
 	"fmt"
+	"net/url"
 	"strings"
 	"time"
 
@@ -46,7 +47,7 @@ func PlanReady(week, thisWeek store.LocalDate, dinners []string) notify.Event {
 		Key:   string(notify.PlanReady) + ":" + week.String(),
 		Title: planTitle(week, thisWeek),
 		Body:  nameList(dinners),
-		URL:   "/plan",
+		URL:   "/plan?" + url.Values{"week": {week.String()}}.Encode(),
 		Week:  week,
 	}
 }
@@ -59,48 +60,65 @@ func ListReady(week store.LocalDate, needed, dinners int) notify.Event {
 		Key:   string(notify.ListReady) + ":" + week.String(),
 		Title: "This week's Supply run is ready",
 		Body:  fmt.Sprintf("%s to buy for %s", count(needed, "item", "items"), count(dinners, "dinner", "dinners")),
-		URL:   "/plan/shopping",
+		URL:   "/plan/shopping?" + url.Values{"week": {week.String()}}.Encode(),
 		Week:  week,
 	}
 }
 
 // DayOfReminder is the day_of_reminder event of the dinner dinnerID, named
-// name, planned on date.
+// name, planned on date: "Tonight: Tacos · Recipe →", a title carrying its
+// own call to action.
 func DayOfReminder(date store.LocalDate, dinnerID, name string) notify.Event {
 	return notify.Event{
 		Type:  notify.DayOfReminder,
 		Key:   string(notify.DayOfReminder) + ":" + date.String(),
-		Title: "Tonight's dinner",
+		Title: "Tonight: " + name + " · Recipe →",
+		URL:   "/dinner/" + dinnerID,
+		Week:  household.WeekStart(date),
+	}
+}
+
+// StartReminder is the day_of_reminder event, keyed
+// day_of_reminder:start:{date}, reminding the household to start the
+// crock-pot dinner dinnerID, named name and planned on date, by startBy,
+// a time in the household zone: "Start the crock pot by 9:30 am".
+func StartReminder(date store.LocalDate, dinnerID, name string, startBy time.Time) notify.Event {
+	return notify.Event{
+		Type:  notify.DayOfReminder,
+		Key:   string(notify.DayOfReminder) + ":start:" + date.String(),
+		Title: "Start the crock pot by " + startBy.Format("3:04 pm"),
 		Body:  name,
 		URL:   "/dinner/" + dinnerID,
 		Week:  household.WeekStart(date),
 	}
 }
 
-// NewSuggestions is the new_suggestions event of suggestion batch batchID,
-// made in the week starting on week, naming its Side quests.
-func NewSuggestions(batchID string, week store.LocalDate, names []string) notify.Event {
+// NewSuggestions is the new_suggestions event keyed by id, the ISO week
+// ("2026-W41") of a scheduled suggestion batch or the batch id of a manual
+// one, of the week starting on week: how many new Side quests there are,
+// and their names.
+func NewSuggestions(id string, week store.LocalDate, names []string) notify.Event {
 	return notify.Event{
 		Type:  notify.NewSuggestions,
-		Key:   string(notify.NewSuggestions) + ":" + batchID,
-		Title: "New Side quests are in",
+		Key:   string(notify.NewSuggestions) + ":" + id,
+		Title: count(len(names), "new Side quest is in", "new Side quests are in"),
 		Body:  nameList(names),
 		URL:   "/discover",
 		Week:  week,
 	}
 }
 
-// RotationReview is the rotation_review event asking whether the dinner
-// dinnerID, named name and tried in the week starting on week, becomes a
-// Regular.
-func RotationReview(dinnerID, name string, week store.LocalDate) notify.Event {
+// RotationReview is the rotation_review event, keyed
+// rotation_review:{dinnerID}:{planDate}, of the Rotation check of the
+// dinner dinnerID, named name and tried on planDate: "How was Pho? Keep it
+// in rotation?". It opens Home, where the Rotation check card asks.
+func RotationReview(dinnerID, name string, planDate store.LocalDate) notify.Event {
 	return notify.Event{
 		Type:  notify.RotationReview,
-		Key:   string(notify.RotationReview) + ":" + dinnerID,
-		Title: "Keep it in rotation?",
-		Body:  "You tried " + name + ". Make it a Regular?",
+		Key:   string(notify.RotationReview) + ":" + dinnerID + ":" + planDate.String(),
+		Title: "How was " + name + "? Keep it in rotation?",
 		URL:   "/",
-		Week:  week,
+		Week:  household.WeekStart(planDate),
 	}
 }
 
@@ -171,9 +189,13 @@ func planTitle(week, thisWeek store.LocalDate) string {
 }
 
 // Text is the Google Chat message of p: its title, its body after a colon
-// and the event's call to action with an arrow.
+// and the event's call to action with an arrow. A title ending in an arrow,
+// with no body, carries its own call to action and is the message as it is.
 func Text(p notify.Payload) string {
 	text := p.Title
+	if p.Body == "" && strings.HasSuffix(text, "→") {
+		return text
+	}
 	if p.Body != "" {
 		if endsSentence(text) {
 			text += " "

internal/chat/messages_test.go

@@ -2,6 +2,7 @@ package chat
 
 import (
 	"testing"
+	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
@@ -38,7 +39,7 @@ func TestMessages(t *testing.T) {
 			name:  "plan ready",
 			ev:    PlanReady(week, week, []string{"Tacos", "Bolognese", "Tikka masala", "Lemon orzo", "Bibimbap", "Shakshuka", "Chili"}),
 			key:   "plan_ready:2026-10-12",
-			url:   "/plan",
+			url:   "/plan?week=2026-10-12",
 			week:  "2026-10-12",
 			title: "This week's plan is ready",
 			body:  "Tacos, Bolognese, Tikka masala + 4 more",
@@ -48,7 +49,7 @@ func TestMessages(t *testing.T) {
 			name:  "plan ready with three dinners",
 			ev:    PlanReady(week, week, []string{"Tacos", "Bolognese", "Tikka masala"}),
 			key:   "plan_ready:2026-10-12",
-			url:   "/plan",
+			url:   "/plan?week=2026-10-12",
 			week:  "2026-10-12",
 			title: "This week's plan is ready",
 			body:  "Tacos, Bolognese, Tikka masala",
@@ -58,7 +59,7 @@ func TestMessages(t *testing.T) {
 			name:  "plan ready for next week",
 			ev:    PlanReady(week, mustDate(t, "2026-10-05"), []string{"Tacos", "Bolognese", "Tikka masala", "Lemon orzo"}),
 			key:   "plan_ready:2026-10-12",
-			url:   "/plan",
+			url:   "/plan?week=2026-10-12",
 			week:  "2026-10-12",
 			title: "Next week's plan is ready",
 			body:  "Tacos, Bolognese, Tikka masala + 1 more",
@@ -68,7 +69,7 @@ func TestMessages(t *testing.T) {
 			name:  "plan ready for a later week",
 			ev:    PlanReady(mustDate(t, "2026-10-26"), mustDate(t, "2026-10-05"), []string{"Tacos"}),
 			key:   "plan_ready:2026-10-26",
-			url:   "/plan",
+			url:   "/plan?week=2026-10-26",
 			week:  "2026-10-26",
 			title: "The plan for the week of Oct 26 is ready",
 			body:  "Tacos",
@@ -78,7 +79,7 @@ func TestMessages(t *testing.T) {
 			name:  "list ready",
 			ev:    ListReady(week, 19, 7),
 			key:   "list_ready:2026-10-12",
-			url:   "/plan/shopping",
+			url:   "/plan/shopping?week=2026-10-12",
 			week:  "2026-10-12",
 			title: "This week's Supply run is ready",
 			body:  "19 items to buy for 7 dinners",
@@ -88,7 +89,7 @@ func TestMessages(t *testing.T) {
 			name:  "list ready singular",
 			ev:    ListReady(week, 1, 1),
 			key:   "list_ready:2026-10-12",
-			url:   "/plan/shopping",
+			url:   "/plan/shopping?week=2026-10-12",
 			week:  "2026-10-12",
 			title: "This week's Supply run is ready",
 			body:  "1 item to buy for 1 dinner",
@@ -100,9 +101,19 @@ func TestMessages(t *testing.T) {
 			key:   "day_of_reminder:2026-10-15",
 			url:   "/dinner/01J9Z8Y7X6W5V4T3S2R1Q0P9N8",
 			week:  "2026-10-12",
-			title: "Tonight's dinner",
-			body:  "Tacos",
-			chatT: "Tonight's dinner: Tacos. Open the recipe →",
+			title: "Tonight: Tacos · Recipe →",
+			body:  "",
+			chatT: "Tonight: Tacos · Recipe →",
+		},
+		{
+			name:  "crock-pot start reminder",
+			ev:    StartReminder(mustDate(t, "2026-10-15"), "01J9Z8Y7X6W5V4T3S2R1Q0P9N8", "Beef Chili", time.Date(2026, 10, 15, 9, 30, 0, 0, time.FixedZone("CDT", -5*60*60))),
+			key:   "day_of_reminder:start:2026-10-15",
+			url:   "/dinner/01J9Z8Y7X6W5V4T3S2R1Q0P9N8",
+			week:  "2026-10-12",
+			title: "Start the crock pot by 9:30 am",
+			body:  "Beef Chili",
+			chatT: "Start the crock pot by 9:30 am: Beef Chili. Open the recipe →",
 		},
 		{
 			name:  "new suggestions",
@@ -110,19 +121,29 @@ func TestMessages(t *testing.T) {
 			key:   "new_suggestions:01J9BATCH",
 			url:   "/discover",
 			week:  "2026-10-12",
-			title: "New Side quests are in",
+			title: "5 new Side quests are in",
 			body:  "Lemon orzo, Bibimbap, Shakshuka + 2 more",
-			chatT: "New Side quests are in: Lemon orzo, Bibimbap, Shakshuka + 2 more. Open Discover →",
+			chatT: "5 new Side quests are in: Lemon orzo, Bibimbap, Shakshuka + 2 more. Open Discover →",
+		},
+		{
+			name:  "new suggestions of a scheduled week",
+			ev:    NewSuggestions("2026-W42", week, []string{"Pho"}),
+			key:   "new_suggestions:2026-W42",
+			url:   "/discover",
+			week:  "2026-10-12",
+			title: "1 new Side quest is in",
+			body:  "Pho",
+			chatT: "1 new Side quest is in: Pho. Open Discover →",
 		},
 		{
 			name:  "rotation review",
-			ev:    RotationReview("01J9DINNER", "Lemon orzo", week),
-			key:   "rotation_review:01J9DINNER",
+			ev:    RotationReview("01J9DINNER", "Lemon orzo", mustDate(t, "2026-10-14")),
+			key:   "rotation_review:01J9DINNER:2026-10-14",
 			url:   "/",
 			week:  "2026-10-12",
-			title: "Keep it in rotation?",
-			body:  "You tried Lemon orzo. Make it a Regular?",
-			chatT: "Keep it in rotation? You tried Lemon orzo. Make it a Regular? Open MealQuest →",
+			title: "How was Lemon orzo? Keep it in rotation?",
+			body:  "",
+			chatT: "How was Lemon orzo? Keep it in rotation? Open MealQuest →",
 		},
 	} {
 		ev := tc.ev

internal/db/dinners.sql.go

@@ -214,6 +214,26 @@ func (q *Queries) FailPendingDinnerGrounding(ctx context.Context, arg FailPendin
 	return result.RowsAffected()
 }
 
+const getActivePhotoBackfillJob = `-- name: GetActivePhotoBackfillJob :one
+SELECT id
+FROM jobs
+WHERE kind = ?1
+	AND status IN ('queued', 'running')
+	AND json_extract(payload, '$.dinner_id') IS NULL
+ORDER BY id
+LIMIT 1
+`
+
+// The id of the full photo backfill job (no dinner_id) of kind queued or
+// running. StartPhotoBackfill enqueues one only when there is none, so
+// there is at most one. Returns sql.ErrNoRows when there is none.
+func (q *Queries) GetActivePhotoBackfillJob(ctx context.Context, kind string) (string, error) {
+	row := q.db.QueryRowContext(ctx, getActivePhotoBackfillJob, kind)
+	var id string
+	err := row.Scan(&id)
+	return id, err
+}
+
 const getDinner = `-- name: GetDinner :one
 SELECT id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision FROM dinners
 WHERE id = ?
@@ -344,6 +364,58 @@ func (q *Queries) GroundDinner(ctx context.Context, arg GroundDinnerParams) (Din
 	return i, err
 }
 
+const groundFailedDinner = `-- name: GroundFailedDinner :execrows
+UPDATE dinners
+SET recipe_id = ?1,
+	photo_id = ?2,
+	method = COALESCE(method, ?3),
+	minutes_total = COALESCE(minutes_total, ?4),
+	difficulty = COALESCE(difficulty, ?5),
+	grounding_status = 'grounded',
+	grounding_error = NULL,
+	updated_at = ?6
+WHERE id = ?7
+	AND status <> 'archived'
+	AND grounding_status = 'failed'
+	AND photo_id IS NULL
+	AND recipe_url IS NULL
+	AND grounding_revision = ?8
+`
+
+type GroundFailedDinnerParams struct {
+	RecipeID          sql.NullString
+	PhotoID           sql.NullString
+	Method            sql.NullString
+	MinutesTotal      sql.NullInt64
+	Difficulty        sql.NullString
+	UpdatedAt         string
+	ID                string
+	GroundingRevision int64
+}
+
+// Records a photo backfill's grounding of a dinner it listed, while the
+// dinner is still unarchived, failed, photoless, without a recipe_url and at
+// the grounding_revision it was listed at; a dinner grounded by hand,
+// renamed or archived meanwhile is left as it is (0 rows). Like
+// GroundPendingDinner it keeps a method, minutes_total or difficulty a
+// member already set.
+func (q *Queries) GroundFailedDinner(ctx context.Context, arg GroundFailedDinnerParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, groundFailedDinner,
+		arg.RecipeID,
+		arg.PhotoID,
+		arg.Method,
+		arg.MinutesTotal,
+		arg.Difficulty,
+		arg.UpdatedAt,
+		arg.ID,
+		arg.GroundingRevision,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
 const groundPendingDinner = `-- name: GroundPendingDinner :execrows
 UPDATE dinners
 SET recipe_id = ?1,
@@ -444,6 +516,64 @@ func (q *Queries) ListDinnersByStatus(ctx context.Context, status string) ([]Din
 	return items, nil
 }
 
+const listPhotoBackfillDinners = `-- name: ListPhotoBackfillDinners :many
+SELECT id, name, normalized_name, status, origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, photo_id, grounding_status, updated_by, created_at, updated_at, recipe_url, grounding_error, grounding_revision FROM dinners
+WHERE status <> 'archived'
+	AND grounding_status = 'failed'
+	AND photo_id IS NULL
+	AND recipe_url IS NULL
+	AND id = COALESCE(?1, id)
+ORDER BY normalized_name, id
+`
+
+// The dinners a photo backfill grounds by name: unarchived, failed, with no
+// photo and no pasted recipe_url (the household's own link is never
+// replaced by a search), ordered by normalized name. A non-NULL id narrows
+// the list to that dinner. Grounded, manual and pending dinners are never
+// listed: they have a recipe, or a ground_dinner job grounding them.
+func (q *Queries) ListPhotoBackfillDinners(ctx context.Context, id sql.NullString) ([]Dinner, error) {
+	rows, err := q.db.QueryContext(ctx, listPhotoBackfillDinners, id)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []Dinner
+	for rows.Next() {
+		var i Dinner
+		if err := rows.Scan(
+			&i.ID,
+			&i.Name,
+			&i.NormalizedName,
+			&i.Status,
+			&i.Origin,
+			&i.Method,
+			&i.MinutesTotal,
+			&i.Difficulty,
+			&i.Cuisine,
+			&i.IsFavorite,
+			&i.RecipeID,
+			&i.PhotoID,
+			&i.GroundingStatus,
+			&i.UpdatedBy,
+			&i.CreatedAt,
+			&i.UpdatedAt,
+			&i.RecipeUrl,
+			&i.GroundingError,
+			&i.GroundingRevision,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listUnarchivedDinners = `-- name: ListUnarchivedDinners :many
 SELECT dinners.id, dinners.name, dinners.normalized_name, dinners.status, dinners.origin, dinners.method, dinners.minutes_total, dinners.difficulty, dinners.cuisine, dinners.is_favorite, dinners.recipe_id, dinners.photo_id, dinners.grounding_status, dinners.updated_by, dinners.created_at, dinners.updated_at, dinners.recipe_url, dinners.grounding_error, dinners.grounding_revision, recipes.source_url AS recipe_source_url
 FROM dinners
@@ -560,6 +690,40 @@ func (q *Queries) ListUnplannedQuestLogDinners(ctx context.Context, fromWeekStar
 	return items, nil
 }
 
+const refailDinnerGrounding = `-- name: RefailDinnerGrounding :execrows
+UPDATE dinners
+SET grounding_error = ?1,
+	updated_at = ?2
+WHERE id = ?3
+	AND status <> 'archived'
+	AND grounding_status = 'failed'
+	AND photo_id IS NULL
+	AND recipe_url IS NULL
+	AND grounding_revision = ?4
+`
+
+type RefailDinnerGroundingParams struct {
+	GroundingError    sql.NullString
+	UpdatedAt         string
+	ID                string
+	GroundingRevision int64
+}
+
+// Records why a photo backfill could not ground a dinner it listed, under
+// the same conditions as GroundFailedDinner (0 rows otherwise).
+func (q *Queries) RefailDinnerGrounding(ctx context.Context, arg RefailDinnerGroundingParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, refailDinnerGrounding,
+		arg.GroundingError,
+		arg.UpdatedAt,
+		arg.ID,
+		arg.GroundingRevision,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
 const setDinnerFavorite = `-- name: SetDinnerFavorite :one
 UPDATE dinners
 SET is_favorite = ?,

internal/db/notifications.sql.go

@@ -97,6 +97,22 @@ func (q *Queries) GetNotificationPref(ctx context.Context, event string) (Notifi
 	return i, err
 }
 
+const hasNotificationSince = `-- name: HasNotificationSince :one
+SELECT EXISTS (
+	SELECT 1 FROM notification_outbox
+	WHERE CAST(?1 AS TEXT) IS NULL OR created_at > CAST(?1 AS TEXT)
+) AS found
+`
+
+// Reports whether a notification was stored after since, or at all when
+// since is NULL.
+func (q *Queries) HasNotificationSince(ctx context.Context, since sql.NullString) (bool, error) {
+	row := q.db.QueryRowContext(ctx, hasNotificationSince, since)
+	var found bool
+	err := row.Scan(&found)
+	return found, err
+}
+
 const insertNotification = `-- name: InsertNotification :execrows
 INSERT INTO notification_outbox (
 	id, event_key, channel, payload, status, attempts, next_attempt_at, created_at, updated_at
@@ -166,6 +182,53 @@ func (q *Queries) ListNotificationPrefs(ctx context.Context) ([]NotificationPref
 	return items, nil
 }
 
+const listRecentNotifications = `-- name: ListRecentNotifications :many
+SELECT o.event_key, o.payload, o.created_at FROM notification_outbox o
+WHERE o.id = (
+	SELECT i.id FROM notification_outbox i
+	WHERE i.event_key = o.event_key
+	ORDER BY i.created_at DESC, i.id DESC
+	LIMIT 1
+)
+ORDER BY o.created_at DESC, o.event_key DESC
+LIMIT ?1
+`
+
+type ListRecentNotificationsRow struct {
+	EventKey  string
+	Payload   string
+	CreatedAt string
+}
+
+// Returns the last lim distinct events stored, newest first: one row per
+// event key, the last stored for it whatever its channel, so an event
+// stored for push and Google Chat is one row. The last, because a channel
+// switched on later can store the same event key again, and
+// HasNotificationSince counts that row: an event is as new as its newest
+// row, so marking it seen also covers that row.
+func (q *Queries) ListRecentNotifications(ctx context.Context, lim int64) ([]ListRecentNotificationsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listRecentNotifications, lim)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListRecentNotificationsRow
+	for rows.Next() {
+		var i ListRecentNotificationsRow
+		if err := rows.Scan(&i.EventKey, &i.Payload, &i.CreatedAt); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const markNotificationSent = `-- name: MarkNotificationSent :execrows
 UPDATE notification_outbox
 SET status = 'sent', attempts = attempts + 1, next_attempt_at = NULL, updated_at = ?1

internal/db/querier.go

@@ -24,6 +24,9 @@ type Querier interface {
 	// Marks the oldest queued job running and returns it. Returns sql.ErrNoRows
 	// when no job is queued.
 	ClaimNextJob(ctx context.Context, now sql.NullString) (Job, error)
+	// Claims one period of a schedule. The insert is the claim: 1 row means
+	// this caller owns the period, 0 rows means it was already claimed.
+	ClaimScheduleRun(ctx context.Context, arg ClaimScheduleRunParams) (int64, error)
 	// Clears every day's calendar event id: none is on the chosen calendar.
 	ClearCalendarEvents(ctx context.Context, updatedAt string) error
 	// Records that Google refuses the stored grant: clears the refresh token and
@@ -114,6 +117,10 @@ type Querier interface {
 	// when there is none, so there is at most one. Returns sql.ErrNoRows when
 	// there is none.
 	GetActiveDraftJob(ctx context.Context, arg GetActiveDraftJobParams) (GetActiveDraftJobRow, error)
+	// The id of the full photo backfill job (no dinner_id) of kind queued or
+	// running. StartPhotoBackfill enqueues one only when there is none, so
+	// there is at most one. Returns sql.ErrNoRows when there is none.
+	GetActivePhotoBackfillJob(ctx context.Context, kind string) (string, error)
 	// The batch still pending or running, oldest first. Returns sql.ErrNoRows
 	// when there is none.
 	GetActiveSuggestionBatch(ctx context.Context) (SuggestionBatch, error)
@@ -172,6 +179,13 @@ type Querier interface {
 	// unknown id, returns sql.ErrNoRows. A method, minutes_total or difficulty
 	// no longer as observed is kept: a member edited it while it was grounding.
 	GroundDinner(ctx context.Context, arg GroundDinnerParams) (Dinner, error)
+	// Records a photo backfill's grounding of a dinner it listed, while the
+	// dinner is still unarchived, failed, photoless, without a recipe_url and at
+	// the grounding_revision it was listed at; a dinner grounded by hand,
+	// renamed or archived meanwhile is left as it is (0 rows). Like
+	// GroundPendingDinner it keeps a method, minutes_total or difficulty a
+	// member already set.
+	GroundFailedDinner(ctx context.Context, arg GroundFailedDinnerParams) (int64, error)
 	// Records the background grounding of an unarchived dinner still pending at
 	// the grounding_revision it was grounded for; a dinner grounded some other
 	// way, renamed or archived meanwhile is left as it is (0 rows). A method,
@@ -179,6 +193,9 @@ type Querier interface {
 	// them only when a member edited them while it was grounding. Like
 	// GroundDinner it clears the pasted recipe_url: the recipe replaces the link.
 	GroundPendingDinner(ctx context.Context, arg GroundPendingDinnerParams) (int64, error)
+	// Reports whether a notification was stored after since, or at all when
+	// since is NULL.
+	HasNotificationSince(ctx context.Context, since sql.NullString) (bool, error)
 	// Stores a pending notification for one channel, due at once. A row already
 	// stored for the event key and channel, in any status, is left unchanged and
 	// no row is inserted.
@@ -200,6 +217,12 @@ type Querier interface {
 	// The pending Rotation checks whose dinner is still tried, oldest plan
 	// date first, with their dinners.
 	ListPendingRotationReviews(ctx context.Context) ([]ListPendingRotationReviewsRow, error)
+	// The dinners a photo backfill grounds by name: unarchived, failed, with no
+	// photo and no pasted recipe_url (the household's own link is never
+	// replaced by a search), ordered by normalized name. A non-NULL id narrows
+	// the list to that dinner. Grounded, manual and pending dinners are never
+	// listed: they have a recipe, or a ground_dinner job grounding them.
+	ListPhotoBackfillDinners(ctx context.Context, id sql.NullString) ([]Dinner, error)
 	// The days of plan plan_id with their dinners, Monday first. A day with
 	// no dinner is left out.
 	ListPlanDays(ctx context.Context, planID string) ([]ListPlanDaysRow, error)
@@ -209,6 +232,13 @@ type Querier interface {
 	// Every stored subscription with its keys, for the push sender, oldest
 	// first.
 	ListPushSubscriptions(ctx context.Context) ([]ListPushSubscriptionsRow, error)
+	// Returns the last lim distinct events stored, newest first: one row per
+	// event key, the last stored for it whatever its channel, so an event
+	// stored for push and Google Chat is one row. The last, because a channel
+	// switched on later can store the same event key again, and
+	// HasNotificationSince counts that row: an event is as new as its newest
+	// row, so marking it seen also covers that row.
+	ListRecentNotifications(ctx context.Context, lim int64) ([]ListRecentNotificationsRow, error)
 	// Reads for the AI household context block (internal/ai/harness).
 	// The most recent names the household turned down, newest first, as
 	// ListPassedNames has them.
@@ -251,6 +281,10 @@ type Querier interface {
 	// Records list id sent to Google Chat at sent_to_chat_at, its send
 	// confirmed, unless it is frozen into the Supply archive.
 	MarkShoppingListSentToChat(ctx context.Context, arg MarkShoppingListSentToChatParams) (int64, error)
+	// Moves updates_seen_at forward to seen_at; affects no row when it is
+	// already at or after seen_at, so it never moves back. It is not a settings
+	// edit: updated_by and updated_at are left as they are.
+	MarkUpdatesSeen(ctx context.Context, seenAt string) (int64, error)
 	// Records an edit of plan id, raising its revision: a synced plan becomes
 	// changed, any other keeps its status.
 	MarkWeekPlanEdited(ctx context.Context, arg MarkWeekPlanEditedParams) error
@@ -290,6 +324,9 @@ type Querier interface {
 	// Records a new draft over plan id: its status and note, raising its
 	// revision.
 	RedraftWeekPlan(ctx context.Context, arg RedraftWeekPlanParams) error
+	// Records why a photo backfill could not ground a dinner it listed, under
+	// the same conditions as GroundFailedDinner (0 rows otherwise).
+	RefailDinnerGrounding(ctx context.Context, arg RefailDinnerGroundingParams) (int64, error)
 	// Records a generation of list id from plan plan_id.
 	RegenerateShoppingList(ctx context.Context, arg RegenerateShoppingListParams) error
 	// Records a failed delivery and when to try again. The lease must still be

internal/db/schedule_runs.sql.go

@@ -0,0 +1,38 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: schedule_runs.sql
+
+package db
+
+import (
+	"context"
+)
+
+const claimScheduleRun = `-- name: ClaimScheduleRun :execrows
+INSERT INTO schedule_runs (id, schedule, period_key, created_at)
+VALUES (?, ?, ?, ?)
+ON CONFLICT (schedule, period_key) DO NOTHING
+`
+
+type ClaimScheduleRunParams struct {
+	ID        string
+	Schedule  string
+	PeriodKey string
+	CreatedAt string
+}
+
+// Claims one period of a schedule. The insert is the claim: 1 row means
+// this caller owns the period, 0 rows means it was already claimed.
+func (q *Queries) ClaimScheduleRun(ctx context.Context, arg ClaimScheduleRunParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, claimScheduleRun,
+		arg.ID,
+		arg.Schedule,
+		arg.PeriodKey,
+		arg.CreatedAt,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}

internal/db/settings.sql.go

@@ -161,6 +161,23 @@ func (q *Queries) GetRecipeSearchSettings(ctx context.Context) (RecipeSearchSett
 	return i, err
 }
 
+const markUpdatesSeen = `-- name: MarkUpdatesSeen :execrows
+UPDATE household_settings
+SET updates_seen_at = CAST(?1 AS TEXT)
+WHERE id = 1 AND (updates_seen_at IS NULL OR updates_seen_at < CAST(?1 AS TEXT))
+`
+
+// Moves updates_seen_at forward to seen_at; affects no row when it is
+// already at or after seen_at, so it never moves back. It is not a settings
+// edit: updated_by and updated_at are left as they are.
+func (q *Queries) MarkUpdatesSeen(ctx context.Context, seenAt string) (int64, error) {
+	result, err := q.db.ExecContext(ctx, markUpdatesSeen, seenAt)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
 const recordChatTest = `-- name: RecordChatTest :execrows
 UPDATE chat_settings
 SET last_test_at = ?, last_test_status = ?, updated_at = ?

internal/dinners/backfill.go

@@ -0,0 +1,199 @@
+package dinners
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// KindBackfillPhotos is the job that grounds, by name, the dinners left
+// without a photo: those whose grounding failed and that have no pasted
+// recipe_url (ListPhotoBackfillDinners).
+const KindBackfillPhotos = "backfill_dinner_photos"
+
+// Photo backfill outcomes for one dinner.
+const (
+	BackfillGrounded = "grounded"
+	BackfillFailed   = "failed"
+	// BackfillSkipped: the dinner was grounded by hand, renamed or archived
+	// while the backfill grounded it, so the backfill left it as it is.
+	BackfillSkipped = "skipped"
+)
+
+// PhotoBackfillEligible reports whether a photo backfill grounds r: the
+// condition ListPhotoBackfillDinners lists dinners by, and GroundFailedDinner
+// and RefailDinnerGrounding write under, for one dinner. The dinner is
+// unarchived, failed, with no photo and no pasted recipe_url.
+func PhotoBackfillEligible(r db.Dinner) bool {
+	return r.Status != StatusArchived &&
+		r.GroundingStatus == GroundingFailed &&
+		!r.PhotoID.Valid &&
+		!r.RecipeUrl.Valid
+}
+
+// BackfillJob is the KindBackfillPhotos payload. DinnerID narrows the
+// backfill to that dinner; empty backfills every dinner without a photo.
+type BackfillJob struct {
+	DinnerID string `json:"dinner_id,omitempty"`
+}
+
+// BackfillOutcome is what a photo backfill did for one dinner. Reason is
+// set only for BackfillFailed: the Reason recorded as its grounding_error.
+type BackfillOutcome struct {
+	DinnerID string  `json:"dinner_id"`
+	Outcome  string  `json:"outcome"`
+	Reason   *string `json:"reason"`
+}
+
+// backfillResult is the KindBackfillPhotos result: the outcome of each
+// dinner the backfill tried, in the order it tried them.
+type backfillResult struct {
+	Dinners []BackfillOutcome `json:"dinners"`
+}
+
+func (r backfillResult) PublicJSON() ([]byte, error) { return json.Marshal(r) }
+
+// StartPhotoBackfill enqueues a KindBackfillPhotos job over every dinner
+// without a photo and returns its id, without waiting for it. While a full
+// backfill is queued or running it enqueues nothing and returns that job's
+// id instead, so two passes never ground the same dinner at once; the jobs
+// table holds the claim, so it holds across restarts too.
+func (s *Service) StartPhotoBackfill(ctx context.Context) (string, error) {
+	var id string
+	created := false
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		active, err := db.New(tx).GetActivePhotoBackfillJob(ctx, KindBackfillPhotos)
+		switch {
+		case errors.Is(err, sql.ErrNoRows):
+		case err != nil:
+			return fmt.Errorf("dinners: read active photo backfill: %w", err)
+		default:
+			id = active
+			return nil
+		}
+		id, err = s.backfillJob.EnqueueTx(ctx, tx, BackfillJob{})
+		if err != nil {
+			return fmt.Errorf("dinners: enqueue photo backfill: %w", err)
+		}
+		created = true
+		return nil
+	})
+	if err != nil {
+		return "", err
+	}
+	if created {
+		s.backfillJob.Wake()
+	}
+	return id, nil
+}
+
+// errBackfillNotRecorded fails a photo backfill that could not record the
+// outcome of one or more of its dinners.
+var errBackfillNotRecorded = errors.New("dinners: photo backfill: dinner outcomes not recorded")
+
+// runBackfillJob grounds each dinner ListPhotoBackfillDinners lists for p,
+// one at a time, with recipes.Grounder.Ground on its name: the first ranked
+// candidate whose photo caches and whose ingredients normalize grounds it,
+// with the recipe's source URL and site kept as any grounding keeps them.
+// Success records the recipe and photo with grounding_status grounded;
+// failure leaves the dinner failed with the new Reason as its
+// grounding_error, for the household to fix its recipe by hand. One
+// dinner's failure, its search's, model's or database write's, never stops
+// the others. A failure to list the dinners, or the job's context ending,
+// fails the job at once. A write that failed fails the job once every
+// dinner has been tried, as a grounding job's failed write does, with the
+// outcomes published as its result, so the job never reports done for a
+// dinner whose outcome is not stored.
+func (s *Service) runBackfillJob(ctx context.Context, p BackfillJob, publish func(backfillResult) error) (backfillResult, error) {
+	q := db.New(s.st.Reader)
+	rows, err := q.ListPhotoBackfillDinners(ctx, sql.NullString{String: p.DinnerID, Valid: p.DinnerID != ""})
+	if err != nil {
+		return backfillResult{}, fmt.Errorf("dinners: photo backfill: list: %w", err)
+	}
+	res := backfillResult{Dinners: make([]BackfillOutcome, 0, len(rows))}
+	grounded, unrecorded := false, false
+	for _, row := range rows {
+		out, recorded, err := s.backfillDinner(ctx, row)
+		if err != nil {
+			return backfillResult{}, err
+		}
+		grounded = grounded || out.Outcome == BackfillGrounded
+		unrecorded = unrecorded || !recorded
+		res.Dinners = append(res.Dinners, out)
+	}
+	if grounded {
+		s.wake()
+	}
+	if unrecorded {
+		if err := publish(res); err != nil {
+			return backfillResult{}, errors.Join(errBackfillNotRecorded, err)
+		}
+		return backfillResult{}, errBackfillNotRecorded
+	}
+	return res, nil
+}
+
+// backfillDinner grounds row, a dinner ListPhotoBackfillDinners listed, as
+// runBackfillJob describes, and reports whether its outcome was recorded.
+// Its error is only the job's context ending.
+func (s *Service) backfillDinner(ctx context.Context, row db.Dinner) (BackfillOutcome, bool, error) {
+	out := BackfillOutcome{DinnerID: row.ID}
+	w := db.New(s.st.Writer)
+	gr, err := s.grounder.Ground(ctx, row.Name, row.Name)
+	if ctxErr := ctx.Err(); ctxErr != nil {
+		return BackfillOutcome{}, false, ctxErr
+	}
+	if err != nil {
+		reason := reasonFor(err, false)
+		// Only the reason is logged: the error may quote a dependency's
+		// response, which jobs never store, return or log.
+		s.logger.InfoContext(ctx, "dinner photo backfill failed", "dinner_id", row.ID, "reason", reason)
+		n, err := w.RefailDinnerGrounding(ctx, db.RefailDinnerGroundingParams{
+			GroundingError:    sql.NullString{String: reason, Valid: true},
+			UpdatedAt:         store.Now().String(),
+			ID:                row.ID,
+			GroundingRevision: row.GroundingRevision,
+		})
+		out, recorded := s.backfillRecorded(ctx, out, BackfillFailed, reason, n, err)
+		return out, recorded, nil
+	}
+	n, err := w.GroundFailedDinner(ctx, db.GroundFailedDinnerParams{
+		RecipeID:          sql.NullString{String: gr.RecipeID, Valid: true},
+		PhotoID:           sql.NullString{String: gr.PhotoID, Valid: true},
+		Method:            sql.NullString{String: gr.Method, Valid: true},
+		MinutesTotal:      nullInt(gr.MinutesTotal),
+		Difficulty:        sql.NullString{String: gr.Difficulty, Valid: true},
+		UpdatedAt:         store.Now().String(),
+		ID:                row.ID,
+		GroundingRevision: row.GroundingRevision,
+	})
+	out, recorded := s.backfillRecorded(ctx, out, BackfillGrounded, "", n, err)
+	return out, recorded, nil
+}
+
+// backfillRecorded is out once the backfill recorded outcome (with reason,
+// for BackfillFailed) on the dinner, writing n rows with err: a dinner that
+// changed meanwhile (no row) is BackfillSkipped, and one whose write failed
+// is BackfillFailed with ReasonGroundingError, the dinner left as it was,
+// and not recorded.
+func (s *Service) backfillRecorded(ctx context.Context, out BackfillOutcome, outcome, reason string, n int64, err error) (BackfillOutcome, bool) {
+	switch {
+	case err != nil:
+		// The error is a database error, never a dependency's text.
+		s.logger.ErrorContext(ctx, "dinner photo backfill not recorded", "dinner_id", out.DinnerID, "error", err)
+		out.Outcome, reason = BackfillFailed, ReasonGroundingError
+	case n == 0:
+		out.Outcome, reason = BackfillSkipped, ""
+	default:
+		out.Outcome = outcome
+	}
+	if reason != "" {
+		out.Reason = &reason
+	}
+	return out, err == nil
+}

internal/dinners/backfill_test.go

@@ -0,0 +1,425 @@
+package dinners_test
+
+import (
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"slices"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// failedDinner stores a Regular named name whose grounding failed with
+// no_recipe_found, without a photo or recipe_url, and returns its id.
+func (e *env) failedDinner(t *testing.T, name string) string {
+	t.Helper()
+	q := db.New(e.st.Writer)
+	now := store.Now().String()
+	row, err := q.CreateDinner(t.Context(), db.CreateDinnerParams{
+		ID:              store.NewID(),
+		Name:            name,
+		NormalizedName:  harness.Normalize(name),
+		Status:          dinners.StatusRegular,
+		Origin:          "regular",
+		GroundingStatus: dinners.GroundingPending,
+		UpdatedBy:       sql.NullString{String: member, Valid: true},
+		CreatedAt:       now,
+		UpdatedAt:       now,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := q.FailPendingDinnerGrounding(t.Context(), db.FailPendingDinnerGroundingParams{
+		GroundingError:    sql.NullString{String: dinners.ReasonNoRecipe, Valid: true},
+		UpdatedAt:         now,
+		ID:                row.ID,
+		GroundingRevision: row.GroundingRevision,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	return row.ID
+}
+
+func outcome(id, out string, reason *string) dinners.BackfillOutcome {
+	return dinners.BackfillOutcome{DinnerID: id, Outcome: out, Reason: reason}
+}
+
+func checkOutcomes(t *testing.T, got, want []dinners.BackfillOutcome) {
+	t.Helper()
+	gj, _ := json.Marshal(got)
+	wj, _ := json.Marshal(want)
+	if string(gj) != string(wj) {
+		t.Fatalf("outcomes = %s, want %s", gj, wj)
+	}
+}
+
+func TestBackfillGroundsFirstCandidateWithAPhoto(t *testing.T) {
+	t.Parallel()
+	e := newUnstartedEnv(t)
+	// curryA ranks first but its photo is gone; curryB's photo caches.
+	delete(e.images.JPEGs, "https://a.example/curry.jpg")
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
+	id := e.failedDinner(t, "Chicken curry")
+
+	got, err := e.svc.RunBackfillJob(t.Context(), dinners.BackfillJob{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	checkOutcomes(t, got, []dinners.BackfillOutcome{outcome(id, dinners.BackfillGrounded, nil)})
+
+	row := e.dinner(t, id)
+	if row.GroundingStatus != dinners.GroundingGrounded || !row.PhotoID.Valid || !row.RecipeID.Valid || row.GroundingError.Valid {
+		t.Fatalf("dinner = %+v, want grounded with a photo and no error", row)
+	}
+	rec, err := db.New(e.st.Reader).GetRecipe(t.Context(), row.RecipeID.String)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rec.SourceUrl != curryB || rec.SiteName.String != "B Kitchen" || rec.PhotoID != row.PhotoID {
+		t.Errorf("recipe = %s from %q photo %s, want %s from B Kitchen photo %s", rec.SourceUrl, rec.SiteName.String, rec.PhotoID.String, curryB, row.PhotoID.String)
+	}
+	if got := e.search.Queries(); !slices.Equal(got, []string{"Chicken curry"}) {
+		t.Errorf("searched %q, want the dinner's name", got)
+	}
+}
+
+func TestBackfillReusesCachedRecipeAndPhoto(t *testing.T) {
+	t.Parallel()
+	e := newUnstartedEnv(t)
+	e.search.Results["Curry chicken"] = []recipes.Candidate{{URL: curryA}}
+	// One reply: the second dinner must reuse the recipe the first stored.
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	first := e.failedDinner(t, "Chicken curry")
+	second := e.failedDinner(t, "Curry chicken")
+
+	got, err := e.svc.RunBackfillJob(t.Context(), dinners.BackfillJob{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	checkOutcomes(t, got, []dinners.BackfillOutcome{
+		outcome(first, dinners.BackfillGrounded, nil),
+		outcome(second, dinners.BackfillGrounded, nil),
+	})
+	a, b := e.dinner(t, first), e.dinner(t, second)
+	if a.RecipeID != b.RecipeID || a.PhotoID != b.PhotoID || !a.PhotoID.Valid {
+		t.Errorf("dinners grounded in recipe %s photo %s and recipe %s photo %s, want the same cached ones",
+			a.RecipeID.String, a.PhotoID.String, b.RecipeID.String, b.PhotoID.String)
+	}
+	if n := len(e.model.Requests()); n != 1 {
+		t.Errorf("normalize_recipe ran %d times, want 1", n)
+	}
+	if n := slices.Index(e.pages.Fetched(), curryA); n < 0 || slices.Contains(e.pages.Fetched()[n+1:], curryA) {
+		t.Errorf("fetched %q, want %s fetched once", e.pages.Fetched(), curryA)
+	}
+}
+
+func TestBackfillIsolatesEachDinnersFailure(t *testing.T) {
+	t.Parallel()
+	e := newUnstartedEnv(t)
+	e.search.Fail = map[string]error{"Broken search": errors.New("search provider down")}
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	// Listed by normalized name: both failures come before the curry.
+	broken := e.failedDinner(t, "Broken search")
+	curry := e.failedDinner(t, "Chicken curry")
+	absent := e.failedDinner(t, "Abalone surprise")
+
+	got, err := e.svc.RunBackfillJob(t.Context(), dinners.BackfillJob{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	checkOutcomes(t, got, []dinners.BackfillOutcome{
+		outcome(absent, dinners.BackfillFailed, ptr(dinners.ReasonNoRecipe)),
+		outcome(broken, dinners.BackfillFailed, ptr(dinners.ReasonSearchFailed)),
+		outcome(curry, dinners.BackfillGrounded, nil),
+	})
+	for id, reason := range map[string]string{absent: dinners.ReasonNoRecipe, broken: dinners.ReasonSearchFailed} {
+		row := e.dinner(t, id)
+		if row.GroundingStatus != dinners.GroundingFailed || row.GroundingError.String != reason || row.PhotoID.Valid {
+			t.Errorf("dinner %s = %+v, want failed with %s and no photo", row.Name, row, reason)
+		}
+	}
+	if row := e.dinner(t, curry); row.GroundingStatus != dinners.GroundingGrounded || !row.PhotoID.Valid {
+		t.Errorf("curry = %+v, want grounded with a photo", row)
+	}
+}
+
+func TestBackfillSkipsDinnersNotMissingAPhoto(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	c, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Chicken curry")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.waitJob(t, *c.GroundingJobID)
+	if row := e.dinner(t, c.ID); row.GroundingStatus != dinners.GroundingGrounded {
+		t.Fatalf("dinner = %+v, want grounded", row)
+	}
+	// A failed dinner with a pasted link keeps that link for a fix by hand.
+	linked, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Mystery pie"), RecipeURL: ptr("https://d.example/pie")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.waitJob(t, *linked.GroundingJobID)
+	if row := e.dinner(t, linked.ID); row.GroundingStatus != dinners.GroundingFailed {
+		t.Fatalf("linked dinner = %+v, want failed", row)
+	}
+	archived := e.failedDinner(t, "Old stew")
+	if _, err := e.svc.Archive(t.Context(), archived, member); err != nil {
+		t.Fatal(err)
+	}
+	searched := len(e.search.Queries())
+
+	id, err := e.svc.StartPhotoBackfill(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	job := e.waitJob(t, id)
+	if job.Kind != dinners.KindBackfillPhotos || string(job.Result) != `{"dinners":[]}` {
+		t.Fatalf("job = %+v (result %s), want a backfill with no dinners", job, job.Result)
+	}
+	if got := e.search.Queries()[searched:]; len(got) != 0 {
+		t.Errorf("backfill searched %q, want nothing", got)
+	}
+}
+
+// TestPhotoBackfillEligibleIsWhatTheBackfillLists holds the API's
+// photo_backfill_eligible to ListPhotoBackfillDinners for a dinner the
+// backfill grounds and for each kind it never does.
+func TestPhotoBackfillEligibleIsWhatTheBackfillLists(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	grounded, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Chicken curry")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.waitJob(t, *grounded.GroundingJobID)
+	linked, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Mystery pie"), RecipeURL: ptr("https://d.example/pie")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.waitJob(t, *linked.GroundingJobID)
+	failed := e.failedDinner(t, "Abalone surprise")
+	archived, err := e.svc.Archive(t.Context(), e.failedDinner(t, "Old stew"), member)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	shown := map[string]dinners.Dinner{archived.ID: archived}
+	regulars, err := e.svc.List(t.Context(), dinners.StatusRegular)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, d := range regulars {
+		shown[d.ID] = d
+	}
+	q := db.New(e.st.Reader)
+	for id, want := range map[string]bool{grounded.ID: false, linked.ID: false, failed: true, archived.ID: false} {
+		listed, err := q.ListPhotoBackfillDinners(t.Context(), sql.NullString{String: id, Valid: true})
+		if err != nil {
+			t.Fatal(err)
+		}
+		d, ok := shown[id]
+		if !ok {
+			t.Fatalf("dinner %s not shown", id)
+		}
+		if got := len(listed) == 1; got != want || d.PhotoBackfillEligible != want {
+			t.Errorf("%s: listed %t, photo_backfill_eligible %t, want both %t", d.Name, got, d.PhotoBackfillEligible, want)
+		}
+	}
+}
+
+func TestBackfillOfOneDinnerGroundsOnlyIt(t *testing.T) {
+	t.Parallel()
+	e := newUnstartedEnv(t)
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	curry := e.failedDinner(t, "Chicken curry")
+	other := e.failedDinner(t, "Abalone surprise")
+
+	got, err := e.svc.RunBackfillJob(t.Context(), dinners.BackfillJob{DinnerID: curry})
+	if err != nil {
+		t.Fatal(err)
+	}
+	checkOutcomes(t, got, []dinners.BackfillOutcome{outcome(curry, dinners.BackfillGrounded, nil)})
+	if row := e.dinner(t, other); row.GroundingStatus != dinners.GroundingFailed || row.PhotoID.Valid {
+		t.Errorf("other dinner = %+v, want left failed", row)
+	}
+	if got := e.search.Queries(); !slices.Equal(got, []string{"Chicken curry"}) {
+		t.Errorf("searched %q, want only the dinner's name", got)
+	}
+}
+
+func TestBackfillLeavesDinnerChangedWhileGrounding(t *testing.T) {
+	t.Parallel()
+	e := newUnstartedEnv(t)
+	id := e.failedDinner(t, "Chicken curry")
+	gate := make(chan struct{})
+	e.search.Gate = gate
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+
+	done := make(chan []dinners.BackfillOutcome)
+	go func() {
+		got, err := e.svc.RunBackfillJob(t.Context(), dinners.BackfillJob{DinnerID: id})
+		if err != nil {
+			t.Error(err)
+		}
+		done <- got
+	}()
+	// The backfill listed the dinner and waits at its search.
+	for len(e.search.Queries()) == 0 {
+		time.Sleep(time.Millisecond)
+	}
+	if _, err := e.svc.Update(t.Context(), id, dinners.Patch{Name: ptr("Chicken korma")}, member); err != nil {
+		t.Fatal(err)
+	}
+	close(gate)
+	checkOutcomes(t, <-done, []dinners.BackfillOutcome{outcome(id, dinners.BackfillSkipped, nil)})
+	if row := e.dinner(t, id); row.GroundingStatus != dinners.GroundingFailed || row.PhotoID.Valid {
+		t.Errorf("dinner = %+v, want left failed without a photo", row)
+	}
+}
+
+// triggerAtOnce calls svc.StartPhotoBackfill from n goroutines released
+// together and returns the job ids they got.
+func triggerAtOnce(t *testing.T, svc *dinners.Service, n int) []string {
+	t.Helper()
+	ids := make([]string, n)
+	errs := make([]error, n)
+	release := make(chan struct{})
+	var wg sync.WaitGroup
+	for i := range n {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-release
+			ids[i], errs[i] = svc.StartPhotoBackfill(t.Context())
+		}()
+	}
+	close(release)
+	wg.Wait()
+	if err := errors.Join(errs...); err != nil {
+		t.Fatal(err)
+	}
+	return ids
+}
+
+// backfillJobs counts the KindBackfillPhotos jobs in st.
+func backfillJobs(t *testing.T, st *store.Store) int {
+	t.Helper()
+	var n int
+	if err := st.Reader.QueryRowContext(t.Context(), `SELECT count(*) FROM jobs WHERE kind = ?`, dinners.KindBackfillPhotos).Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	return n
+}
+
+func TestStartPhotoBackfillIsSingleFlight(t *testing.T) {
+	t.Parallel()
+	const triggers = 8
+	dataDir := t.TempDir()
+	st := openStore(t, dataDir)
+	e := newUnstartedEnvOn(t, st, dataDir)
+	e.failedDinner(t, "Chicken curry")
+	gate := make(chan struct{})
+	e.search.Gate = gate
+
+	// Queued: simultaneous triggers all get the one pass they enqueued.
+	ids := triggerAtOnce(t, e.svc, triggers)
+	first := ids[0]
+	for _, id := range ids {
+		if id != first {
+			t.Fatalf("simultaneous triggers = %q, want one job id", ids)
+		}
+	}
+	if n := backfillJobs(t, st); n != 1 {
+		t.Fatalf("%d backfill jobs after simultaneous triggers, want 1", n)
+	}
+
+	// After a restart the queued pass is still the one: the claim is the
+	// stored job, not the process's memory.
+	if err := st.Close(); err != nil {
+		t.Fatal(err)
+	}
+	st = openStore(t, dataDir)
+	restarted := newUnstartedEnvOn(t, st, dataDir)
+	restarted.search.Gate = gate
+	restarted.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	if again, err := restarted.svc.StartPhotoBackfill(t.Context()); err != nil || again != first {
+		t.Fatalf("trigger after restart = %q, %v; want the queued %q", again, err, first)
+	}
+
+	// Running: the pass waits at its search, and simultaneous triggers all
+	// return it.
+	restarted.start(t)
+	for len(restarted.search.Queries()) == 0 {
+		time.Sleep(time.Millisecond)
+	}
+	for _, id := range triggerAtOnce(t, restarted.svc, triggers) {
+		if id != first {
+			t.Fatalf("trigger while running = %q, want the running %q", id, first)
+		}
+	}
+	if n := backfillJobs(t, st); n != 1 {
+		t.Fatalf("%d backfill jobs, want 1", n)
+	}
+
+	// Finished: the next trigger starts a new pass.
+	close(gate)
+	if job := restarted.waitJob(t, first); job.Status != jobs.StatusSucceeded {
+		t.Fatalf("job = %+v (result %s), want succeeded", job, job.Result)
+	}
+	next, err := restarted.svc.StartPhotoBackfill(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if next == first {
+		t.Fatalf("trigger after the pass finished = %q, want a new job", next)
+	}
+	restarted.waitJob(t, next)
+}
+
+func TestBackfillFailsJobWhenAWriteFails(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	absent := e.failedDinner(t, "Abalone surprise")
+	curry := e.failedDinner(t, "Chicken curry")
+	if _, err := e.st.Writer.ExecContext(t.Context(), `CREATE TRIGGER refuse_grounded BEFORE UPDATE OF grounding_status ON dinners
+		WHEN NEW.id = '`+curry+`' AND NEW.grounding_status = 'grounded'
+		BEGIN SELECT RAISE(ABORT, 'grounded refused'); END`); err != nil {
+		t.Fatal(err)
+	}
+
+	id, err := e.svc.StartPhotoBackfill(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	job := e.waitJob(t, id)
+	if job.Status != jobs.StatusFailed || job.Error == nil || *job.Error != jobs.CodeInternal {
+		t.Fatalf("job = %+v, want failed with %s", job, jobs.CodeInternal)
+	}
+	var got struct {
+		Dinners []dinners.BackfillOutcome `json:"dinners"`
+	}
+	if err := json.Unmarshal(job.Result, &got); err != nil {
+		t.Fatalf("result %s: %v", job.Result, err)
+	}
+	// The other dinner was still tried and recorded.
+	checkOutcomes(t, got.Dinners, []dinners.BackfillOutcome{
+		outcome(absent, dinners.BackfillFailed, ptr(dinners.ReasonNoRecipe)),
+		outcome(curry, dinners.BackfillFailed, ptr(dinners.ReasonGroundingError)),
+	})
+	if row := e.dinner(t, curry); row.GroundingStatus != dinners.GroundingFailed || row.PhotoID.Valid {
+		t.Errorf("curry = %+v, want left failed without a photo", row)
+	}
+}

internal/dinners/detail.go

@@ -147,11 +147,11 @@ func readRecipe(ctx context.Context, q *db.Queries, recipeID string, d *Detail)
 		return fmt.Errorf("recipe %s: %w", recipeID, err)
 	}
 	if !IsManualRecipe(rec.SourceUrl) {
-		site, err := pageSiteName(rec.SiteName, rec.SourceUrl)
+		src, err := SourceOf(rec.SiteName, rec.SourceUrl)
 		if err != nil {
 			return err
 		}
-		d.Source = &Source{SiteName: site, URL: safeSourceURL(rec.SourceUrl)}
+		d.Source = &src
 	}
 	ings, err := q.ListRecipeIngredients(ctx, recipeID)
 	if err != nil {
@@ -182,7 +182,22 @@ func readRecipe(ctx context.Context, q *db.Queries, recipeID string, d *Detail)
 	return nil
 }
 
-// pageSiteName is the stored site name of a recipe fetched from sourceURL
+// SourceOf is the Source of a recipe fetched from sourceURL whose stored
+// site name is siteName: the name only when the page gave it (see
+// pageSiteName) and the link only when it is free of secrets (see
+// safeSourceURL). It is the one way a fetched recipe's source reaches a
+// client. A sourceURL that does not parse is an error, whether or not a
+// site name is stored.
+func SourceOf(siteName sql.NullString, sourceURL string) (Source, error) {
+	link, err := url.Parse(sourceURL)
+	if err != nil {
+		// Not wrapped: url.Parse's error quotes the link.
+		return Source{}, errors.New("source url does not parse")
+	}
+	return Source{SiteName: pageSiteName(siteName, link), URL: safeSourceURL(sourceURL)}, nil
+}
+
+// pageSiteName is the stored site name of a recipe fetched from link
 // when it is one the page gave, else nil. A page that names no site is
 // stored under recipes.HostSiteName of the URL it was served from: the
 // pasted link's host, which may hold a personal token (a private
@@ -192,23 +207,18 @@ func readRecipe(ctx context.Context, q *db.Queries, recipeID string, d *Detail)
 // is treated as one and withheld. A site that names itself as a domain,
 // such as "Food.com", loses its name with them: a credit that does not
 // name the site is better than one that leaks a link.
-func pageSiteName(stored sql.NullString, sourceURL string) (*string, error) {
+func pageSiteName(stored sql.NullString, link *url.URL) *string {
 	if !stored.Valid {
-		return nil, nil
-	}
-	link, err := url.Parse(sourceURL)
-	if err != nil {
-		// Not wrapped: url.Parse's error quotes the link.
-		return nil, errors.New("source url does not parse")
+		return nil
 	}
 	name := stored.String
 	if strings.EqualFold(name, recipes.HostSiteName(link)) || net.ParseIP(name) != nil {
-		return nil, nil
+		return nil
 	}
 	if u, err := url.Parse("https://" + name + "/"); err == nil && u.Host == name && strings.Contains(name, ".") {
-		return nil, nil
+		return nil
 	}
-	return &name, nil
+	return &name
 }
 
 // safeSourceURL is sourceURL when it is verifiably free of secrets — an

internal/dinners/dinners.go

@@ -79,6 +79,11 @@ type Dinner struct {
 	UpdatedBy      *string `json:"updated_by"`
 	CreatedAt      string  `json:"created_at"`
 	UpdatedAt      string  `json:"updated_at"`
+
+	// PhotoBackfillEligible is whether a photo backfill grounds the dinner
+	// (PhotoBackfillEligible): false for one with a pasted recipe link,
+	// which a search never replaces.
+	PhotoBackfillEligible bool `json:"photo_backfill_eligible"`
 }
 
 // NewRegular is a Regular to add: its Name, which the household always
@@ -138,6 +143,11 @@ type Service struct {
 	grounder  *recipes.Grounder
 	logger    *slog.Logger
 	groundJob *jobs.Kind[GroundJob]
+	// backfillJob enqueues KindBackfillPhotos jobs.
+	backfillJob *jobs.Kind[BackfillJob]
+	// wake is called after every committed change to a dinner's method or
+	// minutes, which can move its crock-pot start reminder.
+	wake func()
 
 	// groundingsMu guards groundings: the KindGroundDinner jobs running,
 	// by dinner id, so archiving or renaming a dinner can stop them.
@@ -157,10 +167,11 @@ type Service struct {
 	offerSearches map[string]map[*offerSearch]struct{}
 }
 
-// NewService returns a service over st that grounds dinners with grounder
-// and registers the KindGroundDinner job on runner, which must not have
-// started yet.
-func NewService(st *store.Store, grounder *recipes.Grounder, runner *jobs.Runner, logger *slog.Logger) (*Service, error) {
+// NewService returns a service over st that grounds dinners with grounder,
+// calls wake (the scheduler's Wake) after every committed change to a
+// dinner's method or minutes, and registers the KindGroundDinner and
+// KindBackfillPhotos jobs on runner, which must not have started yet.
+func NewService(st *store.Store, grounder *recipes.Grounder, runner *jobs.Runner, wake func(), logger *slog.Logger) (*Service, error) {
 	switch {
 	case st == nil:
 		return nil, errors.New("dinners: nil store")
@@ -168,16 +179,26 @@ func NewService(st *store.Store, grounder *recipes.Grounder, runner *jobs.Runner
 		return nil, errors.New("dinners: nil grounder")
 	case runner == nil:
 		return nil, errors.New("dinners: nil job runner")
+	case wake == nil:
+		return nil, errors.New("dinners: nil wake")
 	case logger == nil:
 		return nil, errors.New("dinners: nil logger")
 	}
-	s := &Service{st: st, grounder: grounder, logger: logger, groundings: make(map[string]map[*runningGrounding]struct{}), offerKey: make([]byte, 32), offers: make(map[string]*offerSet), offerSearches: make(map[string]map[*offerSearch]struct{})}
+	s := &Service{st: st, grounder: grounder, wake: wake, logger: logger, groundings: make(map[string]map[*runningGrounding]struct{}), offerKey: make([]byte, 32), offers: make(map[string]*offerSet), offerSearches: make(map[string]map[*offerSearch]struct{})}
 	rand.Read(s.offerKey) // never fails: it crashes the program instead
 	kind, err := jobs.Register(runner, KindGroundDinner, s.runGroundJob, Reasons...)
 	if err != nil {
 		return nil, err
 	}
 	s.groundJob = kind
+	backfill, err := jobs.Register(runner, KindBackfillPhotos, s.runBackfillJob)
+	if err != nil {
+		return nil, err
+	}
+	if err := backfill.ServiceOnly(); err != nil {
+		return nil, err
+	}
+	s.backfillJob = backfill
 	return s, nil
 }
 
@@ -502,6 +523,9 @@ func (s *Service) Update(ctx context.Context, id string, p Patch, updatedBy stri
 	if err != nil {
 		return Dinner{}, err
 	}
+	if p.Method != nil || p.MinutesTotal != nil {
+		s.wake()
+	}
 	if renamed {
 		updateCommitted()
 		s.clearOffers(row.ID, row.GroundingRevision)
@@ -693,6 +717,8 @@ func fromRow(r db.Dinner) Dinner {
 		UpdatedBy:       nullString(r.UpdatedBy),
 		CreatedAt:       r.CreatedAt,
 		UpdatedAt:       r.UpdatedAt,
+
+		PhotoBackfillEligible: PhotoBackfillEligible(r),
 	}
 	if r.MinutesTotal.Valid {
 		d.MinutesTotal = &r.MinutesTotal.Int64

internal/dinners/dinners_test.go

@@ -99,16 +99,19 @@ func TestPageSiteNameWithholdsHosts(t *testing.T) {
 		{"Bon Appétit", true, ptr("Bon Appétit")},
 		{"Mr. Food Test Kitchen", true, ptr("Mr. Food Test Kitchen")},
 	} {
-		got, err := dinners.PageSiteName(sql.NullString{String: tc.stored, Valid: tc.valid}, link)
+		src, err := dinners.SourceOf(sql.NullString{String: tc.stored, Valid: tc.valid}, link)
 		if err != nil {
-			t.Fatalf("PageSiteName(%q): %v", tc.stored, err)
+			t.Fatalf("SourceOf(%q): %v", tc.stored, err)
 		}
-		if (got == nil) != (tc.want == nil) || (got != nil && *got != *tc.want) {
-			t.Errorf("PageSiteName(%q) = %v, want %v", tc.stored, deref(got), deref(tc.want))
+		if got := src.SiteName; (got == nil) != (tc.want == nil) || (got != nil && *got != *tc.want) {
+			t.Errorf("SourceOf(%q) site name = %v, want %v", tc.stored, deref(got), deref(tc.want))
 		}
 	}
-	if _, err := dinners.PageSiteName(sql.NullString{String: "Delish", Valid: true}, "https://secret-token\x7f.example/%zz"); err == nil || strings.Contains(err.Error(), "secret-token") {
-		t.Errorf("PageSiteName of an unparseable link: err = %v, want one not quoting the link", err)
+	// A link that does not parse is an error with or without a site name.
+	for _, site := range []sql.NullString{{String: "Delish", Valid: true}, {}} {
+		if _, err := dinners.SourceOf(site, "https://secret-token\x7f.example/%zz"); err == nil || strings.Contains(err.Error(), "secret-token") {
+			t.Errorf("SourceOf(%v) of an unparseable link: err = %v, want one not quoting the link", site, err)
+		}
 	}
 }
 

internal/dinners/export_test.go

@@ -72,8 +72,20 @@ func (s *Service) RunGroundJob(ctx context.Context, p GroundJob) (string, error)
 	return r.GroundingStatus, err
 }
 
-// PageSiteName is pageSiteName.
-var PageSiteName = pageSiteName
-
 // SafeSourceURL is safeSourceURL.
 var SafeSourceURL = safeSourceURL
+
+// RunBackfillJob runs the KindBackfillPhotos handler for p in the caller's
+// goroutine, as the job runner would, and returns its outcomes: on an
+// error, those it last published.
+func (s *Service) RunBackfillJob(ctx context.Context, p BackfillJob) ([]BackfillOutcome, error) {
+	var published backfillResult
+	r, err := s.runBackfillJob(ctx, p, func(partial backfillResult) error {
+		published = partial
+		return nil
+	})
+	if err != nil {
+		return published.Dinners, err
+	}
+	return r.Dinners, nil
+}

internal/dinners/grounding.go

@@ -196,6 +196,7 @@ func (s *Service) runGroundJob(ctx context.Context, p GroundJob, _ func(groundRe
 	if n == 0 {
 		return s.currentGrounding(ctx, row.ID)
 	}
+	s.wake()
 	return groundResult{DinnerID: row.ID, GroundingStatus: GroundingGrounded}, nil
 }
 
@@ -577,6 +578,7 @@ func (s *Service) Ground(ctx context.Context, id string, f Fix, updatedBy string
 	if err != nil {
 		return Dinner{}, fmt.Errorf("%w: dinner %s: record: %w", ErrGroundFailed, id, err)
 	}
+	s.wake()
 	s.clearOffers(cur.ID, math.MaxInt64)
 	return fromRow(row), nil
 }
@@ -700,6 +702,7 @@ func (s *Service) groundManual(ctx context.Context, id string, m ManualRecipe, u
 	if err != nil {
 		return Dinner{}, fmt.Errorf("%w: dinner %s: %w", ErrGroundFailed, id, err)
 	}
+	s.wake()
 	s.clearOffers(row.ID, math.MaxInt64)
 	return fromRow(row), nil
 }

internal/dinners/grounding_test.go

@@ -39,6 +39,7 @@ type env struct {
 	runner *jobs.Runner
 	search *recipestest.Search
 	pages  *recipestest.Pages
+	images *recipestest.Images
 	model  *llm.Fake
 }
 
@@ -104,11 +105,11 @@ func newUnstartedEnvOn(t *testing.T, st *store.Store, dataDir string) *env {
 	if err != nil {
 		t.Fatal(err)
 	}
-	svc, err := dinners.NewService(st, g, runner, logger)
+	svc, err := dinners.NewService(st, g, runner, func() {}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
-	return &env{svc: svc, st: st, runner: runner, search: search, pages: pages, model: model}
+	return &env{svc: svc, st: st, runner: runner, search: search, pages: pages, images: images, model: model}
 }
 
 // start starts the env's job runner, stopping it when the test ends.

internal/home/export_test.go

@@ -0,0 +1,6 @@
+package home
+
+import "time"
+
+// SetClock makes now the clock s reads "now" and "tonight" on.
+func SetClock(s *Service, now func() time.Time) { s.now = now }

internal/home/home.go

@@ -0,0 +1,253 @@
+// Package home reads the Home screen: tonight's dinner, the Side quests to
+// swipe, the Supply run and whether there are recent updates. It owns no
+// data: every value is read through the service that owns it, and "now"
+// and "tonight" are in the household's zone, never UTC.
+package home
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/plan"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/shopping"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
+)
+
+// Service reads the Home screen.
+type Service struct {
+	settings *household.SettingsService
+	plans    *plan.Service
+	suggest  *suggest.Service
+	shopping *shopping.Service
+	notifier *notify.Service
+	// now is the clock "now" and "tonight" are read on; tests replace it.
+	now func() time.Time
+}
+
+// NewService returns a service reading through the given services.
+func NewService(settings *household.SettingsService, plans *plan.Service, suggestSvc *suggest.Service, shop *shopping.Service, notifier *notify.Service) (*Service, error) {
+	switch {
+	case settings == nil:
+		return nil, errors.New("home: nil household settings service")
+	case plans == nil:
+		return nil, errors.New("home: nil plan service")
+	case suggestSvc == nil:
+		return nil, errors.New("home: nil suggestions service")
+	case shop == nil:
+		return nil, errors.New("home: nil shopping service")
+	case notifier == nil:
+		return nil, errors.New("home: nil notifier")
+	}
+	return &Service{settings: settings, plans: plans, suggest: suggestSvc, shopping: shop, notifier: notifier, now: time.Now}, nil
+}
+
+// Home is the Home screen as the API shows it.
+type Home struct {
+	// DateLabel is today in the household's zone, e.g. "Friday, Oct 2".
+	DateLabel string `json:"dateLabel"`
+	// Timezone is the household's IANA zone, whose next local midnight
+	// is when Home is read again for the new day.
+	Timezone string `json:"timezone"`
+	// Tonight is the dinner planned for today on the current week's plan;
+	// nil when the week has no plan.
+	Tonight *Dinner `json:"tonight"`
+	// SideQuestCount is how many Side quests are pending on the deck.
+	SideQuestCount int `json:"sideQuestCount"`
+	// ShoppingList is the Supply run of the upcoming week when it has one,
+	// else of the current week.
+	ShoppingList  ShoppingStatus `json:"shoppingList"`
+	RecentUpdates RecentUpdates  `json:"recentUpdates"`
+}
+
+// Dinner is tonight's dinner.
+type Dinner struct {
+	ID    string  `json:"id"`
+	Name  string  `json:"name"`
+	Photo *string `json:"photo"`
+	// Origin is regular or side_quest.
+	Origin       string `json:"origin"`
+	MinutesTotal *int64 `json:"minutes_total"`
+}
+
+// ShoppingStatus is whether a week's Supply run is ready.
+type ShoppingStatus struct {
+	// WeekStart is the Monday of the week, YYYY-MM-DD.
+	WeekStart string `json:"weekStart"`
+	// Label is the week label, e.g. "Week 41 · Oct 5 – 11".
+	Label string `json:"label"`
+	// Ready is true when the week has a Supply run.
+	Ready bool `json:"ready"`
+	// SentToChatAt is when the Supply run was sent to Google Chat; nil
+	// until it is, and when there is no Supply run.
+	SentToChatAt *string `json:"sentToChatAt"`
+}
+
+// RecentUpdates says whether there is something new for the bell.
+type RecentUpdates struct {
+	// Unread is true when a notification was stored after the household
+	// last saw its updates (household_settings.updates_seen_at), or at all
+	// when it never has.
+	Unread bool `json:"unread"`
+}
+
+// Get reads the Home screen at the service's "now". It only reads: it
+// writes nothing, not even the batch bookkeeping a Deck read does.
+func (s *Service) Get(ctx context.Context) (Home, error) {
+	settings, err := s.settings.Get(ctx)
+	if err != nil {
+		return Home{}, fmt.Errorf("home: read household settings: %w", err)
+	}
+	zone, err := household.LoadZone(settings.Timezone)
+	if err != nil {
+		return Home{}, fmt.Errorf("home: household settings: %w", err)
+	}
+	now := s.now().In(zone)
+	today := household.Today(now, zone)
+	thisWeek := household.WeekStart(today)
+
+	tonight, err := s.tonight(ctx, thisWeek, today)
+	if err != nil {
+		return Home{}, err
+	}
+	sideQuests, err := s.suggest.PendingCount(ctx)
+	if err != nil {
+		return Home{}, fmt.Errorf("home: read deck: %w", err)
+	}
+	list, err := s.shoppingStatus(ctx, thisWeek)
+	if err != nil {
+		return Home{}, err
+	}
+	unread, err := s.unread(ctx, settings.UpdatesSeenAt)
+	if err != nil {
+		return Home{}, err
+	}
+	return Home{
+		DateLabel:      now.Format("Monday, Jan 2"),
+		Timezone:       settings.Timezone,
+		Tonight:        tonight,
+		SideQuestCount: sideQuests,
+		ShoppingList:   list,
+		RecentUpdates:  RecentUpdates{Unread: unread},
+	}, nil
+}
+
+// tonight returns the dinner planned on today in the plan of the week
+// starting thisWeek, or nil when the week has no plan.
+func (s *Service) tonight(ctx context.Context, thisWeek, today store.LocalDate) (*Dinner, error) {
+	p, err := s.plans.Get(ctx, thisWeek)
+	if errors.Is(err, plan.ErrNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("home: read plan: %w", err)
+	}
+	for _, d := range p.Days {
+		if d.Date == today.String() {
+			return &Dinner{
+				ID: d.Dinner.ID, Name: d.Dinner.Name, Photo: d.Dinner.Photo,
+				Origin: d.Dinner.Origin, MinutesTotal: d.Dinner.Minutes,
+			}, nil
+		}
+	}
+	return nil, fmt.Errorf("home: plan of week %s has no day %s", thisWeek, today)
+}
+
+// shoppingStatus returns the status of the upcoming week's Supply run when
+// it has one, else of the current week's, ready or not.
+func (s *Service) shoppingStatus(ctx context.Context, thisWeek store.LocalDate) (ShoppingStatus, error) {
+	y, m, d := thisWeek.Date()
+	nextWeek := store.LocalDateOf(time.Date(y, m, d+7, 0, 0, 0, 0, time.UTC))
+	for _, week := range []store.LocalDate{nextWeek, thisWeek} {
+		l, err := s.shopping.Get(ctx, week)
+		if errors.Is(err, shopping.ErrListNotFound) {
+			continue
+		}
+		if err != nil {
+			return ShoppingStatus{}, fmt.Errorf("home: read Supply run: %w", err)
+		}
+		return weekStatus(week, true, l.SentToChatAt)
+	}
+	return weekStatus(thisWeek, false, nil)
+}
+
+func weekStatus(week store.LocalDate, ready bool, sentToChatAt *string) (ShoppingStatus, error) {
+	label, err := household.WeekLabel(week)
+	if err != nil {
+		return ShoppingStatus{}, fmt.Errorf("home: %w", err)
+	}
+	return ShoppingStatus{WeekStart: week.String(), Label: label, Ready: ready, SentToChatAt: sentToChatAt}, nil
+}
+
+// unread reports whether a notification was stored after seenAt, the
+// stored updates_seen_at, or at all when it is nil.
+func (s *Service) unread(ctx context.Context, seenAt *string) (bool, error) {
+	var since *time.Time
+	if seenAt != nil {
+		var ts store.Timestamp
+		if err := ts.Scan(*seenAt); err != nil {
+			return false, fmt.Errorf("home: household settings updates_seen_at: %w", err)
+		}
+		since = &ts.Time
+	}
+	unread, err := s.notifier.StoredSince(ctx, since)
+	if err != nil {
+		return false, fmt.Errorf("home: %w", err)
+	}
+	return unread, nil
+}
+
+// RecentLimit is how many events the Recent updates sheet lists.
+const RecentLimit = 10
+
+// Update is one event in the Recent updates sheet.
+type Update struct {
+	// Type is the event type, e.g. plan_ready.
+	Type  string `json:"type"`
+	Title string `json:"title"`
+	Body  string `json:"body"`
+	// URL is the path-absolute, same-origin path a tap on the update opens.
+	URL string `json:"url"`
+	// CreatedAt is when the event was stored, UTC RFC 3339 with
+	// milliseconds; it is what POST /updates/seen takes back.
+	CreatedAt string `json:"created_at"`
+}
+
+// Updates returns the last RecentLimit distinct notification events, newest
+// first, whatever channels they went to.
+func (s *Service) Updates(ctx context.Context) ([]Update, error) {
+	events, err := s.notifier.Recent(ctx, RecentLimit)
+	if err != nil {
+		return nil, fmt.Errorf("home: %w", err)
+	}
+	out := make([]Update, len(events))
+	for i, ev := range events {
+		out[i] = Update{
+			Type: string(ev.Type), Title: ev.Title, Body: ev.Body, URL: ev.URL,
+			CreatedAt: store.Timestamp{Time: ev.CreatedAt}.String(),
+		}
+	}
+	return out, nil
+}
+
+// ErrSeenInFuture is returned by MarkUpdatesSeen for a time after now.
+var ErrSeenInFuture = errors.New("home: updates cannot be seen through a time after now")
+
+// MarkUpdatesSeen records that the household has seen its updates through
+// through, the created_at of the newest update it was shown, so
+// recentUpdates.unread is false until an event is stored after it. A time
+// before the one already recorded changes nothing; one after now is
+// ErrSeenInFuture, since it would hide events not yet stored.
+func (s *Service) MarkUpdatesSeen(ctx context.Context, through time.Time) error {
+	if through.After(s.now()) {
+		return ErrSeenInFuture
+	}
+	if err := s.settings.MarkUpdatesSeen(ctx, through); err != nil {
+		return fmt.Errorf("home: %w", err)
+	}
+	return nil
+}

internal/home/home_test.go

@@ -0,0 +1,598 @@
+package home_test
+
+import (
+	"context"
+	"database/sql"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/chat"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/gcal"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/gcal/gcaltest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/home"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify/notifytest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/plan"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/shopping"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+// zone is the household's zone in these tests: not UTC, so a late local
+// evening is already the next day in UTC.
+const zone = "America/Chicago"
+
+// weekDates is the week of 2026-10-12, Monday first.
+var weekDates = []string{"2026-10-12", "2026-10-13", "2026-10-14", "2026-10-15", "2026-10-16", "2026-10-17", "2026-10-18"}
+
+type env struct {
+	svc      *home.Service
+	st       *store.Store
+	settings *household.SettingsService
+	notifier *notify.Service
+	loc      *time.Location
+}
+
+// newEnv returns a home service over a migrated temp database whose
+// household is in zone, reading "now" from a clock set to at.
+func newEnv(t *testing.T) *env {
+	t.Helper()
+	ctx := t.Context()
+	st, err := store.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	if err := household.SeedSettings(ctx, st, zone); err != nil {
+		t.Fatal(err)
+	}
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	notifier := notifytest.New(t, st)
+	pub := &url.URL{Scheme: "https", Host: "mealquest.example"}
+
+	box, err := secretbox.New(base64.StdEncoding.EncodeToString(make([]byte, secretbox.KeySize)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	google := gcaltest.New(t, "https://mealquest.example"+gcal.CallbackPath)
+	googleSvc, err := gcal.NewService(st, box, gcal.Config{
+		ClientID: gcaltest.ClientID, ClientSecret: gcaltest.ClientSecret, PublicURL: pub,
+		SecretKey: []byte("server-secret-key"), Endpoint: google.Endpoint(), RevokeURL: google.RevokeURL(),
+		CalendarAPI: google.CalendarAPI(),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	draft := func(context.Context, string, skills.WeekRequest) (skills.Week, error) {
+		return skills.Week{}, errors.New("no model in this test")
+	}
+	plans, err := plan.NewService(st, draft, runner, googleSvc, notifier, func() {}, pub, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	sideQuests := func(context.Context, string, skills.SideQuestsRequest) (skills.SideQuests, error) {
+		return skills.SideQuests{}, errors.New("no model in this test")
+	}
+	suggestSvc, err := suggest.NewService(st, g, sideQuests, runner, notifier, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	chatSvc, err := chat.NewService(st, box, pub, http.DefaultTransport)
+	if err != nil {
+		t.Fatal(err)
+	}
+	title := func(context.Context, string, skills.ArchiveTitleRequest) (skills.ArchiveTitle, error) {
+		return skills.ArchiveTitle{}, errors.New("no model in this test")
+	}
+	shop, err := shopping.NewService(st, title, runner, notifier, chatSvc, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	settings := household.NewSettingsService(st)
+	svc, err := home.NewService(settings, plans, suggestSvc, shop, notifier)
+	if err != nil {
+		t.Fatal(err)
+	}
+	loc, err := time.LoadLocation(zone)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &env{svc: svc, st: st, settings: settings, notifier: notifier, loc: loc}
+}
+
+// at reads the Home screen with the clock at the household-local wall
+// time "YYYY-MM-DD HH:MM".
+func (e *env) at(t *testing.T, local string) home.Home {
+	t.Helper()
+	now, err := time.ParseInLocation("2006-01-02 15:04", local, e.loc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	home.SetClock(e.svc, func() time.Time { return now })
+	h, err := e.svc.Get(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return h
+}
+
+// dinner stores a dinner and returns its id.
+func (e *env) dinner(t *testing.T, name, status, origin string, minutes int64) string {
+	t.Helper()
+	now := store.Now().String()
+	d, err := db.New(e.st.Writer).CreateDinner(t.Context(), db.CreateDinnerParams{
+		ID: store.NewID(), Name: name, NormalizedName: harness.Normalize(name), Status: status, Origin: origin,
+		MinutesTotal:    sql.NullInt64{Int64: minutes, Valid: minutes > 0},
+		GroundingStatus: "manual", CreatedAt: now, UpdatedAt: now,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return d.ID
+}
+
+// planWeek stores the plan of the week of 2026-10-12: the dinner named for
+// its date each day, a Regular of 30 minutes, but Wednesday a Side quest of
+// unknown minutes. It returns the plan's id.
+func (e *env) planWeek(t *testing.T) string {
+	t.Helper()
+	ctx := t.Context()
+	q := db.New(e.st.Writer)
+	now := store.Now().String()
+	planID := store.NewID()
+	if err := q.CreateWeekPlan(ctx, db.CreateWeekPlanParams{ID: planID, WeekStart: weekDates[0], CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	for _, date := range weekDates {
+		id := e.dinner(t, "Dinner "+date, "regular", "regular", 30)
+		if date == "2026-10-14" {
+			id = e.dinner(t, "Dinner "+date, "quest_log", "side_quest", 0)
+		}
+		if err := q.PutPlanDay(ctx, db.PutPlanDayParams{ID: store.NewID(), PlanID: planID, Date: date,
+			DinnerID: sql.NullString{String: id, Valid: true}, CreatedAt: now, UpdatedAt: now}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return planID
+}
+
+// Tonight's dinner and the date label follow the household's local
+// midnight, not UTC's: late on Tuesday evening in Chicago it is already
+// Wednesday in UTC, and Home still shows Tuesday's dinner.
+func TestTonightSwitchesAtLocalMidnight(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	e.planWeek(t)
+
+	for _, tc := range []struct {
+		local, label, dinner string
+	}{
+		// 23:59 CDT is 04:59 UTC the next day.
+		{"2026-10-13 23:59", "Tuesday, Oct 13", "Dinner 2026-10-13"},
+		{"2026-10-14 00:00", "Wednesday, Oct 14", "Dinner 2026-10-14"},
+		// 19:00 CDT on Sunday is Monday 00:00 UTC, a week with no plan.
+		{"2026-10-18 19:00", "Sunday, Oct 18", "Dinner 2026-10-18"},
+	} {
+		h := e.at(t, tc.local)
+		if h.DateLabel != tc.label {
+			t.Errorf("at %s: dateLabel = %q, want %q", tc.local, h.DateLabel, tc.label)
+		}
+		if h.Tonight == nil || h.Tonight.Name != tc.dinner {
+			t.Errorf("at %s: tonight = %+v, want %s", tc.local, h.Tonight, tc.dinner)
+		}
+	}
+
+	// Late Sunday evening of the week before, the plan's week has not
+	// begun locally, though in UTC it has.
+	if h := e.at(t, "2026-10-11 23:30"); h.Tonight != nil || h.DateLabel != "Sunday, Oct 11" {
+		t.Errorf("at 2026-10-11 23:30: tonight = %+v, dateLabel = %q, want no dinner on Sunday, Oct 11", h.Tonight, h.DateLabel)
+	}
+}
+
+// Tonight carries the dinner's id, name, photo, origin and minutes.
+func TestTonightDinner(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	e.planWeek(t)
+
+	h := e.at(t, "2026-10-13 18:00")
+	if h.Tonight == nil || h.Tonight.ID == "" || h.Tonight.Origin != "regular" || h.Tonight.Photo != nil ||
+		h.Tonight.MinutesTotal == nil || *h.Tonight.MinutesTotal != 30 {
+		t.Errorf("tonight = %+v, want Tuesday's 30-minute Regular with no photo", h.Tonight)
+	}
+	h = e.at(t, "2026-10-14 18:00")
+	if h.Tonight == nil || h.Tonight.Origin != "side_quest" || h.Tonight.MinutesTotal != nil {
+		t.Errorf("tonight = %+v, want Wednesday's Side quest of unknown minutes", h.Tonight)
+	}
+}
+
+// With no plan, no suggestions, no Supply run and no notifications, Home
+// says so: no dinner tonight, nothing to swipe, the current week's Supply
+// run not ready and nothing unread.
+func TestHomeEmpty(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+
+	h := e.at(t, "2026-10-13 23:59")
+	want := home.Home{
+		DateLabel: "Tuesday, Oct 13",
+		Timezone:  zone,
+		ShoppingList: home.ShoppingStatus{
+			WeekStart: "2026-10-12", Label: "Week 42 · Oct 12 – 18",
+		},
+	}
+	if h != want {
+		t.Errorf("home = %+v, want %+v", h, want)
+	}
+}
+
+// The Side quest count is the pending cards of the deck: a decided
+// suggestion is not counted.
+func TestSideQuestCount(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+	q := db.New(e.st.Writer)
+	now := store.Now().String()
+	batch, err := q.CreateSuggestionBatch(ctx, db.CreateSuggestionBatchParams{ID: store.NewID(), Trigger: "manual", CreatedAt: now, UpdatedAt: now})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := q.FinishSuggestionBatch(ctx, db.FinishSuggestionBatchParams{Status: "done", UpdatedAt: now, ID: batch.ID}); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{"Pho", "Ramen", "Tagine"} {
+		id := e.dinner(t, name, "suggested", "side_quest", 0)
+		if err := q.CreateSuggestion(ctx, db.CreateSuggestionParams{
+			ID: store.NewID(), DinnerID: id, BatchID: batch.ID, Name: name, Reason: "Because", CitedRegularIds: "[]",
+			CreatedAt: now, UpdatedAt: now,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if h := e.at(t, "2026-10-13 12:00"); h.SideQuestCount != 3 {
+		t.Errorf("sideQuestCount = %d, want 3", h.SideQuestCount)
+	}
+	if _, err := e.st.Writer.ExecContext(ctx, `UPDATE suggestions SET status = 'declined', decided_at = ? WHERE name = 'Pho'`, now); err != nil {
+		t.Fatal(err)
+	}
+	if h := e.at(t, "2026-10-13 12:00"); h.SideQuestCount != 2 {
+		t.Errorf("sideQuestCount after a Pass = %d, want 2", h.SideQuestCount)
+	}
+}
+
+// Reading Home writes nothing: a batch still pending whose job is gone,
+// which a Deck read would fail, is left as it was, and the read succeeds.
+func TestGetDoesNotWriteBatches(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+	created := "2026-10-13T12:00:00.000Z"
+	batch, err := db.New(e.st.Writer).CreateSuggestionBatch(ctx, db.CreateSuggestionBatchParams{ID: store.NewID(), Trigger: "manual", CreatedAt: created, UpdatedAt: created})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if batch.Status != "pending" {
+		t.Fatalf("new batch status = %q, want pending", batch.Status)
+	}
+	if h := e.at(t, "2026-10-13 12:00"); h.SideQuestCount != 0 {
+		t.Errorf("sideQuestCount = %d, want 0", h.SideQuestCount)
+	}
+	var status, updatedAt string
+	if err := e.st.Reader.QueryRowContext(ctx, `SELECT status, updated_at FROM suggestion_batches WHERE id = ?`, batch.ID).Scan(&status, &updatedAt); err != nil {
+		t.Fatal(err)
+	}
+	if status != "pending" || updatedAt != created {
+		t.Errorf("batch after a Home read = %s at %s, want pending at %s", status, updatedAt, created)
+	}
+}
+
+// The Supply run shown is the upcoming week's when it has one, else the
+// current week's; the weeks are the household's local weeks.
+func TestShoppingStatus(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+	planID := e.planWeek(t)
+	list := func(weekStart string, sent sql.NullString) {
+		t.Helper()
+		now := store.Now().String()
+		if _, err := e.st.Writer.ExecContext(ctx,
+			`INSERT INTO shopping_lists (id, week_start, plan_id, status, sent_to_chat_at, created_at, updated_at) VALUES (?, ?, ?, 'current', ?, ?, ?)`,
+			store.NewID(), weekStart, planID, sent, now, now); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	list("2026-10-12", sql.NullString{})
+	want := home.ShoppingStatus{WeekStart: "2026-10-12", Label: "Week 42 · Oct 12 – 18", Ready: true}
+	if h := e.at(t, "2026-10-16 09:00"); h.ShoppingList != want {
+		t.Errorf("shoppingList = %+v, want %+v", h.ShoppingList, want)
+	}
+
+	sent := "2026-10-17T13:00:00.000Z"
+	list("2026-10-19", sql.NullString{String: sent, Valid: true})
+	h := e.at(t, "2026-10-16 09:00")
+	if s := h.ShoppingList; s.WeekStart != "2026-10-19" || s.Label != "Week 43 · Oct 19 – 25" || !s.Ready || s.SentToChatAt == nil || *s.SentToChatAt != sent {
+		t.Errorf("shoppingList = %+v, want the upcoming week's, sent at %s", s, sent)
+	}
+
+	// Late Sunday evening locally is Monday in UTC: the current week is
+	// still the week of 2026-10-12, so its upcoming week's list shows.
+	if s := e.at(t, "2026-10-18 23:30").ShoppingList; s.WeekStart != "2026-10-19" {
+		t.Errorf("late Sunday: shoppingList week = %s, want 2026-10-19", s.WeekStart)
+	}
+	// On Monday the week of 2026-10-19 is current and has no upcoming
+	// list.
+	if s := e.at(t, "2026-10-19 08:00").ShoppingList; s.WeekStart != "2026-10-19" || !s.Ready {
+		t.Errorf("Monday: shoppingList = %+v, want the current week's", s)
+	}
+	// A week later neither the current nor the upcoming week has a list.
+	want = home.ShoppingStatus{WeekStart: "2026-10-26", Label: "Week 44 · Oct 26 – Nov 1"}
+	if s := e.at(t, "2026-10-26 08:00").ShoppingList; s != want {
+		t.Errorf("no list: shoppingList = %+v, want %+v", s, want)
+	}
+}
+
+// Recent updates are unread when a notification was stored after the
+// household last saw its updates, or ever when it never has.
+func TestRecentUpdatesUnread(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+
+	if h := e.at(t, "2026-10-13 12:00"); h.RecentUpdates.Unread {
+		t.Error("unread with no notifications")
+	}
+	if err := e.notifier.Emit(ctx, notify.Event{Type: notify.NewSuggestions, Key: "new_suggestions:1", Title: "New Side quests", URL: "/discover"}); err != nil {
+		t.Fatal(err)
+	}
+	if h := e.at(t, "2026-10-13 12:00"); !h.RecentUpdates.Unread {
+		t.Error("not unread with a notification never seen")
+	}
+	seen := func(at time.Time) {
+		t.Helper()
+		if _, err := e.st.Writer.ExecContext(ctx, `UPDATE household_settings SET updates_seen_at = ?`, store.Timestamp{Time: at.UTC().Truncate(time.Millisecond)}.String()); err != nil {
+			t.Fatal(err)
+		}
+	}
+	seen(time.Now().Add(time.Hour))
+	if h := e.at(t, "2026-10-13 12:00"); h.RecentUpdates.Unread {
+		t.Error("unread with every notification seen")
+	}
+	seen(time.Now().Add(-time.Hour))
+	if h := e.at(t, "2026-10-13 12:00"); !h.RecentUpdates.Unread {
+		t.Error("not unread with a notification stored after updates were seen")
+	}
+}
+
+func TestNewServiceRequiresServices(t *testing.T) {
+	t.Parallel()
+	if _, err := home.NewService(nil, nil, nil, nil, nil); err == nil {
+		t.Fatal("NewService accepted nil services")
+	}
+}
+
+// store stores event key of type typ in the outbox at instant at, for each
+// of channels, as notify stores an event.
+func (e *env) store(t *testing.T, typ notify.EventType, key string, at time.Time, channels ...notify.Channel) {
+	t.Helper()
+	payload, err := json.Marshal(notify.Payload{Event: typ, Title: "Title " + key, Body: "Body " + key, URL: "/u/" + key, Tag: key})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ts := store.Timestamp{Time: at.UTC().Truncate(time.Millisecond)}.String()
+	for _, ch := range channels {
+		if _, err := db.New(e.st.Writer).InsertNotification(t.Context(), db.InsertNotificationParams{
+			ID: store.NewID(), EventKey: key, Channel: string(ch), Payload: string(payload),
+			NextAttemptAt: sql.NullString{String: ts, Valid: true}, Now: ts,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// Updates are the last ten distinct events, newest first: an event stored
+// for push and Google Chat is listed once, whatever became of its delivery.
+func TestUpdates(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+
+	got, err := e.svc.Updates(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got == nil || len(got) != 0 {
+		t.Errorf("updates with no notifications = %#v, want an empty list", got)
+	}
+
+	base := time.Date(2026, 10, 13, 12, 0, 0, 0, time.UTC)
+	for i := range 12 {
+		key := fmt.Sprintf("plan_ready:%02d", i)
+		e.store(t, notify.PlanReady, key, base.Add(time.Duration(i)*time.Minute), notify.ChannelPush, notify.ChannelChat)
+	}
+	// A delivered and a failed row of one event are still one event.
+	if _, err := e.st.Writer.ExecContext(ctx, `UPDATE notification_outbox SET status = 'sent' WHERE event_key = 'plan_ready:11' AND channel = 'push'`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := e.st.Writer.ExecContext(ctx, `UPDATE notification_outbox SET status = 'failed' WHERE event_key = 'plan_ready:11' AND channel = 'chat'`); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err = e.svc.Updates(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != home.RecentLimit {
+		t.Fatalf("updates = %d, want %d: %+v", len(got), home.RecentLimit, got)
+	}
+	for i, u := range got {
+		n := 11 - i
+		key := fmt.Sprintf("plan_ready:%02d", n)
+		want := home.Update{
+			Type: "plan_ready", Title: "Title " + key, Body: "Body " + key, URL: "/u/" + key,
+			CreatedAt: store.Timestamp{Time: base.Add(time.Duration(n) * time.Minute)}.String(),
+		}
+		if u != want {
+			t.Errorf("updates[%d] = %+v, want %+v", i, u, want)
+		}
+	}
+}
+
+// An event emitted to push and Google Chat is one update.
+func TestUpdatesEmittedToTwoChannels(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+	if err := e.notifier.Emit(ctx, notify.Event{Type: notify.PlanReady, Key: "plan_ready:2026-10-12", Title: "Your week is drafted", Body: "Take a look", URL: "/plan"}); err != nil {
+		t.Fatal(err)
+	}
+	var rows int
+	if err := e.st.Reader.QueryRowContext(ctx, `SELECT COUNT(*) FROM notification_outbox`).Scan(&rows); err != nil {
+		t.Fatal(err)
+	}
+	if rows != 2 {
+		t.Fatalf("outbox rows = %d, want push and chat", rows)
+	}
+	got, err := e.svc.Updates(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || got[0].Type != "plan_ready" || got[0].Title != "Your week is drafted" || got[0].Body != "Take a look" || got[0].URL != "/plan" {
+		t.Errorf("updates = %+v, want the one plan_ready event", got)
+	}
+}
+
+// Marking updates seen through the newest clears unread until a newer event
+// is stored; marking them seen through an older time does not move the
+// mark back, and a time after now is refused.
+func TestMarkUpdatesSeen(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+	unread := func() bool {
+		t.Helper()
+		return e.at(t, "2026-10-13 12:00").RecentUpdates.Unread
+	}
+	first := time.Date(2026, 10, 13, 16, 0, 0, 0, time.UTC)
+	e.store(t, notify.NewSuggestions, "new_suggestions:1", first, notify.ChannelPush)
+	if !unread() {
+		t.Fatal("not unread with an event never seen")
+	}
+	// The settings were last edited well before: marking updates seen must
+	// keep that time and tell no settings subscriber.
+	edited := (store.Timestamp{Time: time.Date(2026, 10, 1, 9, 0, 0, 0, time.UTC)}).String()
+	if _, err := e.st.Writer.ExecContext(ctx, `UPDATE household_settings SET updated_at = ?`, edited); err != nil {
+		t.Fatal(err)
+	}
+	var notified int
+	unsubscribe := e.settings.Subscribe(func(household.Settings) { notified++ })
+	defer unsubscribe()
+	if err := e.svc.MarkUpdatesSeen(ctx, first); err != nil {
+		t.Fatal(err)
+	}
+	if unread() {
+		t.Error("unread after marking the newest event seen")
+	}
+
+	second := first.Add(time.Millisecond)
+	e.store(t, notify.PlanReady, "plan_ready:2", second, notify.ChannelPush, notify.ChannelChat)
+	if !unread() {
+		t.Error("not unread with an event stored after the mark")
+	}
+	// Seen again through the older event, as a sheet opened before the
+	// newer one arrived would: nothing moves, so it stays unread.
+	if err := e.svc.MarkUpdatesSeen(ctx, first); err != nil {
+		t.Fatal(err)
+	}
+	if !unread() {
+		t.Error("an older mark hid the newer event")
+	}
+	if err := e.svc.MarkUpdatesSeen(ctx, second); err != nil {
+		t.Fatal(err)
+	}
+	if unread() {
+		t.Error("unread after marking the newer event seen")
+	}
+	if err := e.svc.MarkUpdatesSeen(ctx, first); err != nil {
+		t.Fatal(err)
+	}
+	settings, err := e.settings.Get(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := (store.Timestamp{Time: second}).String(); settings.UpdatesSeenAt == nil || *settings.UpdatesSeenAt != want {
+		t.Errorf("updates_seen_at = %v, want %s: an older mark moved it back", settings.UpdatesSeenAt, want)
+	}
+	if settings.UpdatedBy != nil {
+		t.Errorf("updated_by = %q, want unset: marking updates seen is not a settings edit", *settings.UpdatedBy)
+	}
+	if settings.UpdatedAt != edited {
+		t.Errorf("updated_at = %s, want %s: marking updates seen is not a settings edit", settings.UpdatedAt, edited)
+	}
+	if notified != 0 {
+		t.Errorf("settings subscribers told %d times, want none: marking updates seen is not a settings edit", notified)
+	}
+
+	// The clock reads 17:00 UTC.
+	if err := e.svc.MarkUpdatesSeen(ctx, first.Add(2*time.Hour)); !errors.Is(err, home.ErrSeenInFuture) {
+		t.Errorf("mark seen through an hour from now = %v, want ErrSeenInFuture", err)
+	}
+}
+
+// An event stored again for a channel switched on later is as new as that
+// row: the update shows its time, and marking it seen clears unread.
+func TestUpdateStoredAgainForAnotherChannel(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	ctx := t.Context()
+	first := time.Date(2026, 10, 13, 15, 0, 0, 0, time.UTC)
+	later := first.Add(30 * time.Minute)
+	e.store(t, notify.PlanReady, "plan_ready:1", first, notify.ChannelPush)
+	e.store(t, notify.PlanReady, "plan_ready:1", later, notify.ChannelChat)
+
+	got, err := e.svc.Updates(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := (store.Timestamp{Time: later}).String(); len(got) != 1 || got[0].CreatedAt != want {
+		t.Fatalf("updates = %+v, want the one event at %s", got, want)
+	}
+	e.at(t, "2026-10-13 12:00")
+	if err := e.svc.MarkUpdatesSeen(ctx, later); err != nil {
+		t.Fatal(err)
+	}
+	if e.at(t, "2026-10-13 12:00").RecentUpdates.Unread {
+		t.Error("unread after the event was marked seen through its listed time")
+	}
+}

internal/household/settings.go

@@ -8,6 +8,7 @@ import (
 	"regexp"
 	"strings"
 	"sync"
+	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
@@ -200,6 +201,21 @@ func (s *SettingsService) Update(ctx context.Context, patch SettingsPatch, updat
 	return settings, nil
 }
 
+// MarkUpdatesSeen records that the household has seen its Recent updates
+// through seenAt: updates_seen_at moves forward to seenAt, and is left as it
+// is when it is already at or after it. It is not a settings edit, so
+// updated_by and updated_at are kept and subscribers are not told.
+func (s *SettingsService) MarkUpdatesSeen(ctx context.Context, seenAt time.Time) error {
+	if seenAt.IsZero() {
+		return errors.New("household: mark updates seen: zero time")
+	}
+	_, err := db.New(s.st.Writer).MarkUpdatesSeen(ctx, store.Timestamp{Time: seenAt.UTC().Truncate(time.Millisecond)}.String())
+	if err != nil {
+		return fmt.Errorf("household: mark updates seen: %w", err)
+	}
+	return nil
+}
+
 // applyPatch applies a validated patch to the household settings row in q's
 // transaction, recording updatedBy, and returns the new row.
 func applyPatch(ctx context.Context, q *db.Queries, patch SettingsPatch, updatedBy string) (db.HouseholdSetting, error) {

internal/ideas/ideas.go

@@ -11,6 +11,7 @@ package ideas
 
 import (
 	"context"
+	"database/sql"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -123,18 +124,18 @@ func NewService(st *store.Store, grounder *recipes.Grounder, generate Generator,
 	}
 	s := &Service{st: st, grounder: grounder, runner: runner, generate: generate, quick: quick, logger: logger}
 	var err error
-	if s.job, err = register(runner, KindFromIngredients, s.run, withoutIdeas[Result]); err != nil {
+	if s.job, err = register(runner, KindFromIngredients, s.run, shownJobResult[Result]); err != nil {
 		return nil, err
 	}
-	if s.quickJob, err = register(runner, KindQuick, s.runQuick, withoutIdeas[QuickResult]); err != nil {
+	if s.quickJob, err = register(runner, KindQuick, s.runQuick, shownJobResult[QuickResult]); err != nil {
 		return nil, err
 	}
 	return s, nil
 }
 
-// register registers the service-only job name, run by run, whose failed
-// jobs show their result through failed.
-func register[P any, R jobs.Public](runner *jobs.Runner, name string, run jobs.Handler[P, R], failed func(json.RawMessage) (json.RawMessage, error)) (*jobs.Kind[P], error) {
+// register registers the service-only job name, run by run, whose jobs
+// show their result through show.
+func register[P any, R jobs.Public](runner *jobs.Runner, name string, run jobs.Handler[P, R], show func(jobs.Status, json.RawMessage) (json.RawMessage, error)) (*jobs.Kind[P], error) {
 	kind, err := jobs.Register(runner, name, run, Reasons...)
 	if err != nil {
 		return nil, err
@@ -142,7 +143,7 @@ func register[P any, R jobs.Public](runner *jobs.Runner, name string, run jobs.H
 	if err := kind.ServiceOnly(); err != nil {
 		return nil, err
 	}
-	if err := kind.FailedResult(failed); err != nil {
+	if err := kind.ShownResult(show); err != nil {
 		return nil, err
 	}
 	return kind, nil
@@ -197,11 +198,13 @@ type Idea struct {
 	// Difficulty is easy, medium or hard.
 	Difficulty string `json:"difficulty"`
 	// Quick says whether the idea is a Quick dinner (see IsQuick).
-	Quick     bool   `json:"quick"`
-	RecipeID  string `json:"recipe_id"`
-	PhotoURL  string `json:"photo_url"`
-	SourceURL string `json:"source_url"`
-	SiteName  string `json:"site_name"`
+	Quick    bool   `json:"quick"`
+	RecipeID string `json:"recipe_id"`
+	PhotoURL string `json:"photo_url"`
+	// SourceURL and SiteName are the grounded recipe's source as
+	// dinners.SourceOf gives it: each null when it could leak a secret.
+	SourceURL *string `json:"source_url"`
+	SiteName  *string `json:"site_name"`
 }
 
 // Result is the KindFromIngredients result, published as the job goes:
@@ -251,6 +254,9 @@ type shownResult[R any] interface {
 	shown() int
 	// cleared is the result showing no ideas.
 	cleared() R
+	// withSafeSources is the result with each idea's source as
+	// shownSource gives it.
+	withSafeSources() (R, error)
 }
 
 func (r Result) shown() int { return len(r.Ideas) }
@@ -260,11 +266,25 @@ func (r Result) cleared() Result {
 	return r
 }
 
+func (r Result) withSafeSources() (Result, error) {
+	ideas := make([]Idea, len(r.Ideas))
+	for i, idea := range r.Ideas {
+		src, err := shownSource(idea.SourceURL, idea.SiteName)
+		if err != nil {
+			return Result{}, fmt.Errorf("ideas: idea %d: %w", i, err)
+		}
+		idea.SourceURL, idea.SiteName = src.URL, src.SiteName
+		ideas[i] = idea
+	}
+	r.Ideas = ideas
+	return r, nil
+}
+
 // finish ends a job whose work returned res and err. A job that failed
 // has its result published again with no ideas, to tidy the stored
 // result. That write is not what keeps a failed job from showing ideas,
 // since it may fail and a job interrupted by restart never makes it:
-// withoutIdeas, applied whenever a failed job is read, is.
+// shownJobResult, applied whenever a failed job is read, is.
 func finish[R shownResult[R]](ctx context.Context, logger *slog.Logger, what string, res R, err error, publish func(R) error) (R, error) {
 	var zero R
 	if err == nil {
@@ -312,9 +332,9 @@ func (s *Service) fill(ctx context.Context, p FromIngredientsJob, publish func(R
 	for i, idea := range out.Ideas {
 		reqs[i] = recipes.GroundRequest{DishName: idea.Name, Query: idea.SearchQuery}
 	}
-	err = keepGrounded(ctx, s.grounder, reqs, skills.IdeasKept, &res.Ideas, &res.Dropped, func(i int, gr recipes.Grounded) (Idea, bool) {
-		idea := ideaOf(out.Ideas[i], gr)
-		return idea, !p.QuickOnly || idea.Quick
+	err = keepGrounded(ctx, s.grounder, reqs, skills.IdeasKept, &res.Ideas, &res.Dropped, func(i int, gr recipes.Grounded) (Idea, bool, error) {
+		idea, err := ideaOf(out.Ideas[i], gr)
+		return idea, !p.QuickOnly || idea.Quick, err
 	}, func() error { return publish(res) })
 	if err != nil {
 		return res, err
@@ -333,9 +353,9 @@ func (s *Service) fill(ctx context.Context, p FromIngredientsJob, publish func(R
 // order (an idea that grounds sooner than one before it is shown first,
 // and the earlier one is put back in its place when it grounds) and
 // publish is called. An idea no recipe grounds, or that keep refuses,
-// counts in *dropped. Any other grounding failure, or publish failing, is
-// returned (see ground).
-func keepGrounded[T any](ctx context.Context, g *recipes.Grounder, reqs []recipes.GroundRequest, want int, shown *[]T, dropped *int, keep func(i int, gr recipes.Grounded) (T, bool), publish func() error) error {
+// counts in *dropped. Any other grounding failure, or keep or publish
+// failing, is returned (see ground).
+func keepGrounded[T any](ctx context.Context, g *recipes.Grounder, reqs []recipes.GroundRequest, want int, shown *[]T, dropped *int, keep func(i int, gr recipes.Grounded) (T, bool, error), publish func() error) error {
 	// order[k] is the index in reqs of (*shown)[k], so each idea is put in
 	// its place in reqs' order as it grounds.
 	var order []int
@@ -348,7 +368,10 @@ func keepGrounded[T any](ctx context.Context, g *recipes.Grounder, reqs []recipe
 				*dropped++
 				return nil
 			}
-			idea, ok := keep(first+i, *gr)
+			idea, ok, err := keep(first+i, *gr)
+			if err != nil {
+				return err
+			}
 			if !ok {
 				*dropped++
 				return nil
@@ -406,19 +429,32 @@ func ground(ctx context.Context, g *recipes.Grounder, reqs []recipes.GroundReque
 	return failed
 }
 
-// withoutIdeas is a failed job's stored result as the job shows it: with no
-// ideas, however the job failed, so a failed job never shows ideas kept
-// before the failure.
-func withoutIdeas[R shownResult[R]](stored json.RawMessage) (json.RawMessage, error) {
+// shownJobResult is a job's stored result as the job shows it. A failed
+// job's shows no ideas, however the job failed, so a failed job never
+// shows ideas kept before the failure. Any other job's shows each idea's
+// source as shownSource gives it, so a result stored before sources were
+// made safe never shows a link or name that could leak a secret.
+func shownJobResult[R shownResult[R]](status jobs.Status, stored json.RawMessage) (json.RawMessage, error) {
 	var res R
 	if err := json.Unmarshal(stored, &res); err != nil {
-		return nil, fmt.Errorf("ideas: decode failed job's result: %w", err)
+		return nil, fmt.Errorf("ideas: decode %s job's result: %w", status, err)
 	}
-	return res.cleared().PublicJSON()
+	if status == jobs.StatusFailed {
+		return res.cleared().PublicJSON()
+	}
+	safe, err := res.withSafeSources()
+	if err != nil {
+		return nil, err
+	}
+	return safe.PublicJSON()
 }
 
 // ideaOf is idea as grounded by gr.
-func ideaOf(idea skills.Idea, gr recipes.Grounded) Idea {
+func ideaOf(idea skills.Idea, gr recipes.Grounded) (Idea, error) {
+	src, err := sourceOf(gr)
+	if err != nil {
+		return Idea{}, err
+	}
 	return Idea{
 		Name:         idea.Name,
 		Uses:         idea.Uses,
@@ -430,9 +466,38 @@ func ideaOf(idea skills.Idea, gr recipes.Grounded) Idea {
 		Quick:        IsQuick(gr.Method, gr.MinutesTotal),
 		RecipeID:     gr.RecipeID,
 		PhotoURL:     dinners.PhotoURL(gr.PhotoID),
-		SourceURL:    gr.SourceURL,
-		SiteName:     gr.SiteName,
+		SourceURL:    src.URL,
+		SiteName:     src.SiteName,
+	}, nil
+}
+
+// sourceOf is gr's recipe source as a client may see it (see
+// dinners.SourceOf): a grounded recipe's site name is stored only when
+// not empty.
+func sourceOf(gr recipes.Grounded) (dinners.Source, error) {
+	src, err := dinners.SourceOf(sql.NullString{String: gr.SiteName, Valid: gr.SiteName != ""}, gr.SourceURL)
+	if err != nil {
+		return dinners.Source{}, fmt.Errorf("ideas: recipe %s: %w", gr.RecipeID, err)
 	}
+	return src, nil
+}
+
+// shownSource is the source of an idea as stored in a job's result, with
+// link sourceURL and site name siteName, as a client may see it (see
+// dinners.SourceOf). A result stored now already holds it, and one stored
+// before sources were made safe holds the grounded recipe's own, with ""
+// for no site name, as sourceOf reads it; a null link, which only a result
+// stored now holds, is checked as "".
+func shownSource(sourceURL, siteName *string) (dinners.Source, error) {
+	var link string
+	if sourceURL != nil {
+		link = *sourceURL
+	}
+	var site sql.NullString
+	if siteName != nil {
+		site = sql.NullString{String: *siteName, Valid: *siteName != ""}
+	}
+	return dinners.SourceOf(site, link)
 }
 
 // QuickJob is the KindQuick payload: the kind of Quick dinner wanted,
@@ -478,8 +543,9 @@ type QuickIdea struct {
 	Difficulty string `json:"difficulty"`
 	RecipeID   string `json:"recipe_id"`
 	PhotoURL   string `json:"photo_url"`
-	SourceURL  string `json:"source_url"`
-	SiteName   string `json:"site_name"`
+	// SourceURL and SiteName are as in Idea.
+	SourceURL *string `json:"source_url"`
+	SiteName  *string `json:"site_name"`
 }
 
 // QuickResult is the KindQuick result, published as the job goes: its
@@ -504,6 +570,20 @@ func (r QuickResult) cleared() QuickResult {
 	return r
 }
 
+func (r QuickResult) withSafeSources() (QuickResult, error) {
+	ideas := make([]QuickIdea, len(r.Ideas))
+	for i, idea := range r.Ideas {
+		src, err := shownSource(idea.SourceURL, idea.SiteName)
+		if err != nil {
+			return QuickResult{}, fmt.Errorf("ideas: idea %d: %w", i, err)
+		}
+		idea.SourceURL, idea.SiteName = src.URL, src.SiteName
+		ideas[i] = idea
+	}
+	r.Ideas = ideas
+	return r, nil
+}
+
 // OfQuickKind reports whether a recipe cooked by method in minutes (nil
 // when unknown) is a Quick dinner of kind: for skills.QuickCrockpot,
 // cooked in a crock pot (normalize_recipe writes a slow cooker as
@@ -564,8 +644,9 @@ func (s *Service) fillQuick(ctx context.Context, p QuickJob, publish func(QuickR
 	for i, idea := range out.Ideas {
 		reqs[i] = recipes.GroundRequest{DishName: idea.Name, Query: idea.SearchQuery}
 	}
-	err = keepGrounded(ctx, s.grounder, reqs, skills.QuickIdeasKept, &res.Ideas, &res.Dropped, func(i int, gr recipes.Grounded) (QuickIdea, bool) {
-		return quickIdeaOf(out.Ideas[i], gr), OfQuickKind(p.Kind, gr.Method, gr.MinutesTotal)
+	err = keepGrounded(ctx, s.grounder, reqs, skills.QuickIdeasKept, &res.Ideas, &res.Dropped, func(i int, gr recipes.Grounded) (QuickIdea, bool, error) {
+		idea, err := quickIdeaOf(out.Ideas[i], gr)
+		return idea, OfQuickKind(p.Kind, gr.Method, gr.MinutesTotal), err
 	}, func() error { return publish(res) })
 	if err != nil {
 		return res, err
@@ -578,7 +659,11 @@ func (s *Service) fillQuick(ctx context.Context, p QuickJob, publish func(QuickR
 }
 
 // quickIdeaOf is idea as grounded by gr.
-func quickIdeaOf(idea skills.QuickIdea, gr recipes.Grounded) QuickIdea {
+func quickIdeaOf(idea skills.QuickIdea, gr recipes.Grounded) (QuickIdea, error) {
+	src, err := sourceOf(gr)
+	if err != nil {
+		return QuickIdea{}, err
+	}
 	return QuickIdea{
 		Name:         idea.Name,
 		Method:       gr.Method,
@@ -586,9 +671,9 @@ func quickIdeaOf(idea skills.QuickIdea, gr recipes.Grounded) QuickIdea {
 		Difficulty:   gr.Difficulty,
 		RecipeID:     gr.RecipeID,
 		PhotoURL:     dinners.PhotoURL(gr.PhotoID),
-		SourceURL:    gr.SourceURL,
-		SiteName:     gr.SiteName,
-	}
+		SourceURL:    src.URL,
+		SiteName:     src.SiteName,
+	}, nil
 }
 
 // Origins of a dinner made from an idea (the dinners.origin column).

internal/ideas/quick_test.go

@@ -369,7 +369,7 @@ func TestStartQuickRunsTheJob(t *testing.T) {
 	if res.Stage != StageDone || res.Kind != skills.QuickCrockpot || !reflect.DeepEqual(res.Exclude, []string{"Beef Stew"}) || len(res.Ideas) != 1 {
 		t.Fatalf("result = %+v", res)
 	}
-	if got := res.Ideas[0]; got.Name != "Pulled Pork" || got.Method != "crockpot" || got.SiteName != "R Kitchen" {
+	if got := res.Ideas[0]; got.Name != "Pulled Pork" || got.Method != "crockpot" || got.SiteName == nil || *got.SiteName != "R Kitchen" {
 		t.Errorf("idea = %+v", got)
 	}
 }

internal/jobs/jobs.go

@@ -136,13 +136,13 @@ type runFunc func(ctx context.Context, payload string, publish func(json.RawMess
 
 // handler is a registered kind: run runs a job, check reports whether a
 // payload decodes into the kind's payload type, serviceOnly is set when
-// Runner.Enqueue refuses the kind, and failedResult, when set, is what Get
-// shows of a failed job's stored result (see Kind.FailedResult).
+// Runner.Enqueue refuses the kind, and shownResult, when set, is what Get
+// shows of a job's stored result (see Kind.ShownResult).
 type handler struct {
-	run          runFunc
-	check        func(payload []byte) bool
-	serviceOnly  bool
-	failedResult func(stored json.RawMessage) (json.RawMessage, error)
+	run         runFunc
+	check       func(payload []byte) bool
+	serviceOnly bool
+	shownResult func(status Status, stored json.RawMessage) (json.RawMessage, error)
 }
 
 // Runner owns the job handlers and the worker pool.
@@ -309,23 +309,24 @@ func (k *Kind[P]) ServiceOnly() error {
 	return nil
 }
 
-// FailedResult makes Get return, for a failed job of the kind with a
-// stored result, show's view of that result instead of the result itself.
-// It is applied on every read, so it holds however the job failed: by its
-// handler, as interrupted by restart, or after a write meant to tidy the
-// result failed. A show error fails Get. A kind that never calls it shows a
-// failed job's last result as stored. It must be called before Start.
-func (k *Kind[P]) FailedResult(show func(stored json.RawMessage) (json.RawMessage, error)) error {
+// ShownResult makes Get return, for a job of the kind with a stored
+// result, show's view of that result, given the job's status, instead of
+// the result itself. It is applied on every read, so it holds for every
+// stored result: however a job failed (by its handler, as interrupted by
+// restart, or after a write meant to tidy the result failed) and whatever
+// version of the kind stored it. A show error fails Get. A kind that never
+// calls it shows a job's result as stored. It must be called before Start.
+func (k *Kind[P]) ShownResult(show func(status Status, stored json.RawMessage) (json.RawMessage, error)) error {
 	if show == nil {
-		return fmt.Errorf("jobs: failed result %q: nil func", k.name)
+		return fmt.Errorf("jobs: shown result %q: nil func", k.name)
 	}
 	k.r.mu.Lock()
 	defer k.r.mu.Unlock()
 	if k.r.started {
-		return fmt.Errorf("jobs: failed result %q: runner already started", k.name)
+		return fmt.Errorf("jobs: shown result %q: runner already started", k.name)
 	}
 	h := k.r.handlers[k.name]
-	h.failedResult = show
+	h.shownResult = show
 	k.r.handlers[k.name] = h
 	return nil
 }
@@ -425,8 +426,8 @@ func (r *Runner) Wait() {
 	r.wg.Wait()
 }
 
-// Get returns the job with id, or ErrNotFound. A failed job's result is
-// shown through its kind's FailedResult, when the kind set one.
+// Get returns the job with id, or ErrNotFound. A job's result is shown
+// through its kind's ShownResult, when the kind set one.
 func (r *Runner) Get(ctx context.Context, id string) (Job, error) {
 	row, err := db.New(r.st.Reader).GetJob(ctx, id)
 	if errors.Is(err, sql.ErrNoRows) {
@@ -442,17 +443,17 @@ func (r *Runner) Get(ctx context.Context, id string) (Job, error) {
 	if row.Error.Valid {
 		job.Error = &row.Error.String
 	}
-	if job.Status == StatusFailed && job.Result != nil {
+	if job.Result != nil {
 		r.mu.Lock()
-		show := r.handlers[job.Kind].failedResult
+		show := r.handlers[job.Kind].shownResult
 		r.mu.Unlock()
 		if show != nil {
-			shown, err := show(job.Result)
+			shown, err := show(job.Status, job.Result)
 			if err != nil {
-				return Job{}, fmt.Errorf("jobs: show failed %s result: %w", job.Kind, err)
+				return Job{}, fmt.Errorf("jobs: show %s %s result: %w", job.Status, job.Kind, err)
 			}
 			if !json.Valid(shown) {
-				return Job{}, fmt.Errorf("jobs: show failed %s result: not one JSON value", job.Kind)
+				return Job{}, fmt.Errorf("jobs: show %s %s result: not one JSON value", job.Status, job.Kind)
 			}
 			job.Result = shown
 		}

internal/jobs/jobs_test.go

@@ -773,7 +773,7 @@ func TestServiceOnlyKind(t *testing.T) {
 	}
 }
 
-func TestFailedResultAppliesOnlyToItsKindsFailedJobs(t *testing.T) {
+func TestShownResultAppliesOnlyToItsKindsJobs(t *testing.T) {
 	t.Parallel()
 	st := migratedStore(t)
 	r := newRunner(t, st, 1)
@@ -788,17 +788,24 @@ func TestFailedResultAppliesOnlyToItsKindsFailedJobs(t *testing.T) {
 	}
 	hidden := register(t, r, "hidden", h, "stopped")
 	plain := register(t, r, "plain", h, "stopped")
-	if err := hidden.FailedResult(func(json.RawMessage) (json.RawMessage, error) {
-		return json.RawMessage(`{"done":0}`), nil
+	if err := hidden.ShownResult(func(status Status, stored json.RawMessage) (json.RawMessage, error) {
+		if status == StatusFailed {
+			return json.RawMessage(`{"done":0}`), nil
+		}
+		var res countResult
+		if err := json.Unmarshal(stored, &res); err != nil {
+			return nil, err
+		}
+		return json.Marshal(countResult{Done: res.Done * 10})
 	}); err != nil {
 		t.Fatal(err)
 	}
-	if err := hidden.FailedResult(nil); err == nil {
-		t.Error("FailedResult(nil) succeeded, want an error")
+	if err := hidden.ShownResult(nil); err == nil {
+		t.Error("ShownResult(nil) succeeded, want an error")
 	}
 	start(t, r)
-	if err := hidden.FailedResult(func(s json.RawMessage) (json.RawMessage, error) { return s, nil }); err == nil {
-		t.Error("FailedResult after Start succeeded, want an error")
+	if err := hidden.ShownResult(func(_ Status, s json.RawMessage) (json.RawMessage, error) { return s, nil }); err == nil {
+		t.Error("ShownResult after Start succeeded, want an error")
 	}
 
 	for _, tc := range []struct {
@@ -806,9 +813,10 @@ func TestFailedResultAppliesOnlyToItsKindsFailedJobs(t *testing.T) {
 		steps int
 		want  string
 	}{
-		{hidden, 0, `{"done":0}`}, // failed: shown through FailedResult
-		{hidden, 3, `{"done":3}`}, // succeeded: as stored
-		{plain, 0, `{"done":5}`},  // failed, kind without FailedResult: as stored
+		{hidden, 0, `{"done":0}`},  // failed: shown through ShownResult
+		{hidden, 3, `{"done":30}`}, // succeeded: shown through ShownResult
+		{plain, 0, `{"done":5}`},   // failed, kind without ShownResult: as stored
+		{plain, 3, `{"done":3}`},   // succeeded, kind without ShownResult: as stored
 	} {
 		job := waitFor(t, r, enqueue(t, tc.kind, countPayload{Steps: tc.steps}), finished)
 		if string(job.Result) != tc.want {

internal/notify/notify.go

@@ -27,6 +27,7 @@ import (
 	"fmt"
 	"log/slog"
 	"net/url"
+	"slices"
 	"strings"
 	"sync"
 	"time"
@@ -189,6 +190,61 @@ func (s *Service) EmitTx(ctx context.Context, tx *sql.Tx, ev Event) error {
 	})
 }
 
+// StoredSince reports whether a notification was stored after since, or
+// at all when since is nil. An event counts once it is stored for any
+// channel, whatever became of its delivery; one whose preference switches
+// every channel off is never stored and never counts.
+func (s *Service) StoredSince(ctx context.Context, since *time.Time) (bool, error) {
+	var after sql.NullString
+	if since != nil {
+		after = sql.NullString{String: timestamp(*since), Valid: true}
+	}
+	found, err := db.New(s.st.Reader).HasNotificationSince(ctx, after)
+	if err != nil {
+		return false, fmt.Errorf("notify: read notifications since %s: %w", after.String, err)
+	}
+	return found, nil
+}
+
+// Stored is one event as it was stored, whatever channels it went to.
+type Stored struct {
+	Type  EventType
+	Title string
+	Body  string
+	// URL is the path-absolute, same-origin path the event opens.
+	URL string
+	// CreatedAt is when the event was last stored, for any channel: the
+	// instant StoredSince must be given for it not to count.
+	CreatedAt time.Time
+}
+
+// Recent returns the last n distinct events stored, newest first. An event
+// stored for more than one channel is one event, as new as its newest row;
+// one whose preference switches every channel off is never stored and
+// never listed.
+func (s *Service) Recent(ctx context.Context, n int) ([]Stored, error) {
+	if n <= 0 {
+		return nil, fmt.Errorf("notify: list %d recent events: want a positive count", n)
+	}
+	rows, err := db.New(s.st.Reader).ListRecentNotifications(ctx, int64(n))
+	if err != nil {
+		return nil, fmt.Errorf("notify: list recent events: %w", err)
+	}
+	out := make([]Stored, 0, len(rows))
+	for _, r := range rows {
+		var p Payload
+		if err := json.Unmarshal([]byte(r.Payload), &p); err != nil {
+			return nil, fmt.Errorf("notify: decode payload of %s: %w", r.EventKey, err)
+		}
+		created, err := parseTimestamp(r.CreatedAt)
+		if err != nil {
+			return nil, fmt.Errorf("notify: created_at of %s: %w", r.EventKey, err)
+		}
+		out = append(out, Stored{Type: p.Event, Title: p.Title, Body: p.Body, URL: p.URL, CreatedAt: created})
+	}
+	return out, nil
+}
+
 // emitTx stores ev in tx for each channel that channels chooses from the
 // preference of ev's type.
 func (s *Service) emitTx(ctx context.Context, tx *sql.Tx, ev Event, channels func(db.NotificationPref) ([]Channel, error)) error {
@@ -238,6 +294,19 @@ func (s *Service) emitTx(ctx context.Context, tx *sql.Tx, ev Event, channels fun
 	return nil
 }
 
+// ChannelOn reports whether the preference of event type ev switches
+// channel ch on. A type with no preference row is an error.
+func (s *Service) ChannelOn(ctx context.Context, ev EventType, ch Channel) (bool, error) {
+	pref, err := db.New(s.st.Reader).GetNotificationPref(ctx, string(ev))
+	if errors.Is(err, sql.ErrNoRows) {
+		return false, fmt.Errorf("notify: no notification preference for %s", ev)
+	}
+	if err != nil {
+		return false, fmt.Errorf("notify: read notification preference for %s: %w", ev, err)
+	}
+	return slices.Contains(enabledChannels(pref), ch), nil
+}
+
 // enabledChannels returns the channels pref switches on.
 func enabledChannels(pref db.NotificationPref) []Channel {
 	var chs []Channel

internal/plan/draft.go

@@ -234,6 +234,7 @@ func (s *Service) storeDraft(ctx context.Context, weekStart, thisWeek store.Loca
 		return "", err
 	}
 	s.notifier.Wake()
+	s.wake()
 	return planID, nil
 }
 

internal/plan/plan.go

@@ -141,6 +141,9 @@ type Service struct {
 	draft    Drafter
 	cal      Calendar
 	notifier *notify.Service
+	// wake is called after every committed change to a plan's days, which
+	// can move a crock-pot dinner's start reminder.
+	wake     func()
 	logger   *slog.Logger
 	draftJob *jobs.Kind[DraftJob]
 	// publicURL is MEALQUEST_PUBLIC_URL, under which a pushed event links
@@ -150,11 +153,12 @@ type Service struct {
 
 // NewService returns a service over st that drafts with draft, pushes to
 // cal with links under publicURL, tells the household through notifier,
-// which must be over st, and registers the KindDraftWeek job on
+// which must be over st, calls wake (the scheduler's Wake) after every
+// committed change to a plan's days, and registers the KindDraftWeek job on
 // runner, which must not have started yet. The kind is service-only:
-// StartDraft, which keeps one draft in flight per week, is the only way to
-// enqueue it.
-func NewService(st *store.Store, draft Drafter, runner *jobs.Runner, cal Calendar, notifier *notify.Service, publicURL *url.URL, logger *slog.Logger) (*Service, error) {
+// StartDraft and StartScheduledDraft, which keep one draft in flight per
+// week, are the only way to enqueue it.
+func NewService(st *store.Store, draft Drafter, runner *jobs.Runner, cal Calendar, notifier *notify.Service, wake func(), publicURL *url.URL, logger *slog.Logger) (*Service, error) {
 	switch {
 	case st == nil:
 		return nil, errors.New("plan: nil store")
@@ -166,12 +170,14 @@ func NewService(st *store.Store, draft Drafter, runner *jobs.Runner, cal Calenda
 		return nil, errors.New("plan: nil calendar")
 	case notifier == nil:
 		return nil, errors.New("plan: nil notifier")
+	case wake == nil:
+		return nil, errors.New("plan: nil wake")
 	case publicURL == nil:
 		return nil, errors.New("plan: nil public URL")
 	case logger == nil:
 		return nil, errors.New("plan: nil logger")
 	}
-	s := &Service{st: st, draft: draft, cal: cal, notifier: notifier, logger: logger, publicURL: publicURL}
+	s := &Service{st: st, draft: draft, cal: cal, notifier: notifier, wake: wake, logger: logger, publicURL: publicURL}
 	kind, err := jobs.Register(runner, KindDraftWeek, s.runDraft, Reasons...)
 	if err != nil {
 		return nil, err
@@ -233,10 +239,10 @@ func (s *Service) Get(ctx context.Context, weekStart store.LocalDate) (p Plan, e
 }
 
 // EmitDayOfReminder emits day_of_reminder for date, keyed by the date,
-// naming the dinner planned on it, and reports whether it did: a date whose
-// week has no plan emits nothing. The scheduler calls it at the
-// household's reminder_time (Feature 20); emitting a date again stores no
-// second notification.
+// "Tonight: {dinner} · Recipe →" for the dinner planned on it, and reports
+// whether it did: a date whose week has no plan emits nothing. The
+// day_of_reminder schedule calls it at the household's reminder_time
+// (ReminderSchedules); emitting a date again stores no second notification.
 func (s *Service) EmitDayOfReminder(ctx context.Context, date store.LocalDate) (bool, error) {
 	p, err := s.Get(ctx, household.WeekStart(date))
 	if errors.Is(err, ErrNotFound) {
@@ -245,15 +251,14 @@ func (s *Service) EmitDayOfReminder(ctx context.Context, date store.LocalDate) (
 	if err != nil {
 		return false, err
 	}
-	for _, d := range p.Days {
-		if d.Date == date.String() {
-			if err := s.notifier.Emit(ctx, chat.DayOfReminder(date, d.Dinner.ID, d.Dinner.Name)); err != nil {
-				return false, fmt.Errorf("plan: %w", err)
-			}
-			return true, nil
-		}
+	d, err := p.day(date)
+	if err != nil {
+		return false, err
 	}
-	return false, fmt.Errorf("plan: week %s has no day %s", p.WeekStart, date)
+	if err := s.notifier.Emit(ctx, chat.DayOfReminder(date, d.Dinner.ID, d.Dinner.Name)); err != nil {
+		return false, fmt.Errorf("plan: %w", err)
+	}
+	return true, nil
 }
 
 // readPlan reads the plan of the week starting weekStart through q, with
@@ -342,10 +347,27 @@ type Draft struct {
 // enqueues nothing. Drafting over a synced or changed plan needs confirm,
 // else it fails with ErrConfirmRequired and enqueues nothing.
 func (s *Service) StartDraft(ctx context.Context, weekStart store.LocalDate, confirm bool) (Draft, error) {
+	d, _, err := s.startDraft(ctx, weekStart, confirm, false)
+	return d, err
+}
+
+// StartScheduledDraft is StartDraft, without confirm, for the plan_draft
+// schedule: it enqueues the same KindDraftWeek job, or returns the one
+// queued or running, only while the week starting weekStart has no plan.
+// A week that has a plan, in any status, is left as it is: nothing is
+// enqueued and planned is true.
+func (s *Service) StartScheduledDraft(ctx context.Context, weekStart store.LocalDate) (d Draft, planned bool, err error) {
+	return s.startDraft(ctx, weekStart, false, true)
+}
+
+// startDraft is StartDraft, and when onlyUnplanned is set it enqueues
+// nothing for a week that has a plan and reports planned true.
+func (s *Service) startDraft(ctx context.Context, weekStart store.LocalDate, confirm, onlyUnplanned bool) (Draft, bool, error) {
 	if _, err := household.WeekDays(weekStart); err != nil {
-		return Draft{}, &InvalidWeekError{Value: weekStart.String()}
+		return Draft{}, false, &InvalidWeekError{Value: weekStart.String()}
 	}
 	var d Draft
+	planned := false
 	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
 		q := db.New(tx)
 		cur, err := q.GetWeekPlan(ctx, weekStart.String())
@@ -353,6 +375,9 @@ func (s *Service) StartDraft(ctx context.Context, weekStart store.LocalDate, con
 		case errors.Is(err, sql.ErrNoRows):
 		case err != nil:
 			return fmt.Errorf("plan: read week %s: %w", weekStart, err)
+		case onlyUnplanned:
+			planned = true
+			return nil
 		case cur.Status != StatusDraft && !confirm:
 			return ErrConfirmRequired
 		}
@@ -375,12 +400,12 @@ func (s *Service) StartDraft(ctx context.Context, weekStart store.LocalDate, con
 		return nil
 	})
 	if err != nil {
-		return Draft{}, err
+		return Draft{}, false, err
 	}
 	if d.Created {
 		s.draftJob.Wake()
 	}
-	return d, nil
+	return d, planned, nil
 }
 
 // Swap plans dinnerID on date of the week starting weekStart, marking the
@@ -450,6 +475,7 @@ func (s *Service) Swap(ctx context.Context, weekStart store.LocalDate, date, din
 	if err != nil {
 		return Plan{}, err
 	}
+	s.wake()
 	return p, nil
 }
 

internal/plan/plan_test.go

@@ -146,7 +146,7 @@ func newEnv(t *testing.T) *env {
 	if err != nil {
 		t.Fatal(err)
 	}
-	e.svc, err = plan.NewService(st, drafter, e.runner, e.gcal, notifytest.New(t, st), publicURL, logger)
+	e.svc, err = plan.NewService(st, drafter, e.runner, e.gcal, notifytest.New(t, st), func() {}, publicURL, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -375,9 +375,9 @@ func TestDraftEmitsPlanReady(t *testing.T) {
 	}
 	for _, r := range rows {
 		p := r.Payload
-		if r.Key != "plan_ready:2026-10-12" || p.Tag != r.Key || p.URL != "/plan" || p.Week != "2026-10-12" ||
+		if r.Key != "plan_ready:2026-10-12" || p.Tag != r.Key || p.URL != "/plan?week=2026-10-12" || p.Week != "2026-10-12" ||
 			p.Title != want.Title || p.Body != "Beef Chili, Pot Roast, Pad Thai + 4 more" {
-			t.Errorf("%s row = %+v, want key plan_ready:2026-10-12, title %q, the drafted dinners and /plan", r.Channel, r, want.Title)
+			t.Errorf("%s row = %+v, want key plan_ready:2026-10-12, title %q, the drafted dinners and /plan?week=2026-10-12", r.Channel, r, want.Title)
 		}
 	}
 
@@ -428,8 +428,8 @@ func TestEmitDayOfReminder(t *testing.T) {
 		t.Fatalf("day_of_reminder rows = %+v, want one on push", rows)
 	}
 	r := rows[0]
-	if r.Key != "day_of_reminder:2026-10-14" || r.Channel != notify.ChannelPush || r.Payload.Title != "Tonight's dinner" ||
-		r.Payload.Body != "Pad Thai" || r.Payload.URL != "/dinner/"+e.ids["Pad Thai"] || r.Payload.Week != "2026-10-12" {
+	if r.Key != "day_of_reminder:2026-10-14" || r.Channel != notify.ChannelPush || r.Payload.Title != "Tonight: Pad Thai · Recipe →" ||
+		r.Payload.Body != "" || r.Payload.URL != "/dinner/"+e.ids["Pad Thai"] || r.Payload.Week != "2026-10-12" {
 		t.Errorf("day_of_reminder row = %+v", r)
 	}
 }

internal/plan/reminder.go

@@ -0,0 +1,150 @@
+package plan
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/chat"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// StartReminderLead is how long before a crock-pot dinner's start_by its
+// start reminder fires.
+const StartReminderLead = 15 * time.Minute
+
+// StartReminderKey is the period key prefix of the crock-pot start
+// reminder: its periods are start:YYYY-MM-DD of the day_of_reminder
+// schedule.
+const StartReminderKey = "start"
+
+// ReminderSchedules are the day_of_reminder schedules. The first fires
+// every day at the household's reminder_time, period YYYY-MM-DD, and emits
+// day_of_reminder:YYYY-MM-DD for tonight's dinner (EmitDayOfReminder). The
+// second fires StartReminderLead before the start_by of a crock-pot dinner
+// whose start_by is earlier than that day's reminder_time, period
+// start:YYYY-MM-DD of the dinner's date, and emits
+// day_of_reminder:start:YYYY-MM-DD (EmitStartReminder). A date whose week
+// has no plan emits neither.
+func (s *Service) ReminderSchedules() []scheduler.Schedule {
+	return []scheduler.Schedule{
+		{
+			Name: scheduler.DayOfReminder,
+			Rule: func(settings household.Settings) scheduler.Rule {
+				return scheduler.Daily(settings.ReminderTime)
+			},
+			Run: func(ctx context.Context, p scheduler.Period) error {
+				sent, err := s.EmitDayOfReminder(ctx, p.Date)
+				if err != nil {
+					return err
+				}
+				if !sent {
+					s.logger.InfoContext(ctx, "day-of reminder not sent: the week has no plan",
+						"period", p.Key, "date", p.Date.String())
+				}
+				return nil
+			},
+		},
+		{
+			Name: scheduler.DayOfReminder,
+			Key:  StartReminderKey,
+			Rule: func(household.Settings) scheduler.Rule {
+				return scheduler.DailyAt(s.startReminderAt)
+			},
+			Run: func(ctx context.Context, p scheduler.Period) error {
+				sent, err := s.EmitStartReminder(ctx, p.Date)
+				if err != nil {
+					return err
+				}
+				if !sent {
+					s.logger.InfoContext(ctx, "start reminder not sent: no crock-pot dinner to start before the reminder",
+						"period", p.Key, "date", p.Date.String())
+				}
+				return nil
+			},
+		},
+	}
+}
+
+// EmitStartReminder emits day_of_reminder:start:{date}, "Start the crock
+// pot by {time}", for the crock-pot dinner planned on date, and reports
+// whether it did: it emits nothing unless date's dinner has a start_by
+// earlier than date's reminder_time. Emitting a date again stores no
+// second notification.
+func (s *Service) EmitStartReminder(ctx context.Context, date store.LocalDate) (bool, error) {
+	d, ok, err := s.startReminder(ctx, date)
+	if err != nil || !ok {
+		return false, err
+	}
+	if err := s.notifier.Emit(ctx, chat.StartReminder(date, d.Dinner.ID, d.Dinner.Name, *d.StartBy)); err != nil {
+		return false, fmt.Errorf("plan: %w", err)
+	}
+	return true, nil
+}
+
+// startReminderAt is the start reminder's scheduler.FireAt: the
+// StartReminderLead before start_by of the dinner date's start reminder,
+// if it has one.
+func (s *Service) startReminderAt(ctx context.Context, date store.LocalDate) (time.Time, bool, error) {
+	d, ok, err := s.startReminder(ctx, date)
+	if err != nil || !ok {
+		return time.Time{}, false, err
+	}
+	return d.StartBy.Add(-StartReminderLead), true, nil
+}
+
+// startReminder returns the plan day of date when it has a start reminder:
+// its dinner has a start_by (a crock-pot dinner of known minutes) earlier
+// than the household's reminder_time on date. The plan and the settings
+// come from one read transaction.
+func (s *Service) startReminder(ctx context.Context, date store.LocalDate) (d Day, ok bool, err error) {
+	tx, err := s.st.Reader.BeginTx(ctx, nil)
+	if err != nil {
+		return Day{}, false, fmt.Errorf("plan: begin read: %w", err)
+	}
+	defer func() {
+		err = errors.Join(err, tx.Rollback())
+	}()
+	q := db.New(tx)
+	p, err := readPlan(ctx, q, household.WeekStart(date))
+	if errors.Is(err, ErrNotFound) {
+		return Day{}, false, nil
+	}
+	if err != nil {
+		return Day{}, false, err
+	}
+	d, err = p.day(date)
+	if err != nil {
+		return Day{}, false, err
+	}
+	if d.StartBy == nil {
+		return Day{}, false, nil
+	}
+	settings, err := q.GetHouseholdSettings(ctx)
+	if err != nil {
+		return Day{}, false, fmt.Errorf("plan: read household settings: %w", err)
+	}
+	zone, err := household.LoadZone(settings.Timezone)
+	if err != nil {
+		return Day{}, false, fmt.Errorf("plan: household settings: %w", err)
+	}
+	remind, err := household.LocalTime(zone, date, settings.ReminderTime)
+	if err != nil {
+		return Day{}, false, fmt.Errorf("plan: reminder time of %s: %w", date, err)
+	}
+	return d, d.StartBy.Before(remind), nil
+}
+
+// day returns p's day on date; a plan holds all seven days of its week.
+func (p Plan) day(date store.LocalDate) (Day, error) {
+	for _, d := range p.Days {
+		if d.Date == date.String() {
+			return d, nil
+		}
+	}
+	return Day{}, fmt.Errorf("plan: week %s has no day %s", p.WeekStart, date)
+}

internal/plan/rotation.go

@@ -6,8 +6,11 @@ import (
 	"errors"
 	"fmt"
 
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/chat"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 )
 
@@ -79,12 +82,40 @@ type Decided struct {
 	UpdatedBy    string `json:"updated_by"`
 }
 
+// RotationCheckSchedule is the rotation_check schedule: every day at the
+// household's review_time it runs MarkTried for the day before, so each
+// Quest log dinner planned yesterday is tried and the household is asked
+// "Keep it in rotation?". Its period is the fire date, claimed as
+// rotation_check:YYYY-MM-DD. It never makes a dinner a Regular.
+func (s *Service) RotationCheckSchedule() scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.RotationCheck,
+		Rule: func(settings household.Settings) scheduler.Rule {
+			return scheduler.Daily(settings.ReviewTime)
+		},
+		PeriodKey: func(p scheduler.Period) string {
+			return scheduler.RotationCheck + ":" + p.Key
+		},
+		Run: func(ctx context.Context, p scheduler.Period) error {
+			yesterday := addDays(p.Date, -1)
+			n, err := s.MarkTried(ctx, yesterday)
+			if err != nil {
+				return err
+			}
+			s.logger.InfoContext(ctx, "Rotation check: Quest log dinners marked tried",
+				"period", p.Key, "plan_date", yesterday.String(), "tried", n)
+			return nil
+		},
+	}
+}
+
 // MarkTried moves every dinner in the Quest log planned on date, the
-// household-local day just past, on a plan of any status, to tried and
-// opens a pending Rotation check of it for date. It is idempotent: a
-// dinner already checked for date is left as it is, so a later run never
-// moves one returned to the Quest log ("We didn't make it") again. It
-// returns how many dinners it moved.
+// household-local day just past, on a plan of any status, to tried, opens
+// a pending Rotation check of it for date and emits its rotation_review
+// (chat.RotationReview), all in one transaction. It is idempotent: a
+// dinner already checked for date is left as it is and not notified of
+// again, so a later run never moves one returned to the Quest log ("We
+// didn't make it") again. It returns how many dinners it moved.
 func (s *Service) MarkTried(ctx context.Context, date store.LocalDate) (int, error) {
 	var n int
 	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
@@ -95,6 +126,10 @@ func (s *Service) MarkTried(ctx context.Context, date store.LocalDate) (int, err
 		}
 		now := store.Now().String()
 		for _, id := range ids {
+			d, err := q.GetDinner(ctx, id)
+			if err != nil {
+				return fmt.Errorf("plan: read dinner %s: %w", id, err)
+			}
 			moved, err := q.MarkDinnerTried(ctx, db.MarkDinnerTriedParams{UpdatedAt: now, ID: id})
 			if err != nil {
 				return fmt.Errorf("plan: mark %s tried: %w", id, err)
@@ -107,6 +142,9 @@ func (s *Service) MarkTried(ctx context.Context, date store.LocalDate) (int, err
 			}); err != nil {
 				return fmt.Errorf("plan: open Rotation check of %s for %s: %w", id, date, err)
 			}
+			if err := s.notifier.EmitTx(ctx, tx, chat.RotationReview(id, d.Name, date)); err != nil {
+				return fmt.Errorf("plan: %w", err)
+			}
 		}
 		n = len(ids)
 		return nil
@@ -114,6 +152,9 @@ func (s *Service) MarkTried(ctx context.Context, date store.LocalDate) (int, err
 	if err != nil {
 		return 0, err
 	}
+	if n > 0 {
+		s.notifier.Wake()
+	}
 	return n, nil
 }
 

internal/plan/schedule.go

@@ -0,0 +1,42 @@
+package plan
+
+import (
+	"context"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+)
+
+// DraftSchedule is the plan_draft schedule: at the household's
+// plan_draft_dow and plan_draft_time it drafts the week after the fire
+// date's, its period scheduler.WeeklyForNextWeek keys plan_draft:YYYY-Www
+// for that week. The draft is the KindDraftWeek job a manual draft runs
+// (StartScheduledDraft), so a stored draft emits plan_ready keyed
+// plan_ready:{weekStart} and a draft that fails, as when the AI fails,
+// stores no plan and emits nothing. A week that already has a plan is left
+// as it is, and so is a draft of it already queued or running; either way
+// the period says so.
+func (s *Service) DraftSchedule() scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.PlanDraft,
+		Rule: func(settings household.Settings) scheduler.Rule {
+			return scheduler.WeeklyForNextWeek(time.Weekday(settings.PlanDraftDow), settings.PlanDraftTime)
+		},
+		Run: func(ctx context.Context, p scheduler.Period) error {
+			d, planned, err := s.StartScheduledDraft(ctx, p.Week)
+			if err != nil {
+				return err
+			}
+			switch {
+			case planned:
+				s.logger.InfoContext(ctx, "scheduled week draft not started: the week already has a plan",
+					"period", p.Key, "week_start", p.Week.String())
+			case !d.Created:
+				s.logger.WarnContext(ctx, "scheduled week draft not started: a draft of the week is already under way",
+					"period", p.Key, "week_start", p.Week.String(), "job_id", d.JobID)
+			}
+			return nil
+		},
+	}
+}

internal/scheduler/day_of_reminder_test.go

@@ -0,0 +1,328 @@
+package scheduler_test
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify/notifytest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// The tests in this file run plan's day_of_reminder schedules on the fake
+// clock against the real plan service and notification outbox. The plan of
+// the week of Monday Oct 12 (w42) has poolNames Monday to Sunday: Beef
+// Chili on Monday, Pot Roast on Tuesday. The household's dinner time is the
+// seeded 17:30 and its reminder time the seeded 16:30, in Chicago.
+
+// w42 is the Monday of 2026-W42.
+var w42 = mustLocalDate("2026-10-12")
+
+// planWeek drafts the plan of the week starting weekStart and waits for it.
+func (p *planEnv) planWeek(weekStart store.LocalDate) {
+	p.e.t.Helper()
+	p.reply(weekStart)
+	if _, err := p.svc.StartDraft(context.Background(), weekStart, false); err != nil {
+		p.e.t.Fatal(err)
+	}
+	if jobs := p.e.drafts(); jobs[len(jobs)-1] != succeeded {
+		p.e.t.Fatalf("draft of %s = %+v, want succeeded", weekStart, jobs)
+	}
+}
+
+// crockPot makes the dinner name a crock-pot dinner of minutes.
+func (p *planEnv) crockPot(name string, minutes int) {
+	p.e.t.Helper()
+	if _, err := p.e.st.Writer.Exec(`UPDATE dinners SET method = 'crockpot', minutes_total = ? WHERE id = ?`, minutes, p.ids[name]); err != nil {
+		p.e.t.Fatal(err)
+	}
+}
+
+// reminders returns the day_of_reminder notifications stored, oldest
+// first. The seeded preference sends day_of_reminder to push only, so there
+// is one row per event.
+func (e *env) reminders() []notifytest.Row {
+	e.t.Helper()
+	rows := notifytest.Rows(e.t, e.st, notify.DayOfReminder)
+	for _, r := range rows {
+		if r.Channel != notify.ChannelPush {
+			e.t.Fatalf("day_of_reminder row %+v, want push only", r)
+		}
+	}
+	return rows
+}
+
+// reminderKeys returns the keys of e.reminders().
+func (e *env) reminderKeys() []string {
+	e.t.Helper()
+	var keys []string
+	for _, r := range e.reminders() {
+		keys = append(keys, r.Key)
+	}
+	return keys
+}
+
+// wantReminder fails unless the reminder keyed key was stored with title,
+// body and the link to the dinner name.
+func (p *planEnv) wantReminder(key, title, body, name string) {
+	p.e.t.Helper()
+	for _, r := range p.e.reminders() {
+		if r.Key != key {
+			continue
+		}
+		week := household.WeekStart(mustLocalDate(key[len(key)-len("YYYY-MM-DD"):]))
+		want := notify.Payload{Event: notify.DayOfReminder, Title: title, Body: body, URL: "/dinner/" + p.ids[name], Tag: key, Week: week.String()}
+		if r.Payload != want {
+			p.e.t.Errorf("reminder %s = %+v, want %+v", key, r.Payload, want)
+		}
+		return
+	}
+	p.e.t.Errorf("no reminder %s", key)
+}
+
+// TestDayOfReminderNormalNight: a night whose dinner is not a crock-pot
+// dinner gets exactly the daily reminder, at reminder_time 16:30, keyed
+// day_of_reminder:YYYY-MM-DD and linking to the dinner.
+func TestDayOfReminderNormalNight(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	p.planWeek(w42)
+
+	// Monday 08:00: the catch-up of Sunday 16:30 finds no plan for W41.
+	r := e.start(at(2026, 10, 12, 8, 0), p.svc.ReminderSchedules()...)
+	r.runUntil(at(2026, 10, 12, 16, 29))
+	wantKeys(t, "before 16:30", e.reminderKeys(), nil)
+
+	r.runUntil(at(2026, 10, 12, 16, 30))
+	wantKeys(t, "at 16:30", e.reminderKeys(), []string{"day_of_reminder:2026-10-12"})
+	p.wantReminder("day_of_reminder:2026-10-12", "Tonight: Beef Chili · Recipe →", "", "Beef Chili")
+
+	r.runUntil(at(2026, 10, 13, 23, 59))
+	wantKeys(t, "Tuesday", e.reminderKeys(), []string{"day_of_reminder:2026-10-12", "day_of_reminder:2026-10-13"})
+	p.wantReminder("day_of_reminder:2026-10-13", "Tonight: Pot Roast · Recipe →", "", "Pot Roast")
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder), []string{"2026-10-11", "2026-10-12", "2026-10-13"})
+}
+
+// TestDayOfReminderCrockPotNight: a crock-pot night whose start_by is
+// earlier than reminder_time gets the start reminder at start_by minus 15
+// minutes, keyed day_of_reminder:start:YYYY-MM-DD, and the daily reminder
+// at reminder_time. A crock-pot night whose start_by is not earlier than
+// reminder_time gets only the daily one.
+func TestDayOfReminderCrockPotNight(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	p.crockPot("Beef Chili", 480) // Monday: start by 09:30
+	p.crockPot("Pot Roast", 30)   // Tuesday: start by 17:00, after 16:30
+	p.planWeek(w42)
+
+	r := e.start(at(2026, 10, 12, 8, 0), p.svc.ReminderSchedules()...)
+	r.runUntil(at(2026, 10, 12, 9, 14))
+	wantKeys(t, "before 09:15", e.reminderKeys(), nil)
+
+	r.runUntil(at(2026, 10, 12, 9, 15))
+	wantKeys(t, "at 09:15", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12"})
+	p.wantReminder("day_of_reminder:start:2026-10-12", "Start the crock pot by 9:30 am", "Beef Chili", "Beef Chili")
+
+	r.runUntil(at(2026, 10, 12, 16, 29))
+	wantKeys(t, "before 16:30", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12"})
+	r.runUntil(at(2026, 10, 12, 16, 30))
+	wantKeys(t, "at 16:30", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12", "day_of_reminder:2026-10-12"})
+	p.wantReminder("day_of_reminder:2026-10-12", "Tonight: Beef Chili · Recipe →", "", "Beef Chili")
+
+	r.runUntil(at(2026, 10, 13, 23, 59))
+	wantKeys(t, "Tuesday", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12", "day_of_reminder:2026-10-12", "day_of_reminder:2026-10-13"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder), []string{"2026-10-11", "2026-10-12", "2026-10-13", "start:2026-10-12"})
+}
+
+// TestDayOfReminderEmptyNight: with no plan for tonight's week, here none
+// at all and then only next week's, nothing is emitted and nothing fails;
+// next week's crock-pot Monday is reminded on its own day.
+func TestDayOfReminderEmptyNight(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+
+	r := e.start(at(2026, 10, 12, 8, 0), p.svc.ReminderSchedules()...)
+	r.runUntil(at(2026, 10, 13, 23, 59))
+	wantKeys(t, "with no plan", e.reminderKeys(), nil)
+
+	p.crockPot("Beef Chili", 480)
+	p.planWeek(w43)
+	r.runUntil(at(2026, 10, 18, 23, 59))
+	wantKeys(t, "with only next week's plan", e.reminderKeys(), nil)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder),
+		[]string{"2026-10-11", "2026-10-12", "2026-10-13", "2026-10-14", "2026-10-15", "2026-10-16", "2026-10-17", "2026-10-18"})
+	if logs := p.logs.String(); !strings.Contains(logs, "day-of reminder not sent: the week has no plan") || strings.Contains(logs, "level=ERROR") {
+		t.Errorf("logs = %s, want the empty nights logged and no error", logs)
+	}
+
+	r.runUntil(at(2026, 10, 19, 9, 15))
+	wantKeys(t, "next Monday", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-19"})
+	p.wantReminder("day_of_reminder:start:2026-10-19", "Start the crock pot by 9:30 am", "Beef Chili", "Beef Chili")
+}
+
+// TestDayOfReminderFollowsReminderTimeWithoutRestart: a reminder_time
+// change takes effect in the running scheduler. Moved from 16:30 to 18:00,
+// the daily reminder fires at 18:00, not 16:30, and a crock-pot start_by
+// of 17:00, now earlier than reminder_time, gets its start reminder at
+// 16:45.
+func TestDayOfReminderFollowsReminderTimeWithoutRestart(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	p.crockPot("Beef Chili", 30) // start by 17:00
+	p.planWeek(w42)
+
+	r := e.start(at(2026, 10, 12, 8, 0), p.svc.ReminderSchedules()...)
+	e.update(household.SettingsPatch{ReminderTime: ptr("18:00")})
+	r.changed()
+	r.runUntil(at(2026, 10, 12, 16, 44))
+	wantKeys(t, "before 16:45", e.reminderKeys(), nil)
+	r.runUntil(at(2026, 10, 12, 16, 45))
+	wantKeys(t, "at 16:45", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12"})
+	p.wantReminder("day_of_reminder:start:2026-10-12", "Start the crock pot by 5:00 pm", "Beef Chili", "Beef Chili")
+	r.runUntil(at(2026, 10, 12, 17, 59))
+	wantKeys(t, "before 18:00", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12"})
+	r.runUntil(at(2026, 10, 12, 18, 0))
+	wantKeys(t, "at 18:00", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12", "day_of_reminder:2026-10-12"})
+}
+
+// TestDayOfReminderNoDuplicateAfterRestart: restarts after each reminder
+// of a crock-pot night, within the catch-up window, emit neither again:
+// each period is already claimed.
+func TestDayOfReminderNoDuplicateAfterRestart(t *testing.T) {
+	e := newEnv(t)
+	ids := e.pool()
+	p := e.plans(ids)
+	p.crockPot("Beef Chili", 480)
+	p.planWeek(w42)
+
+	r := e.start(at(2026, 10, 12, 8, 0), p.svc.ReminderSchedules()...)
+	r.runUntil(at(2026, 10, 12, 9, 15))
+	r.stop()
+	p.stop()
+
+	p2 := e.plans(ids)
+	r2 := e.start(at(2026, 10, 12, 9, 20), p2.svc.ReminderSchedules()...)
+	wantKeys(t, "after the first restart", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12"})
+	r2.runUntil(at(2026, 10, 12, 16, 30))
+	r2.stop()
+	p2.stop()
+
+	p3 := e.plans(ids)
+	r3 := e.start(at(2026, 10, 12, 16, 40), p3.svc.ReminderSchedules()...)
+	r3.runUntil(at(2026, 10, 13, 9, 0))
+	wantKeys(t, "after the second restart", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12", "day_of_reminder:2026-10-12"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder), []string{"2026-10-11", "2026-10-12", "start:2026-10-12"})
+}
+
+// TestDailyAtLookupFailureIsRetried: a DailyAt rule fires at the instant
+// its lookup gives, its period keyed by the schedule's Key and the date;
+// a lookup that fails fires nothing and is looked up again after
+// ClaimRetry, then fires its period once.
+func TestDailyAtLookupFailureIsRetried(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	var mu sync.Mutex
+	failing := false
+	at915 := func(ctx context.Context, d store.LocalDate) (time.Time, bool, error) {
+		mu.Lock()
+		defer mu.Unlock()
+		if failing {
+			return time.Time{}, false, errors.New("database down")
+		}
+		y, m, day := d.Date()
+		return at(y, m, day, 9, 15), true, nil
+	}
+	sch := scheduler.Schedule{
+		Name: scheduler.DayOfReminder,
+		Key:  "start",
+		Rule: func(household.Settings) scheduler.Rule { return scheduler.DailyAt(at915) },
+		Run:  rec.run,
+	}
+
+	r := e.start(at(2026, 10, 12, 8, 0), sch)
+	wantKeys(t, "catch-up", rec.keys(), []string{"start:2026-10-11"})
+	mu.Lock()
+	failing = true
+	mu.Unlock()
+	r.runUntil(at(2026, 10, 12, 9, 16))
+	wantKeys(t, "while the lookup fails", rec.keys(), []string{"start:2026-10-11"})
+
+	mu.Lock()
+	failing = false
+	mu.Unlock()
+	r.runUntil(at(2026, 10, 12, 9, 17))
+	wantKeys(t, "after the lookup recovers", rec.keys(), []string{"start:2026-10-11", "start:2026-10-12"})
+	if p := rec.periods()[1]; !p.FireAt.Equal(at(2026, 10, 12, 9, 15)) || p.Date.String() != "2026-10-12" {
+		t.Errorf("period = %+v, want fired at 09:15 for 2026-10-12", p)
+	}
+	r.runUntil(at(2026, 10, 13, 12, 0))
+	wantKeys(t, "next day", rec.keys(), []string{"start:2026-10-11", "start:2026-10-12", "start:2026-10-13"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder), rec.keys())
+}
+
+// questLog stores name as a Quest-log dinner, a crock-pot dinner of
+// minutes, and returns its id. It is not a Regular.
+func (p *planEnv) questLog(name string, minutes int) string {
+	p.e.t.Helper()
+	now := store.Now().String()
+	d, err := db.New(p.e.st.Writer).CreateDinner(context.Background(), db.CreateDinnerParams{
+		ID:              store.NewID(),
+		Name:            name,
+		NormalizedName:  harness.Normalize(name),
+		Status:          "quest_log",
+		Origin:          "side_quest",
+		GroundingStatus: "manual",
+		CreatedAt:       now,
+		UpdatedAt:       now,
+	})
+	if err != nil {
+		p.e.t.Fatal(err)
+	}
+	p.ids[name] = d.ID
+	p.crockPot(name, minutes)
+	return d.ID
+}
+
+// TestStartReminderAfterSwapFiresOnTime: swapping a crock-pot dinner in
+// for tonight wakes the scheduler, so its start reminder fires at start_by
+// minus 15 minutes, 09:15, and not at the next hourly check, 10:00. At
+// 09:00 tonight is Beef Chili, not a crock-pot dinner, and the scheduler's
+// next timer is 10:00; at 09:01 the household swaps in an eight-hour
+// crock-pot Quest-log dinner, start by 09:30. Each reminder fires once.
+func TestStartReminderAfterSwapFiresOnTime(t *testing.T) {
+	e := newEnv(t)
+	p := e.wakingPlans(e.pool())
+	stew := p.questLog("Crock Pot Stew", 480) // start by 09:30
+	p.planWeek(w42)
+
+	r := e.start(at(2026, 10, 12, 8, 0), p.svc.ReminderSchedules()...)
+	r.runUntil(at(2026, 10, 12, 9, 0))
+	if next, _ := r.clock.nextDeadline(); !next.Equal(at(2026, 10, 12, 10, 0)) {
+		t.Fatalf("next wake at 09:00 = %s, want the hourly 10:00", next)
+	}
+
+	r.runUntil(at(2026, 10, 12, 9, 1))
+	if _, err := p.svc.Swap(context.Background(), w42, "2026-10-12", stew); err != nil {
+		t.Fatal(err)
+	}
+	r.changed()
+	r.runUntil(at(2026, 10, 12, 9, 14))
+	wantKeys(t, "before 09:15", e.reminderKeys(), nil)
+
+	r.runUntil(at(2026, 10, 12, 9, 15))
+	wantKeys(t, "at 09:15", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12"})
+	p.wantReminder("day_of_reminder:start:2026-10-12", "Start the crock pot by 9:30 am", "Crock Pot Stew", "Crock Pot Stew")
+
+	r.runUntil(at(2026, 10, 13, 23, 59))
+	wantKeys(t, "Tuesday", e.reminderKeys(), []string{"day_of_reminder:start:2026-10-12", "day_of_reminder:2026-10-12", "day_of_reminder:2026-10-13"})
+	p.wantReminder("day_of_reminder:2026-10-12", "Tonight: Crock Pot Stew · Recipe →", "", "Crock Pot Stew")
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder), []string{"2026-10-11", "2026-10-12", "2026-10-13", "start:2026-10-12"})
+}

internal/scheduler/export_test.go

@@ -0,0 +1,9 @@
+package scheduler
+
+import "time"
+
+// SetClock makes now the clock and after the timer s fires by.
+func SetClock(s *Scheduler, now func() time.Time, after func(time.Duration) <-chan time.Time) {
+	s.now = now
+	s.after = after
+}

internal/scheduler/plan_draft_test.go

@@ -0,0 +1,409 @@
+package scheduler_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/url"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/gcal"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify/notifytest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/plan"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// The tests in this file run plan's plan_draft schedule on the fake clock
+// against the real plan service, job runner, harness, draft_week and
+// notification outbox, with the AI faked.
+
+// planEnv is a plan service over a scheduler env's store, the "process" a
+// scheduler runs it in. model answers draft_week.
+type planEnv struct {
+	e     *env
+	svc   *plan.Service
+	model *llm.Fake
+	ids   map[string]string
+	logs  *syncBuffer
+	stop  func()
+}
+
+// poolNames are the seven Regulars pool stores, enough for a week.
+var poolNames = []string{"Beef Chili", "Pot Roast", "Chicken Fajitas", "Spaghetti Bolognese", "Sheet Pan Salmon", "Tacos", "Pancakes"}
+
+// pool stores poolNames as Regulars and returns their ids by name.
+func (e *env) pool() map[string]string {
+	e.t.Helper()
+	ids := map[string]string{}
+	for _, name := range poolNames {
+		now := store.Now().String()
+		d, err := db.New(e.st.Writer).CreateDinner(context.Background(), db.CreateDinnerParams{
+			ID:              store.NewID(),
+			Name:            name,
+			NormalizedName:  harness.Normalize(name),
+			Status:          "regular",
+			Origin:          "regular",
+			GroundingStatus: "manual",
+			CreatedAt:       now,
+			UpdatedAt:       now,
+		})
+		if err != nil {
+			e.t.Fatal(err)
+		}
+		ids[name] = d.ID
+	}
+	return ids
+}
+
+// publicURL is MEALQUEST_PUBLIC_URL in these tests.
+var publicURL = &url.URL{Scheme: "https", Host: "meals.example.com"}
+
+// noCalendar is a Calendar the schedule must never push to.
+type noCalendar struct{ t *testing.T }
+
+func (c noCalendar) PushEvents(context.Context, []gcal.Event, func() error) error {
+	c.t.Error("plan_draft pushed to Calendar")
+	return errors.New("no calendar")
+}
+
+// plans builds a plan service drafting from the dinners ids over e with a
+// started job runner, which stop stops (and the test's end, if not before).
+// Its changes do not wake the scheduler: a draft job's wake would add a
+// pass the fake clock's waits do not expect.
+func (e *env) plans(ids map[string]string) *planEnv {
+	e.t.Helper()
+	return e.newPlans(ids, func() {})
+}
+
+// wakingPlans is plans whose changes wake the scheduler, as in the server.
+// A test using it changes plans only from its own goroutine and waits for
+// the wake's pass with changed.
+func (e *env) wakingPlans(ids map[string]string) *planEnv {
+	e.t.Helper()
+	return e.newPlans(ids, e.wake)
+}
+
+// newPlans is plans whose service calls wake after a plan change.
+func (e *env) newPlans(ids map[string]string, wake func()) *planEnv {
+	e.t.Helper()
+	p := &planEnv{e: e, model: &llm.Fake{}, ids: ids, logs: &syncBuffer{}}
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	cfg := harness.Config{
+		Settings:    llm.Settings{Provider: "anthropic", Model: "claude-test", Temperature: 0.7},
+		NewProvider: func(llm.Settings, string) (llm.Provider, error) { return p.model, nil },
+		Store:       e.st,
+		Guard:       guard,
+	}
+	drafter := func(ctx context.Context, scope string, in skills.WeekRequest) (skills.Week, error) {
+		return skills.DraftWeek(ctx, cfg, scope, in)
+	}
+	logger := slog.New(slog.NewTextHandler(p.logs, nil))
+	runner, err := jobs.NewRunner(e.st, logger, 1)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	p.svc, err = plan.NewService(e.st, drafter, runner, noCalendar{e.t}, notifytest.New(e.t, e.st), wake, publicURL, logger)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := runner.Start(ctx); err != nil {
+		cancel()
+		e.t.Fatal(err)
+	}
+	var once sync.Once
+	p.stop = func() {
+		once.Do(func() {
+			cancel()
+			runner.Wait()
+		})
+	}
+	e.t.Cleanup(p.stop)
+	return p
+}
+
+// reply scripts the next draft_week answer: poolNames on the days of the
+// week starting weekStart, Monday to Sunday.
+func (p *planEnv) reply(weekStart store.LocalDate) {
+	p.e.t.Helper()
+	dates, err := household.WeekDays(weekStart)
+	if err != nil {
+		p.e.t.Fatal(err)
+	}
+	var days []string
+	for i, name := range poolNames {
+		days = append(days, fmt.Sprintf(`{"date":%q,"dinner_id":%q}`, dates[i], p.ids[name]))
+	}
+	js := fmt.Sprintf(`{"days":[%s],"note":""}`, strings.Join(days, ","))
+	p.model.QueueGenerate(llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}})
+}
+
+// draftJob is a draft_week jobs row.
+type draftJob struct {
+	Status, Error string
+}
+
+// drafts waits until no draft_week job is queued or running and returns
+// them all, oldest first.
+func (e *env) drafts() []draftJob {
+	e.t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		rows, err := e.st.Reader.Query(`SELECT status, COALESCE(error, '') FROM jobs WHERE kind = ? ORDER BY created_at, id`, plan.KindDraftWeek)
+		if err != nil {
+			e.t.Fatal(err)
+		}
+		var out []draftJob
+		busy := false
+		for rows.Next() {
+			var j draftJob
+			if err := rows.Scan(&j.Status, &j.Error); err != nil {
+				e.t.Fatal(err)
+			}
+			busy = busy || j.Status == string(jobs.StatusQueued) || j.Status == string(jobs.StatusRunning)
+			out = append(out, j)
+		}
+		if err := rows.Err(); err != nil {
+			e.t.Fatal(err)
+		}
+		rows.Close()
+		if !busy {
+			return out
+		}
+		if time.Now().After(deadline) {
+			e.t.Fatalf("draft jobs still under way: %+v", out)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+// wantDrafts fails unless the draft_week jobs are got.
+func wantDrafts(t *testing.T, what string, got []draftJob, want ...draftJob) {
+	t.Helper()
+	if fmt.Sprint(got) != fmt.Sprint(want) {
+		t.Fatalf("%s: draft jobs = %+v, want %+v", what, got, want)
+	}
+}
+
+// weekPlans returns the week_start of every plan, oldest first.
+func (e *env) weekPlans() []string {
+	e.t.Helper()
+	rows, err := e.st.Reader.Query(`SELECT week_start FROM week_plans ORDER BY week_start`)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	defer rows.Close()
+	var out []string
+	for rows.Next() {
+		var w string
+		if err := rows.Scan(&w); err != nil {
+			e.t.Fatal(err)
+		}
+		out = append(out, w)
+	}
+	if err := rows.Err(); err != nil {
+		e.t.Fatal(err)
+	}
+	return out
+}
+
+// planReady returns the distinct plan_ready keys stored, oldest first.
+func (e *env) planReady() []string {
+	e.t.Helper()
+	var keys []string
+	for _, r := range notifytest.Rows(e.t, e.st, notify.PlanReady) {
+		if len(keys) == 0 || keys[len(keys)-1] != r.Key {
+			keys = append(keys, r.Key)
+		}
+	}
+	return keys
+}
+
+var (
+	succeeded = draftJob{Status: string(jobs.StatusSucceeded)}
+	aiFailed  = draftJob{Status: string(jobs.StatusFailed), Error: plan.ReasonAIFailed}
+	// w43 is the Monday of 2026-W43, the week after Friday Oct 16.
+	w43 = mustLocalDate("2026-10-19")
+	w44 = mustLocalDate("2026-10-26")
+)
+
+func mustLocalDate(s string) store.LocalDate {
+	d, err := store.ParseLocalDate(s)
+	if err != nil {
+		panic(err)
+	}
+	return d
+}
+
+// TestPlanDraftDraftsNextWeek: at the seeded Friday 09:00 the schedule
+// drafts the next ISO week through the plan service's draft job, period
+// plan_draft:YYYY-Www of that week, and the draft emits plan_ready keyed
+// by its Monday once.
+func TestPlanDraftDraftsNextWeek(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	p.reply(w43)
+	p.reply(w44)
+
+	// Wednesday Oct 14: the Friday Oct 9 09:00 fire is days ago, missed.
+	r := e.start(at(2026, 10, 14, 12, 0), p.svc.DraftSchedule())
+	r.runUntil(at(2026, 10, 16, 8, 59))
+	wantDrafts(t, "before Friday 09:00", e.drafts())
+	wantKeys(t, "plans before Friday 09:00", e.weekPlans(), nil)
+
+	r.runUntil(at(2026, 10, 16, 9, 0))
+	wantDrafts(t, "at Friday 09:00", e.drafts(), succeeded)
+	wantKeys(t, "plans at Friday 09:00", e.weekPlans(), []string{"2026-10-19"})
+	wantKeys(t, "plan_ready of W43", e.planReady(), []string{"plan_ready:2026-10-19"})
+	got, err := p.svc.Get(context.Background(), w43)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Days) != 7 || got.Days[0].Dinner.Name != "Beef Chili" || got.Status != plan.StatusDraft {
+		t.Errorf("plan of W43 = %+v, want the drafted week", got)
+	}
+
+	r.runUntil(at(2026, 10, 23, 9, 0))
+	wantDrafts(t, "W44", e.drafts(), succeeded, succeeded)
+	wantKeys(t, "plans", e.weekPlans(), []string{"2026-10-19", "2026-10-26"})
+	wantKeys(t, "plan_ready of W43 and W44", e.planReady(), []string{"plan_ready:2026-10-19", "plan_ready:2026-10-26"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.PlanDraft), []string{"2026-W42", "2026-W43", "2026-W44"})
+}
+
+// TestPlanDraftLeavesAnExistingPlan: when next week already has a plan,
+// here one the household drafted by hand, the period drafts nothing,
+// notifies no one and says so.
+func TestPlanDraftLeavesAnExistingPlan(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	p.reply(w43)
+	p.reply(w43) // a second draft would succeed too
+	if _, err := p.svc.StartDraft(context.Background(), w43, false); err != nil {
+		t.Fatal(err)
+	}
+	wantDrafts(t, "manual draft", e.drafts(), succeeded)
+	wantKeys(t, "plan_ready of the manual draft", e.planReady(), []string{"plan_ready:2026-10-19"})
+	before, err := p.svc.Get(context.Background(), w43)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	r := e.start(at(2026, 10, 16, 8, 0), p.svc.DraftSchedule())
+	r.runUntil(at(2026, 10, 16, 9, 0))
+	wantDrafts(t, "with a plan", e.drafts(), succeeded)
+	wantKeys(t, "plan_ready with a plan", e.planReady(), []string{"plan_ready:2026-10-19"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.PlanDraft), []string{"2026-W42", "2026-W43"})
+	after, err := p.svc.Get(context.Background(), w43)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fmt.Sprint(after) != fmt.Sprint(before) {
+		t.Errorf("plan of W43 = %+v, want it unchanged from %+v", after, before)
+	}
+	if logs := p.logs.String(); !strings.Contains(logs, "the week already has a plan") || !strings.Contains(logs, "period=2026-W43") {
+		t.Errorf("logs = %s, want the skipped period logged", logs)
+	}
+}
+
+// TestPlanDraftNoDuplicateAfterRestart: a restart after the week was
+// drafted, still within the catch-up window, drafts nothing more and sends
+// no second plan_ready: the period is already claimed.
+func TestPlanDraftNoDuplicateAfterRestart(t *testing.T) {
+	e := newEnv(t)
+	ids := e.pool()
+	p := e.plans(ids)
+	p.reply(w43)
+	r := e.start(at(2026, 10, 16, 8, 0), p.svc.DraftSchedule())
+	r.runUntil(at(2026, 10, 16, 9, 0))
+	wantDrafts(t, "first process", e.drafts(), succeeded)
+	r.stop()
+	p.stop()
+
+	// The restarted process has a new job runner, plan service and
+	// scheduler; it would answer a second draft if one were started.
+	p2 := e.plans(ids)
+	p2.reply(w43)
+	r2 := e.start(at(2026, 10, 16, 10, 0), p2.svc.DraftSchedule())
+	r2.runUntil(at(2026, 10, 23, 8, 59))
+	wantDrafts(t, "after restart", e.drafts(), succeeded)
+	wantKeys(t, "plans after restart", e.weekPlans(), []string{"2026-10-19"})
+	wantKeys(t, "plan_ready after restart", e.planReady(), []string{"plan_ready:2026-10-19"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.PlanDraft), []string{"2026-W42", "2026-W43"})
+}
+
+// TestPlanDraftAIFailureEmitsNothing: when draft_week fails the draft job
+// fails as ai_failed with the failure recorded in ai_runs, no plan is made
+// up and no one is notified; a restart within the catch-up window does not
+// draft the claimed period again.
+func TestPlanDraftAIFailureEmitsNothing(t *testing.T) {
+	e := newEnv(t)
+	ids := e.pool()
+	p := e.plans(ids)
+	p.model.QueueGenerate(llm.GenerateResult{Err: errors.New("provider down")})
+
+	r := e.start(at(2026, 10, 16, 8, 0), p.svc.DraftSchedule())
+	r.runUntil(at(2026, 10, 16, 9, 0))
+	wantDrafts(t, "after the AI failed", e.drafts(), aiFailed)
+	wantKeys(t, "plans after the AI failed", e.weekPlans(), nil)
+	wantKeys(t, "plan_ready after the AI failed", e.planReady(), nil)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.PlanDraft), []string{"2026-W42", "2026-W43"})
+
+	var status, msg string
+	if err := e.st.Reader.QueryRow(`SELECT status, COALESCE(error, '') FROM ai_runs WHERE skill = 'draft_week'`).Scan(&status, &msg); err != nil {
+		t.Fatalf("ai_runs row of draft_week: %v", err)
+	}
+	if status != string(harness.StatusProviderError) || msg == "" {
+		t.Errorf("ai_runs draft_week = %s %q, want %s with its message", status, msg, harness.StatusProviderError)
+	}
+	if logs := p.logs.String(); !strings.Contains(logs, "week draft failed") || !strings.Contains(logs, "reason="+plan.ReasonAIFailed) {
+		t.Errorf("logs = %s, want the draft failure with reason %s", logs, plan.ReasonAIFailed)
+	}
+
+	r.stop()
+	p.stop()
+	p2 := e.plans(ids)
+	p2.reply(w43)
+	e.start(at(2026, 10, 16, 10, 0), p2.svc.DraftSchedule())
+	wantDrafts(t, "after restart", e.drafts(), aiFailed)
+	wantKeys(t, "plan_ready after restart", e.planReady(), nil)
+}
+
+// TestPlanDraftFollowsSettingsWithoutRestart: a plan_draft_dow and
+// plan_draft_time change takes effect in the running scheduler; the old
+// Friday 09:00 no longer fires and the new Wednesday 18:30 drafts the next
+// week.
+func TestPlanDraftFollowsSettingsWithoutRestart(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	p.reply(w43)
+
+	r := e.start(at(2026, 10, 12, 12, 0), p.svc.DraftSchedule()) // Monday
+	e.update(household.SettingsPatch{PlanDraftDow: ptr(3), PlanDraftTime: ptr("18:30")})
+	r.changed()
+	r.runUntil(at(2026, 10, 14, 18, 29)) // Wednesday
+	wantDrafts(t, "before Wednesday 18:30", e.drafts())
+	r.runUntil(at(2026, 10, 14, 18, 30))
+	wantDrafts(t, "at Wednesday 18:30", e.drafts(), succeeded)
+	wantKeys(t, "plan_ready", e.planReady(), []string{"plan_ready:2026-10-19"})
+
+	// Friday 09:00, the old fire time, drafts nothing more.
+	r.runUntil(at(2026, 10, 16, 9, 0))
+	wantDrafts(t, "at Friday 09:00", e.drafts(), succeeded)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.PlanDraft), []string{"2026-W42", "2026-W43"})
+}

internal/scheduler/rotation_check_test.go

@@ -0,0 +1,204 @@
+package scheduler_test
+
+import (
+	"context"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify/notifytest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+)
+
+// The tests in this file run plan's rotation_check schedule on the fake
+// clock against the real plan service and notification outbox. The plan of
+// the week of Monday Oct 12 (w42) has poolNames, all Regulars, Monday to
+// Sunday; a test that needs a Quest-log dinner swaps Lemon Orzo in for
+// Monday. The household's review time is the seeded 09:00, in Chicago.
+
+// orzoDay is the Monday Lemon Orzo is planned on.
+var orzoDay = mustLocalDate("2026-10-12")
+
+// orzoWeek plans w42 with the Quest-log dinner Lemon Orzo on Monday in
+// place of Beef Chili, and returns its id.
+func (p *planEnv) orzoWeek() string {
+	p.e.t.Helper()
+	id := p.questLog("Lemon Orzo", 30)
+	p.planWeek(w42)
+	if _, err := p.svc.Swap(context.Background(), w42, orzoDay.String(), id); err != nil {
+		p.e.t.Fatal(err)
+	}
+	return id
+}
+
+// rotationReviews returns the keys of the rotation_review notifications
+// stored, oldest first. The seeded preference sends rotation_review to push
+// only, so there is one row per event.
+func (e *env) rotationReviews() []string {
+	e.t.Helper()
+	var keys []string
+	for _, r := range notifytest.Rows(e.t, e.st, notify.RotationReview) {
+		if r.Channel != notify.ChannelPush {
+			e.t.Fatalf("rotation_review row %+v, want push only", r)
+		}
+		keys = append(keys, r.Key)
+	}
+	return keys
+}
+
+// status returns the status of the dinner name.
+func (p *planEnv) status(name string) string {
+	p.e.t.Helper()
+	var s string
+	if err := p.e.st.Reader.QueryRow(`SELECT status FROM dinners WHERE id = ?`, p.ids[name]).Scan(&s); err != nil {
+		p.e.t.Fatal(err)
+	}
+	return s
+}
+
+// pendingReviews returns the plan dates of the pending Rotation checks of
+// the dinner name.
+func (p *planEnv) pendingReviews(name string) []string {
+	p.e.t.Helper()
+	rows, err := p.e.st.Reader.Query(`SELECT plan_date FROM rotation_reviews WHERE dinner_id = ? AND status = 'pending' ORDER BY plan_date`, p.ids[name])
+	if err != nil {
+		p.e.t.Fatal(err)
+	}
+	defer rows.Close()
+	var out []string
+	for rows.Next() {
+		var d string
+		if err := rows.Scan(&d); err != nil {
+			p.e.t.Fatal(err)
+		}
+		out = append(out, d)
+	}
+	if err := rows.Err(); err != nil {
+		p.e.t.Fatal(err)
+	}
+	return out
+}
+
+// wantOrzoTried fails unless Lemon Orzo, id, is tried with one pending
+// Rotation check for orzoDay and exactly one rotation_review asking about
+// it, which opens Home.
+func (p *planEnv) wantOrzoTried(id string) {
+	p.e.t.Helper()
+	if got := p.status("Lemon Orzo"); got != "tried" {
+		p.e.t.Errorf("Lemon Orzo status = %s, want tried", got)
+	}
+	wantKeys(p.e.t, "Lemon Orzo pending Rotation checks", p.pendingReviews("Lemon Orzo"), []string{orzoDay.String()})
+	key := "rotation_review:" + id + ":" + orzoDay.String()
+	wantKeys(p.e.t, "rotation_review", p.e.rotationReviews(), []string{key})
+	got := notifytest.Rows(p.e.t, p.e.st, notify.RotationReview)[0].Payload
+	want := notify.Payload{Event: notify.RotationReview, Title: "How was Lemon Orzo? Keep it in rotation?", URL: "/", Tag: key, Week: w42.String()}
+	if got != want {
+		p.e.t.Errorf("rotation_review = %+v, want %+v", got, want)
+	}
+}
+
+// TestRotationCheckMarksQuestLogDinnerTried: at review_time 09:00 the day
+// after a Quest-log dinner was planned, the schedule, period
+// rotation_check:YYYY-MM-DD, marks it tried, opens its Rotation check and
+// emits one rotation_review. It never makes the dinner a Regular.
+func TestRotationCheckMarksQuestLogDinnerTried(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	id := p.orzoWeek()
+
+	// Tuesday 08:00: the catch-up of Monday 09:00 checks Sunday, unplanned.
+	r := e.start(at(2026, 10, 13, 8, 0), p.svc.RotationCheckSchedule())
+	r.runUntil(at(2026, 10, 13, 8, 59))
+	wantKeys(t, "before 09:00", e.rotationReviews(), nil)
+	if got := p.status("Lemon Orzo"); got != "quest_log" {
+		t.Fatalf("Lemon Orzo status before 09:00 = %s, want quest_log", got)
+	}
+
+	r.runUntil(at(2026, 10, 13, 9, 0))
+	p.wantOrzoTried(id)
+
+	// Days later, still tried: only the household's keep makes a Regular.
+	r.runUntil(at(2026, 10, 16, 12, 0))
+	p.wantOrzoTried(id)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.RotationCheck), []string{
+		"rotation_check:2026-10-12", "rotation_check:2026-10-13", "rotation_check:2026-10-14",
+		"rotation_check:2026-10-15", "rotation_check:2026-10-16",
+	})
+}
+
+// TestRotationCheckLeavesRegulars: a day planning only Regulars marks
+// nothing tried, opens no Rotation check and emits nothing.
+func TestRotationCheckLeavesRegulars(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	p.planWeek(w42)
+
+	r := e.start(at(2026, 10, 13, 8, 0), p.svc.RotationCheckSchedule())
+	r.runUntil(at(2026, 10, 13, 9, 0))
+	wantKeys(t, "rotation_review", e.rotationReviews(), nil)
+	if got := p.status("Beef Chili"); got != "regular" {
+		t.Errorf("Beef Chili status = %s, want regular", got)
+	}
+	wantKeys(t, "Beef Chili pending Rotation checks", p.pendingReviews("Beef Chili"), nil)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.RotationCheck), []string{"rotation_check:2026-10-12", "rotation_check:2026-10-13"})
+}
+
+// TestRotationCheckNoDuplicateSameDay: a restart the same day finds the
+// period claimed, and MarkTried run again for the same day finds the
+// Rotation check open, so neither opens a second check or notification.
+func TestRotationCheckNoDuplicateSameDay(t *testing.T) {
+	e := newEnv(t)
+	ids := e.pool()
+	p := e.plans(ids)
+	id := p.orzoWeek()
+
+	r := e.start(at(2026, 10, 13, 8, 0), p.svc.RotationCheckSchedule())
+	r.runUntil(at(2026, 10, 13, 9, 0))
+	p.wantOrzoTried(id)
+	r.stop()
+	p.stop()
+
+	p2 := e.plans(ids)
+	r2 := e.start(at(2026, 10, 13, 9, 30), p2.svc.RotationCheckSchedule())
+	r2.runUntil(at(2026, 10, 13, 23, 59))
+	p2.wantOrzoTried(id)
+
+	if n, err := p2.svc.MarkTried(context.Background(), orzoDay); err != nil || n != 0 {
+		t.Fatalf("MarkTried(%s) again = %d, %v, want 0", orzoDay, n, err)
+	}
+	p2.wantOrzoTried(id)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.RotationCheck), []string{"rotation_check:2026-10-12", "rotation_check:2026-10-13"})
+}
+
+// TestRotationCheckCatchUpAtBoot: started 23 hours after a missed 09:00,
+// the scheduler runs that day's Rotation check once at boot.
+func TestRotationCheckCatchUpAtBoot(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	id := p.orzoWeek()
+
+	e.start(at(2026, 10, 14, 8, 0), p.svc.RotationCheckSchedule())
+	p.wantOrzoTried(id)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.RotationCheck), []string{"rotation_check:2026-10-13"})
+}
+
+// TestRotationCheckFollowsReviewTimeWithoutRestart: a review_time change
+// takes effect in the running scheduler. Moved from 09:00 to 10:30, the
+// Rotation check does not run at 09:00 and runs at 10:30.
+func TestRotationCheckFollowsReviewTimeWithoutRestart(t *testing.T) {
+	e := newEnv(t)
+	p := e.plans(e.pool())
+	id := p.orzoWeek()
+
+	r := e.start(at(2026, 10, 13, 8, 0), p.svc.RotationCheckSchedule())
+	e.update(household.SettingsPatch{ReviewTime: ptr("10:30")})
+	r.changed()
+	r.runUntil(at(2026, 10, 13, 10, 29))
+	wantKeys(t, "before 10:30", e.rotationReviews(), nil)
+	if got := p.status("Lemon Orzo"); got != "quest_log" {
+		t.Fatalf("Lemon Orzo status before 10:30 = %s, want quest_log", got)
+	}
+	r.runUntil(at(2026, 10, 13, 10, 30))
+	p.wantOrzoTried(id)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.RotationCheck), []string{"rotation_check:2026-10-12", "rotation_check:2026-10-13"})
+}

internal/scheduler/scheduler.go

@@ -0,0 +1,746 @@
+// Package scheduler runs the household's timed work: each registered
+// schedule fires once per period at a household-local time read from the
+// household settings.
+//
+// # Periods and the claim
+//
+// Every fire time belongs to one period, named by a period key derived in
+// the household zone from the schedule's cadence (see Rule.PeriodKey): the
+// local date "2026-10-09" for a daily rule, and the ISO week "2026-W41" of
+// the fire date, or of the week after it, for a weekly rule. Before running,
+// the scheduler inserts schedule_runs(schedule, period_key); the insert is
+// the claim, and a period already claimed, by an earlier run, an earlier
+// process or another instance, is skipped. A period therefore runs at most
+// once: a Run that fails is logged and its period is not retried.
+//
+// # Catch-up
+//
+// When the scheduler starts, and whenever it wakes late, it handles, oldest
+// first, every fire time of each schedule that passed within CatchUpWindow,
+// and the most recent fire time even when it passed longer ago. Each
+// unclaimed period within CatchUpWindow runs once. A most recent one that
+// passed longer ago is claimed without running and logged as missed, so it
+// can never run later, not after a restart and not after a settings change
+// moves the fire time. Other fire times older than CatchUpWindow are never
+// looked at.
+//
+// # Claim failures
+//
+// A claim that fails (the database refused the insert) is never skipped:
+// the scheduler logs it and keeps that period's fire time, and every
+// ClaimRetry claims that same period again until the claim succeeds. Only
+// then does it apply the catch-up rule to it, running it if its fire time
+// is within CatchUpWindow of the successful claim and recording it as
+// missed otherwise, and only then does it go on to later fire times, even
+// when one has passed meanwhile. Each period is claimed by its own fire
+// time, so the later period runs once as well.
+//
+// # Time zone and DST
+//
+// Fire times are wall-clock times in the household zone, never the process
+// zone, turned into instants by household.LocalTime. Its rule is the
+// scheduler's DST rule: a time that does not exist on a spring-forward day
+// fires later by the length of the gap (02:30 fires at 03:30 local), and a
+// time that occurs twice on a fall-back day fires once, at its first
+// occurrence. Either way the period key is that local date's, so the
+// period still runs exactly once.
+//
+// # Fire times from data
+//
+// A DailyAt rule fires at a time read from the household's data rather
+// than the settings: its function gives, for each household-local date,
+// the instant the date's period fires, or none. The period is that date
+// even when the instant falls on another day. The scheduler asks again on
+// every pass, and whoever changes that data calls Wake once the change is
+// committed, so the next pass comes at once and a fire time the change
+// moved fires on time rather than up to maxWait late; the claim still runs
+// a period at most once. A lookup that fails is logged and repeated every
+// ClaimRetry, as a failed claim is.
+//
+// # Settings changes
+//
+// The scheduler subscribes to the household settings and records each change
+// with the instant it was saved. A change takes effect at once without a
+// restart: fire times up to that instant follow the old settings and later
+// ones the new, even when the scheduler gets to the change late. So moving
+// a fire time to earlier the same day does not fire the passed time, and a
+// new fire time that was still ahead when the change was saved fires.
+package scheduler
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// Schedule names, as the schedule_runs.schedule CHECK constraint allows.
+const (
+	SuggestionsWeekly    = "suggestions_weekly"
+	PlanDraft            = "plan_draft"
+	ShoppingChatAutosend = "shopping_chat_autosend"
+	DayOfReminder        = "day_of_reminder"
+	RotationCheck        = "rotation_check"
+	WeekRollover         = "week_rollover"
+	AIRunsPurge          = "ai_runs_purge"
+)
+
+// names are the schedule names Register accepts.
+var names = map[string]bool{
+	SuggestionsWeekly:    true,
+	PlanDraft:            true,
+	ShoppingChatAutosend: true,
+	DayOfReminder:        true,
+	RotationCheck:        true,
+	WeekRollover:         true,
+	AIRunsPurge:          true,
+}
+
+// CatchUpWindow is how long after its fire time a period that has not run
+// still runs. A period found later than that is recorded as missed.
+const CatchUpWindow = 24 * time.Hour
+
+// ClaimRetry is how long the scheduler waits before repeating a pass in
+// which a claim failed.
+const ClaimRetry = time.Minute
+
+// maxWait bounds one sleep, so the scheduler checks the wall clock at least
+// this often even if the host was suspended or its clock stepped.
+const maxWait = time.Hour
+
+// Rule is when a schedule fires: at household-local Time ("HH:MM") every
+// day, or on Weekday only when Weekly is set, or every day at the instant
+// At gives. Build one with Daily, Weekly, WeeklyForNextWeek or DailyAt.
+type Rule struct {
+	Weekly  bool
+	Weekday time.Weekday
+	Time    string
+	// NextWeek keys a weekly period by the ISO week after the fire date,
+	// for work done ahead for the coming week.
+	NextWeek bool
+	// At, instead of Time, gives the instant the period of a
+	// household-local date fires.
+	At FireAt
+}
+
+// FireAt gives the instant the period of household-local date fires, or
+// false when that date's period does not fire.
+type FireAt func(ctx context.Context, date store.LocalDate) (time.Time, bool, error)
+
+// Daily fires every day at hhmm; its period is the local date.
+func Daily(hhmm string) Rule {
+	return Rule{Time: hhmm}
+}
+
+// Weekly fires on day at hhmm; its period is the ISO week of the fire date.
+func Weekly(day time.Weekday, hhmm string) Rule {
+	return Rule{Weekly: true, Weekday: day, Time: hhmm}
+}
+
+// WeeklyForNextWeek fires on day at hhmm; its period is the ISO week after
+// the fire date's.
+func WeeklyForNextWeek(day time.Weekday, hhmm string) Rule {
+	return Rule{Weekly: true, Weekday: day, Time: hhmm, NextWeek: true}
+}
+
+// DailyAt fires at most once a day, at the instant at gives for the date;
+// its period is that date, wherever the instant falls.
+func DailyAt(at FireAt) Rule {
+	return Rule{At: at}
+}
+
+// PeriodKey returns the period key of a fire on household-local date
+// fireDate: the date ("2026-10-09") for a daily rule, the ISO week
+// ("2026-W53") for a weekly one, and the ISO week after that ("2027-W01")
+// when NextWeek is set. It panics if fireDate is the zero LocalDate.
+func (r Rule) PeriodKey(fireDate store.LocalDate) string {
+	if !r.Weekly {
+		return fireDate.String()
+	}
+	if r.NextWeek {
+		return household.PeriodKey(addDays(fireDate, 7))
+	}
+	return household.PeriodKey(fireDate)
+}
+
+// validate reports whether r can fire.
+func (r Rule) validate() error {
+	if r.Weekly && (r.Weekday < time.Sunday || r.Weekday > time.Saturday) {
+		return fmt.Errorf("invalid weekday %d (want 0-6, Sunday = 0)", r.Weekday)
+	}
+	if !r.Weekly && (r.Weekday != time.Sunday || r.NextWeek) {
+		return errors.New("a daily rule has no weekday or next week")
+	}
+	if r.At != nil {
+		if r.Weekly || r.Time != "" {
+			return errors.New("a DailyAt rule has no weekday or time")
+		}
+		return nil
+	}
+	// Any date checks the time's form.
+	_, err := household.LocalTime(time.UTC, store.LocalDateOf(time.Unix(0, 0).UTC()), r.Time)
+	return err
+}
+
+// Period is one period of a schedule, as given to its Run.
+type Period struct {
+	// Key is the period key claimed in schedule_runs.
+	Key string
+	// FireAt is the instant the period fired, in the household zone.
+	FireAt time.Time
+	// Date is the household-local date of FireAt.
+	Date store.LocalDate
+	// Week is the ISO Monday of the week Key names; for a daily rule, of
+	// the week containing Date.
+	Week store.LocalDate
+}
+
+// Schedule is registered work that runs once per period.
+type Schedule struct {
+	// Name is one of the schedule name constants.
+	Name string
+	// Key, when set, prefixes the schedule's period keys with Key and a
+	// colon ("start:2026-10-14"), so two schedules of one Name claim
+	// different periods. Name and Key together are unique.
+	Key string
+	// PeriodKey, when set, gives the period key claimed for p in place of
+	// the rule's, such as "list_ready:chat:2026-10-19" for the week p.Week;
+	// p.Key is the rule's key. It must give each period its own key. A
+	// schedule sets Key or PeriodKey, not both.
+	PeriodKey func(p Period) string
+	// Rule returns when the schedule fires under settings. It is called
+	// again after every settings change.
+	Rule func(settings household.Settings) Rule
+	// Run does the period's work. It runs on the scheduler's goroutine,
+	// one schedule at a time, so it must return promptly: long work is
+	// enqueued as a job. ctx is cancelled when the scheduler stops. An
+	// error is logged; the period stays claimed and is not retried.
+	Run func(ctx context.Context, p Period) error
+}
+
+// label names sch in errors and logs: its Name, and its Key if set.
+func (sch Schedule) label() string {
+	if sch.Key == "" {
+		return sch.Name
+	}
+	return sch.Name + ":" + sch.Key
+}
+
+// Settings is the household settings source: *household.SettingsService.
+type Settings interface {
+	Get(ctx context.Context) (household.Settings, error)
+	Subscribe(fn func(household.Settings)) (unsubscribe func())
+}
+
+// Scheduler runs the registered schedules.
+type Scheduler struct {
+	st       *store.Store
+	settings Settings
+	logger   *slog.Logger
+
+	// now is the clock and after the timer; tests replace both.
+	now   func() time.Time
+	after func(d time.Duration) <-chan time.Time
+
+	// wake holds one token when the settings or the data a DailyAt rule
+	// reads changed since the loop last looked; pending is the settings
+	// changes to apply, oldest first.
+	wake      chan struct{}
+	pendingMu sync.Mutex
+	pending   []change
+
+	mu        sync.Mutex
+	schedules []Schedule
+	started   bool
+
+	wg sync.WaitGroup
+}
+
+// New returns a scheduler over st reading the household settings from
+// settings.
+func New(st *store.Store, settings Settings, logger *slog.Logger) (*Scheduler, error) {
+	if st == nil {
+		return nil, errors.New("scheduler: nil store")
+	}
+	if settings == nil {
+		return nil, errors.New("scheduler: nil settings")
+	}
+	if logger == nil {
+		return nil, errors.New("scheduler: nil logger")
+	}
+	return &Scheduler{
+		st:       st,
+		settings: settings,
+		logger:   logger,
+		now:      time.Now,
+		after:    time.After,
+		wake:     make(chan struct{}, 1),
+	}, nil
+}
+
+// Register adds sch. It must be called before Start, once per name.
+func (s *Scheduler) Register(sch Schedule) error {
+	if !names[sch.Name] {
+		return fmt.Errorf("scheduler: register: unknown schedule %q", sch.Name)
+	}
+	if sch.Rule == nil {
+		return fmt.Errorf("scheduler: register %s: nil rule", sch.label())
+	}
+	if sch.Run == nil {
+		return fmt.Errorf("scheduler: register %s: nil run", sch.label())
+	}
+	if strings.Contains(sch.Key, ":") {
+		return fmt.Errorf("scheduler: register %s: key has a colon", sch.label())
+	}
+	if sch.Key != "" && sch.PeriodKey != nil {
+		return fmt.Errorf("scheduler: register %s: both key and period key", sch.label())
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.started {
+		return fmt.Errorf("scheduler: register %s: already started", sch.label())
+	}
+	for _, have := range s.schedules {
+		if have.Name == sch.Name && have.Key == sch.Key {
+			return fmt.Errorf("scheduler: register %s: already registered", sch.label())
+		}
+	}
+	s.schedules = append(s.schedules, sch)
+	return nil
+}
+
+// Start reads the settings and starts the scheduler, which first catches
+// up on each schedule's recent periods and then fires schedules as
+// their times come. Settings whose zone or rules are invalid are an error
+// and nothing starts. The scheduler stops when ctx is cancelled; Wait waits
+// for it.
+func (s *Scheduler) Start(ctx context.Context) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.started {
+		return errors.New("scheduler: already started")
+	}
+	// Subscribing first means a change saved after the read below still
+	// wakes the loop.
+	unsubscribe := s.settings.Subscribe(s.changed)
+	settings, err := s.settings.Get(ctx)
+	if err != nil {
+		unsubscribe()
+		return fmt.Errorf("scheduler: %w", err)
+	}
+	p, err := compile(s.schedules, settings)
+	if err != nil {
+		unsubscribe()
+		return err
+	}
+	s.started = true
+	s.wg.Add(1)
+	go func() {
+		defer s.wg.Done()
+		defer unsubscribe()
+		s.loop(ctx, p)
+	}()
+	return nil
+}
+
+// Wait blocks until the scheduler has stopped.
+func (s *Scheduler) Wait() {
+	s.wg.Wait()
+}
+
+// change is a settings change and the instant it was saved.
+type change struct {
+	at       time.Time
+	settings household.Settings
+}
+
+// changed is the settings subscriber. It runs on the updating goroutine, so
+// it only records the change and wakes the loop.
+func (s *Scheduler) changed(settings household.Settings) {
+	s.pendingMu.Lock()
+	s.pending = append(s.pending, change{at: s.now(), settings: settings})
+	s.pendingMu.Unlock()
+	s.signal()
+}
+
+// Wake makes the scheduler look up its fire times again now rather than at
+// its next timer. Call it after committing a change to the data a DailyAt
+// rule reads, such as tonight's planned dinner. It never blocks.
+func (s *Scheduler) Wake() {
+	s.signal()
+}
+
+// signal leaves one token in wake for the loop.
+func (s *Scheduler) signal() {
+	select {
+	case s.wake <- struct{}{}:
+	default: // the loop already has a token and looks again then
+	}
+}
+
+// takeChanges returns and clears the pending changes.
+func (s *Scheduler) takeChanges() []change {
+	s.pendingMu.Lock()
+	defer s.pendingMu.Unlock()
+	out := s.pending
+	s.pending = nil
+	return out
+}
+
+// plan is the schedules compiled against one version of the settings.
+type plan struct {
+	loc   *time.Location
+	items []item
+}
+
+type item struct {
+	sch  Schedule
+	rule Rule
+}
+
+// compile builds the plan for settings.
+func compile(schedules []Schedule, settings household.Settings) (*plan, error) {
+	loc, err := household.LoadZone(settings.Timezone)
+	if err != nil {
+		return nil, fmt.Errorf("scheduler: household zone: %w", err)
+	}
+	p := &plan{loc: loc, items: make([]item, len(schedules))}
+	for i, sch := range schedules {
+		rule := sch.Rule(settings)
+		if err := rule.validate(); err != nil {
+			return nil, fmt.Errorf("scheduler: %s: %w", sch.label(), err)
+		}
+		p.items[i] = item{sch: sch, rule: rule}
+	}
+	return p, nil
+}
+
+// loop fires schedules until ctx is cancelled. done is the instant up to
+// which fire times have been handled; it starts at the zero time so the
+// first pass catches up. retry is the periods whose claim failed, each
+// with its own fire time. Each pass first claims retry again; while any
+// claim there still fails, the pass stops and is repeated after
+// ClaimRetry. Otherwise it applies the pending settings changes in order,
+// handling fire times up to a change under the plan it replaces, then
+// handles fire times up to now under the current plan, stopping after the
+// first stretch in which a claim failed.
+func (s *Scheduler) loop(ctx context.Context, p *plan) {
+	var done time.Time
+	var pending []change
+	var retry []target
+	for {
+		now := s.now()
+		pending = append(pending, s.takeChanges()...)
+		retry = s.retry(ctx, retry, now)
+		for len(retry) == 0 && len(pending) > 0 {
+			c := pending[0]
+			if c.at.After(done) {
+				if p != nil {
+					retry = s.fire(ctx, p, done, c.at, now)
+				}
+				done = c.at
+			}
+			p = s.compileChange(ctx, c.settings)
+			pending = pending[1:]
+		}
+		if len(retry) == 0 {
+			if p != nil {
+				retry = s.fire(ctx, p, done, now, now)
+			}
+			done = now
+		}
+		if ctx.Err() != nil {
+			return
+		}
+
+		var timeout <-chan time.Time
+		switch {
+		case len(retry) > 0:
+			timeout = s.after(ClaimRetry)
+		case p != nil:
+			next, ok, err := p.next(ctx, now)
+			switch {
+			case err != nil:
+				s.logger.ErrorContext(ctx, "scheduler: look up next fire time failed; retrying", "error", err, "retry_in", ClaimRetry.String())
+				timeout = s.after(ClaimRetry)
+			case ok:
+				timeout = s.after(min(next.Sub(now), maxWait))
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-timeout:
+		case <-s.wake:
+		}
+	}
+}
+
+// compileChange returns the plan for changed settings, or nil when they
+// are unusable.
+func (s *Scheduler) compileChange(ctx context.Context, settings household.Settings) *plan {
+	p, err := compile(s.schedules, settings)
+	if err != nil {
+		// Settings are validated before they are saved, so this is a
+		// bug; firing at a guessed time would be worse than not firing
+		// until the settings are fixed.
+		s.logger.ErrorContext(ctx, "scheduler: settings unusable; no schedule fires until they change", "error", err)
+		return nil
+	}
+	return p
+}
+
+// target is one schedule's periods still to handle, oldest first, each
+// named by its fire time and the household-local date of its period. A
+// target whose fire times could not be looked up has lookup set instead,
+// with the stretch (done, until] to look them up in again.
+type target struct {
+	it    item
+	loc   *time.Location
+	fires []fireTime
+
+	lookup      bool
+	done, until time.Time
+}
+
+// fire handles, for every schedule, its catch-up fire times after done and
+// at or before until; now is the current instant. It returns the
+// targets whose lookup or claim failed, to be handled again.
+func (s *Scheduler) fire(ctx context.Context, p *plan, done, until, now time.Time) []target {
+	var failed []target
+	for _, it := range p.items {
+		if ctx.Err() != nil {
+			return failed
+		}
+		if t, ok := s.fireItem(ctx, it, p.loc, done, until, now); !ok {
+			failed = append(failed, t)
+		}
+	}
+	return failed
+}
+
+// fireItem handles, oldest first, it's fire times after done and at or
+// before until that passed within CatchUpWindow of now, and the most recent
+// of them even when it passed longer ago. It reports false, with the target
+// to handle again, when the fire times could not be looked up or a period's
+// claim failed.
+func (s *Scheduler) fireItem(ctx context.Context, it item, loc *time.Location, done, until, now time.Time) (target, bool) {
+	fs, err := fireBetween(ctx, it.rule, loc, done, until)
+	if err != nil {
+		s.logger.ErrorContext(ctx, "scheduler: look up fire time failed; retrying",
+			"schedule", it.sch.label(), "error", err, "retry_in", ClaimRetry.String())
+		return target{it: it, loc: loc, lookup: true, done: done, until: until}, false
+	}
+	i := 0
+	for i < len(fs)-1 && now.Sub(fs[i].at) > CatchUpWindow {
+		i++
+	}
+	return s.handleAll(ctx, target{it: it, loc: loc, fires: fs[i:]}, now)
+}
+
+// handleAll handles the periods of t in order, stopping at the first whose
+// claim failed. It reports false, with that period and those after it,
+// when one did.
+func (s *Scheduler) handleAll(ctx context.Context, t target, now time.Time) (target, bool) {
+	for i, f := range t.fires {
+		if !s.handle(ctx, t.it, f, now) {
+			t.fires = t.fires[i:]
+			return t, false
+		}
+	}
+	return target{}, true
+}
+
+// retry handles targets again at now and returns those whose lookup or
+// claim still failed.
+func (s *Scheduler) retry(ctx context.Context, targets []target, now time.Time) []target {
+	var failed []target
+	for i, t := range targets {
+		if ctx.Err() != nil {
+			return append(failed, targets[i:]...)
+		}
+		if t.lookup {
+			if again, ok := s.fireItem(ctx, t.it, t.loc, t.done, t.until, now); !ok {
+				failed = append(failed, again)
+			}
+			continue
+		}
+		if again, ok := s.handleAll(ctx, t, now); !ok {
+			failed = append(failed, again)
+		}
+	}
+	return failed
+}
+
+// handle claims the period of it's fire time f and runs it, or records it
+// as missed when f is more than CatchUpWindow before now. It reports false
+// when the claim failed and the period is still unclaimed.
+func (s *Scheduler) handle(ctx context.Context, it item, f fireTime, now time.Time) bool {
+	at, date := f.at, f.date
+	period := Period{Key: it.rule.PeriodKey(date), FireAt: at, Date: date}
+	if it.rule.NextWeek {
+		period.Week = household.WeekStart(addDays(date, 7))
+	} else {
+		period.Week = household.WeekStart(date)
+	}
+	switch {
+	case it.sch.Key != "":
+		period.Key = it.sch.Key + ":" + period.Key
+	case it.sch.PeriodKey != nil:
+		period.Key = it.sch.PeriodKey(period)
+	}
+	log := s.logger.With("schedule", it.sch.Name, "period", period.Key, "fire_at", at.Format(time.RFC3339))
+
+	claimed, err := s.claim(ctx, it.sch.Name, period.Key, now)
+	if err != nil {
+		log.ErrorContext(ctx, "scheduler: claim period failed; retrying", "error", err, "retry_in", ClaimRetry.String())
+		return false
+	}
+	if !claimed {
+		return true
+	}
+	if late := now.Sub(at); late > CatchUpWindow {
+		log.WarnContext(ctx, "scheduler: period missed; recorded without running", "late", late.String())
+		return true
+	}
+	if err := it.sch.Run(ctx, period); err != nil {
+		log.ErrorContext(ctx, "scheduler: run failed", "error", err)
+		return true
+	}
+	log.InfoContext(ctx, "scheduler: ran")
+	return true
+}
+
+// claim inserts schedule_runs(name, key) and reports whether this call
+// inserted it.
+func (s *Scheduler) claim(ctx context.Context, name, key string, now time.Time) (bool, error) {
+	n, err := db.New(s.st.Writer).ClaimScheduleRun(ctx, db.ClaimScheduleRunParams{
+		ID:        store.NewID(),
+		Schedule:  name,
+		PeriodKey: key,
+		CreatedAt: store.Timestamp{Time: now.UTC().Truncate(time.Millisecond)}.String(),
+	})
+	if err != nil {
+		return false, err
+	}
+	return n == 1, nil
+}
+
+// next returns the earliest fire time of any schedule after now, or false
+// when there is none.
+func (p *plan) next(ctx context.Context, now time.Time) (time.Time, bool, error) {
+	var next time.Time
+	for _, it := range p.items {
+		f, ok, err := fireAfter(ctx, it.rule, p.loc, now)
+		if err != nil {
+			return time.Time{}, false, fmt.Errorf("%s: %w", it.sch.label(), err)
+		}
+		if ok && (next.IsZero() || f.at.Before(next)) {
+			next = f.at
+		}
+	}
+	return next, !next.IsZero(), nil
+}
+
+// window is how many days either side of a date fireBetween and fireAfter
+// search: more than a week, so a weekly rule always has a fire time on
+// each side.
+const window = 8
+
+// atWindow is how many days either side of a date fireBetween and fireAfter
+// look up a DailyAt rule's fire times. A period firing further off is
+// looked up on a later pass, which comes within maxWait.
+const atWindow = 2
+
+// fireTime is a fire time and the household-local date of its period.
+type fireTime struct {
+	at   time.Time
+	date store.LocalDate
+}
+
+// fireBetween returns the fire times of r in zone loc after from and at or
+// before t, oldest first.
+func fireBetween(ctx context.Context, r Rule, loc *time.Location, from, t time.Time) ([]fireTime, error) {
+	fs, err := fireTimes(ctx, r, loc, t)
+	if err != nil {
+		return nil, err
+	}
+	var out []fireTime
+	for _, f := range fs {
+		if f.at.After(from) && !f.at.After(t) {
+			out = append(out, f)
+		}
+	}
+	slices.SortFunc(out, func(a, b fireTime) int { return a.at.Compare(b.at) })
+	return out, nil
+}
+
+// fireAfter returns the earliest fire time of r in zone loc after t.
+func fireAfter(ctx context.Context, r Rule, loc *time.Location, t time.Time) (fireTime, bool, error) {
+	fs, err := fireTimes(ctx, r, loc, t)
+	if err != nil {
+		return fireTime{}, false, err
+	}
+	var best fireTime
+	for _, f := range fs {
+		if f.at.After(t) && (best.at.IsZero() || f.at.Before(best.at)) {
+			best = f
+		}
+	}
+	return best, !best.at.IsZero(), nil
+}
+
+// fireTimes returns r's fire times for the local dates within window days
+// of t's, or atWindow days for a DailyAt rule. A Time that fails to
+// resolve was validated at compile, so it cannot; a DailyAt lookup that
+// fails is an error.
+func fireTimes(ctx context.Context, r Rule, loc *time.Location, t time.Time) ([]fireTime, error) {
+	today := household.Today(t, loc)
+	span := window
+	if r.At != nil {
+		span = atWindow
+	}
+	var out []fireTime
+	for i := -span; i <= span; i++ {
+		d := addDays(today, i)
+		if r.Weekly && weekday(d) != r.Weekday {
+			continue
+		}
+		if r.At != nil {
+			at, ok, err := r.At(ctx, d)
+			if err != nil {
+				return nil, fmt.Errorf("fire time of %s: %w", d, err)
+			}
+			if ok {
+				out = append(out, fireTime{at: at, date: d})
+			}
+			continue
+		}
+		at, err := household.LocalTime(loc, d, r.Time)
+		if err != nil {
+			panic(fmt.Sprintf("scheduler: validated rule %+v: %v", r, err))
+		}
+		out = append(out, fireTime{at: at, date: d})
+	}
+	return out, nil
+}
+
+// addDays returns d plus n calendar days.
+func addDays(d store.LocalDate, n int) store.LocalDate {
+	y, m, day := d.Date()
+	return store.LocalDateOf(time.Date(y, m, day+n, 0, 0, 0, 0, time.UTC))
+}
+
+// weekday returns the day of the week of d.
+func weekday(d store.LocalDate) time.Weekday {
+	y, m, day := d.Date()
+	return time.Date(y, m, day, 0, 0, 0, 0, time.UTC).Weekday()
+}

internal/scheduler/scheduler_test.go

@@ -0,0 +1,805 @@
+package scheduler_test
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"slices"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+const zone = "America/Chicago"
+
+// chicago is the household zone of every test.
+var chicago = mustZone(zone)
+
+func mustZone(name string) *time.Location {
+	loc, err := household.LoadZone(name)
+	if err != nil {
+		panic(err)
+	}
+	return loc
+}
+
+// at returns the instant clocks in Chicago read the given time.
+func at(year int, month time.Month, day, hour, minute int) time.Time {
+	return time.Date(year, month, day, hour, minute, 0, 0, chicago)
+}
+
+// fakeClock is a clock whose time moves only when the test moves it.
+type fakeClock struct {
+	mu     sync.Mutex
+	now    time.Time
+	timers []fakeTimer
+	// waits receives one value per After call, so the test knows the
+	// scheduler finished a pass and is waiting.
+	waits chan struct{}
+}
+
+type fakeTimer struct {
+	deadline time.Time
+	ch       chan time.Time
+}
+
+func newFakeClock(now time.Time) *fakeClock {
+	return &fakeClock{now: now, waits: make(chan struct{}, 100)}
+}
+
+func (c *fakeClock) Now() time.Time {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.now
+}
+
+// After returns a timer that fires d from now. The scheduler waits on only
+// its latest timer, so this one replaces any still pending: a timer the
+// scheduler gave up on when a wake came first never fires.
+func (c *fakeClock) After(d time.Duration) <-chan time.Time {
+	c.mu.Lock()
+	ch := make(chan time.Time, 1)
+	c.timers = []fakeTimer{{deadline: c.now.Add(d), ch: ch}}
+	c.mu.Unlock()
+	c.waits <- struct{}{}
+	return ch
+}
+
+// set moves the clock to t and fires the timers due by then, reporting
+// whether any fired.
+func (c *fakeClock) set(t time.Time) bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.now = t
+	fired := false
+	kept := c.timers[:0]
+	for _, tm := range c.timers {
+		if tm.deadline.After(t) {
+			kept = append(kept, tm)
+			continue
+		}
+		tm.ch <- t
+		fired = true
+	}
+	c.timers = kept
+	return fired
+}
+
+// nextDeadline returns the earliest pending timer deadline.
+func (c *fakeClock) nextDeadline() (time.Time, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	var next time.Time
+	for _, tm := range c.timers {
+		if next.IsZero() || tm.deadline.Before(next) {
+			next = tm.deadline
+		}
+	}
+	return next, !next.IsZero()
+}
+
+// recorder records the periods a schedule ran.
+type recorder struct {
+	mu   sync.Mutex
+	runs []scheduler.Period
+	err  error
+}
+
+func (r *recorder) run(_ context.Context, p scheduler.Period) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.runs = append(r.runs, p)
+	return r.err
+}
+
+func (r *recorder) periods() []scheduler.Period {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return slices.Clone(r.runs)
+}
+
+func (r *recorder) keys() []string {
+	var keys []string
+	for _, p := range r.periods() {
+		keys = append(keys, p.Key)
+	}
+	return keys
+}
+
+// env is a migrated database with household settings in Chicago.
+type env struct {
+	t        *testing.T
+	st       *store.Store
+	settings *household.SettingsService
+	// sched is the scheduler start last started, which wake wakes.
+	sched atomic.Pointer[scheduler.Scheduler]
+}
+
+// wake wakes the scheduler start last started, as the services' wake does
+// in the server; before the first start it does nothing.
+func (e *env) wake() {
+	if s := e.sched.Load(); s != nil {
+		s.Wake()
+	}
+}
+
+func newEnv(t *testing.T) *env {
+	t.Helper()
+	ctx := context.Background()
+	st, err := store.Open(ctx, t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := st.Close(); err != nil {
+			t.Error(err)
+		}
+	})
+	if err := store.Migrate(ctx, st.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+	if err := household.SeedSettings(ctx, st, zone); err != nil {
+		t.Fatal(err)
+	}
+	return &env{t: t, st: st, settings: household.NewSettingsService(st)}
+}
+
+// update changes the household settings.
+func (e *env) update(patch household.SettingsPatch) {
+	e.t.Helper()
+	if _, err := e.settings.Update(context.Background(), patch, "member"); err != nil {
+		e.t.Fatal(err)
+	}
+}
+
+// claimed returns the period keys schedule_runs holds for name.
+func (e *env) claimed(name string) []string {
+	e.t.Helper()
+	rows, err := e.st.Reader.Query(`SELECT period_key FROM schedule_runs WHERE schedule = ? ORDER BY period_key`, name)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	defer rows.Close()
+	var keys []string
+	for rows.Next() {
+		var k string
+		if err := rows.Scan(&k); err != nil {
+			e.t.Fatal(err)
+		}
+		keys = append(keys, k)
+	}
+	if err := rows.Err(); err != nil {
+		e.t.Fatal(err)
+	}
+	return keys
+}
+
+// running is a started scheduler on a fake clock.
+type running struct {
+	t     *testing.T
+	clock *fakeClock
+	stop  func()
+}
+
+// start starts a scheduler on e at now with the schedules, and stops it
+// when the test ends. It returns once the first pass, the catch-up, is done.
+func (e *env) start(now time.Time, schedules ...scheduler.Schedule) *running {
+	e.t.Helper()
+	s, err := scheduler.New(e.st, e.settings, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	clock := newFakeClock(now)
+	scheduler.SetClock(s, clock.Now, clock.After)
+	for _, sch := range schedules {
+		if err := s.Register(sch); err != nil {
+			e.t.Fatal(err)
+		}
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := s.Start(ctx); err != nil {
+		cancel()
+		e.t.Fatal(err)
+	}
+	e.sched.Store(s)
+	var once sync.Once
+	stop := func() {
+		once.Do(func() {
+			cancel()
+			s.Wait()
+		})
+	}
+	e.t.Cleanup(stop)
+	r := &running{t: e.t, clock: clock, stop: stop}
+	r.idle()
+	return r
+}
+
+// idle waits until the scheduler finished a pass and is waiting.
+func (r *running) idle() {
+	r.t.Helper()
+	select {
+	case <-r.clock.waits:
+	case <-time.After(10 * time.Second):
+		r.t.Fatal("scheduler did not finish its pass")
+	}
+}
+
+// runUntil moves the clock to to, stopping at every instant the scheduler
+// asked to wake at on the way, as a real clock would.
+func (r *running) runUntil(to time.Time) {
+	r.t.Helper()
+	for {
+		next, ok := r.clock.nextDeadline()
+		if !ok || next.After(to) {
+			if r.clock.set(to) {
+				r.idle()
+			}
+			return
+		}
+		if r.clock.set(next) {
+			r.idle()
+		}
+	}
+}
+
+// changed waits for the scheduler to apply a settings change, or to look
+// again after a wake.
+func (r *running) changed() {
+	r.t.Helper()
+	r.idle()
+}
+
+func reminder(rec *recorder) scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.DayOfReminder,
+		Rule: func(s household.Settings) scheduler.Rule { return scheduler.Daily(s.ReminderTime) },
+		Run:  rec.run,
+	}
+}
+
+func suggestions(rec *recorder) scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.SuggestionsWeekly,
+		Rule: func(s household.Settings) scheduler.Rule {
+			return scheduler.Weekly(time.Weekday(s.SuggestionsDow), s.SuggestionsTime)
+		},
+		Run: rec.run,
+	}
+}
+
+func planDraft(rec *recorder) scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.PlanDraft,
+		Rule: func(s household.Settings) scheduler.Rule {
+			return scheduler.WeeklyForNextWeek(time.Weekday(s.PlanDraftDow), s.PlanDraftTime)
+		},
+		Run: rec.run,
+	}
+}
+
+func ptr[T any](v T) *T { return &v }
+
+func wantKeys(t *testing.T, what string, got, want []string) {
+	t.Helper()
+	if !slices.Equal(got, want) {
+		t.Fatalf("%s = %q, want %q", what, got, want)
+	}
+}
+
+func TestFiresOncePerPeriod(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	// Seeded reminder time is 16:30; boot just after it on Oct 6 runs it.
+	r := e.start(at(2026, 10, 6, 16, 31), reminder(&rec))
+	wantKeys(t, "after boot", rec.keys(), []string{"2026-10-06"})
+
+	r.runUntil(at(2026, 10, 7, 16, 29))
+	wantKeys(t, "before the fire time", rec.keys(), []string{"2026-10-06"})
+	r.runUntil(at(2026, 10, 9, 23, 59))
+	wantKeys(t, "after three days", rec.keys(), []string{"2026-10-06", "2026-10-07", "2026-10-08", "2026-10-09"})
+
+	for i, p := range rec.periods()[1:] {
+		want := at(2026, 10, 7+i, 16, 30)
+		if !p.FireAt.Equal(want) {
+			t.Errorf("run %s fired at %s, want %s", p.Key, p.FireAt, want)
+		}
+		if p.FireAt.Location().String() != zone {
+			t.Errorf("run %s fired in zone %s, want %s", p.Key, p.FireAt.Location(), zone)
+		}
+	}
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder), rec.keys())
+}
+
+func TestRestartMidPeriodDoesNotRerun(t *testing.T) {
+	e := newEnv(t)
+	var first recorder
+	r := e.start(at(2026, 10, 7, 12, 0), suggestions(&first)) // Wednesday
+	// The seeded Sunday 08:00 of Oct 4 is days ago: missed, not run.
+	wantKeys(t, "first boot", first.keys(), nil)
+	r.runUntil(at(2026, 10, 11, 9, 0))
+	wantKeys(t, "first process", first.keys(), []string{"2026-W41"})
+	r.stop()
+
+	// The restart is an hour after the Sunday 08:00 fire, mid-period.
+	var second recorder
+	r2 := e.start(at(2026, 10, 11, 9, 0), suggestions(&second))
+	wantKeys(t, "after restart", second.keys(), nil)
+	r2.runUntil(at(2026, 10, 18, 7, 59))
+	wantKeys(t, "rest of the period", second.keys(), nil)
+	r2.runUntil(at(2026, 10, 18, 8, 0))
+	wantKeys(t, "next period", second.keys(), []string{"2026-W42"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.SuggestionsWeekly), []string{"2026-W40", "2026-W41", "2026-W42"})
+}
+
+func TestCatchUpWithin24Hours(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	// Sunday Oct 11 08:00 passed 23h59m before boot.
+	e.start(at(2026, 10, 12, 7, 59), suggestions(&rec))
+	wantKeys(t, "catch-up", rec.keys(), []string{"2026-W41"})
+	if p := rec.periods()[0]; !p.FireAt.Equal(at(2026, 10, 11, 8, 0)) {
+		t.Errorf("caught-up period fired at %s, want its fire time", p.FireAt)
+	}
+}
+
+func TestNoCatchUpBeyond24Hours(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	// Sunday Oct 11 08:00 passed 24h01m before boot.
+	r := e.start(at(2026, 10, 12, 8, 1), suggestions(&rec))
+	wantKeys(t, "boot", rec.keys(), nil)
+	// The missed period is recorded, so it never runs later.
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.SuggestionsWeekly), []string{"2026-W41"})
+
+	// Moving the fire time to Sunday 23:00 puts that week's fire time
+	// within 24 h of now. The change itself never fires a passed time...
+	e.update(household.SettingsPatch{SuggestionsTime: ptr("23:00")})
+	r.changed()
+	wantKeys(t, "after a settings change", rec.keys(), nil)
+	r.stop()
+
+	// ...and the restart's catch-up finds the period already recorded.
+	var again recorder
+	r2 := e.start(at(2026, 10, 12, 8, 2), suggestions(&again))
+	wantKeys(t, "after restart", again.keys(), nil)
+	r2.runUntil(at(2026, 10, 18, 23, 0))
+	wantKeys(t, "next period", again.keys(), []string{"2026-W42"})
+}
+
+func TestCatchUpOnlyMostRecentPeriod(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	// Days of downtime: only Oct 9 16:30, 30 minutes ago, runs.
+	e.start(at(2026, 10, 9, 17, 0), reminder(&rec))
+	wantKeys(t, "catch-up", rec.keys(), []string{"2026-10-09"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.DayOfReminder), []string{"2026-10-09"})
+}
+
+func TestCatchUpEveryPeriodWithin24HoursAcrossSpringForward(t *testing.T) {
+	// Clocks in Chicago jump 02:00 CST → 03:00 CDT on Sunday 2026-03-08,
+	// so 01:30 on Mar 8 and 01:30 on Mar 9 are only 23 hours apart.
+	e := newEnv(t)
+	e.update(household.SettingsPatch{ReviewTime: ptr("01:30")})
+	var rec recorder
+	review := scheduler.Schedule{
+		Name: scheduler.RotationCheck,
+		Rule: func(s household.Settings) scheduler.Rule { return scheduler.Daily(s.ReviewTime) },
+		Run:  rec.run,
+	}
+	// Boot at Mar 9 01:35: Mar 9 01:30 passed 5 minutes ago and Mar 8
+	// 01:30 23h05m ago, so both run, oldest first; Mar 7 01:30, 47h05m
+	// ago, is not looked at.
+	r := e.start(at(2026, 3, 9, 1, 35), review)
+	wantKeys(t, "catch-up", rec.keys(), []string{"2026-03-08", "2026-03-09"})
+	wantFired(t, rec.periods(),
+		time.Date(2026, 3, 8, 7, 30, 0, 0, time.UTC), // 01:30 CST
+		time.Date(2026, 3, 9, 6, 30, 0, 0, time.UTC), // 01:30 CDT
+	)
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.RotationCheck), []string{"2026-03-08", "2026-03-09"})
+	r.stop()
+
+	// A restart within the window finds both periods claimed.
+	var again recorder
+	review.Run = again.run
+	r2 := e.start(at(2026, 3, 9, 1, 40), review)
+	r2.runUntil(at(2026, 3, 9, 23, 0))
+	wantKeys(t, "after restart", again.keys(), nil)
+}
+
+func TestSpringForward(t *testing.T) {
+	// Clocks in Chicago jump 02:00 CST → 03:00 CDT on Sunday 2026-03-08.
+	e := newEnv(t)
+	e.update(household.SettingsPatch{ReminderTime: ptr("08:00"), ReviewTime: ptr("02:30")})
+	var daily, skipped recorder
+	review := scheduler.Schedule{
+		Name: scheduler.RotationCheck,
+		Rule: func(s household.Settings) scheduler.Rule { return scheduler.Daily(s.ReviewTime) },
+		Run:  skipped.run,
+	}
+	r := e.start(at(2026, 3, 7, 9, 0), reminder(&daily), review)
+	r.runUntil(at(2026, 3, 9, 12, 0))
+
+	wantKeys(t, "08:00 runs", daily.keys(), []string{"2026-03-07", "2026-03-08", "2026-03-09"})
+	wantFired(t, daily.periods(),
+		time.Date(2026, 3, 7, 14, 0, 0, 0, time.UTC), // 08:00 CST
+		time.Date(2026, 3, 8, 13, 0, 0, 0, time.UTC), // 08:00 CDT
+		time.Date(2026, 3, 9, 13, 0, 0, 0, time.UTC),
+	)
+
+	// 02:30 does not exist on Mar 8: it fires once, an hour later at
+	// 03:30 CDT, keyed by Mar 8.
+	wantKeys(t, "02:30 runs", skipped.keys(), []string{"2026-03-07", "2026-03-08", "2026-03-09"})
+	wantFired(t, skipped.periods(),
+		time.Date(2026, 3, 7, 8, 30, 0, 0, time.UTC), // 02:30 CST
+		time.Date(2026, 3, 8, 8, 30, 0, 0, time.UTC), // 03:30 CDT
+		time.Date(2026, 3, 9, 7, 30, 0, 0, time.UTC), // 02:30 CDT
+	)
+	if got := skipped.periods()[1].FireAt.Format("15:04 MST"); got != "03:30 CDT" {
+		t.Errorf("skipped 02:30 fired at %s local, want 03:30 CDT", got)
+	}
+}
+
+func TestFallBack(t *testing.T) {
+	// Clocks in Chicago go back 02:00 CDT → 01:00 CST on Sunday 2026-11-01.
+	e := newEnv(t)
+	e.update(household.SettingsPatch{ReminderTime: ptr("08:00"), ReviewTime: ptr("01:30")})
+	var daily, repeated recorder
+	review := scheduler.Schedule{
+		Name: scheduler.RotationCheck,
+		Rule: func(s household.Settings) scheduler.Rule { return scheduler.Daily(s.ReviewTime) },
+		Run:  repeated.run,
+	}
+	r := e.start(at(2026, 10, 31, 9, 0), reminder(&daily), review)
+	r.runUntil(at(2026, 11, 2, 12, 0))
+
+	wantKeys(t, "08:00 runs", daily.keys(), []string{"2026-10-31", "2026-11-01", "2026-11-02"})
+	wantFired(t, daily.periods(),
+		time.Date(2026, 10, 31, 13, 0, 0, 0, time.UTC), // 08:00 CDT
+		time.Date(2026, 11, 1, 14, 0, 0, 0, time.UTC),  // 08:00 CST
+		time.Date(2026, 11, 2, 14, 0, 0, 0, time.UTC),
+	)
+
+	// 01:30 happens twice on Nov 1: it fires once, at the first (CDT).
+	wantKeys(t, "01:30 runs", repeated.keys(), []string{"2026-10-31", "2026-11-01", "2026-11-02"})
+	wantFired(t, repeated.periods(),
+		time.Date(2026, 10, 31, 6, 30, 0, 0, time.UTC), // 01:30 CDT
+		time.Date(2026, 11, 1, 6, 30, 0, 0, time.UTC),  // first 01:30, CDT
+		time.Date(2026, 11, 2, 7, 30, 0, 0, time.UTC),  // 01:30 CST
+	)
+}
+
+func TestFallBackSecondOccurrenceDoesNotRerun(t *testing.T) {
+	e := newEnv(t)
+	e.update(household.SettingsPatch{ReviewTime: ptr("01:30")})
+	var rec recorder
+	review := scheduler.Schedule{
+		Name: scheduler.RotationCheck,
+		Rule: func(s household.Settings) scheduler.Rule { return scheduler.Daily(s.ReviewTime) },
+		Run:  rec.run,
+	}
+	// Boot between the two 01:30s of Nov 1: the first ran in an earlier
+	// process, so the second is not a new period.
+	first := time.Date(2026, 11, 1, 6, 30, 0, 0, time.UTC)
+	r := e.start(first.Add(-time.Minute), review)
+	r.runUntil(first)
+	wantKeys(t, "first 01:30", rec.keys(), []string{"2026-10-31", "2026-11-01"})
+	r.stop()
+
+	var again recorder
+	review.Run = again.run
+	r2 := e.start(first.Add(30*time.Minute), review)
+	r2.runUntil(first.Add(2 * time.Hour)) // past the second 01:30, CST
+	wantKeys(t, "second 01:30", again.keys(), nil)
+}
+
+func wantFired(t *testing.T, got []scheduler.Period, want ...time.Time) {
+	t.Helper()
+	if len(got) != len(want) {
+		t.Fatalf("%d runs, want %d", len(got), len(want))
+	}
+	for i := range want {
+		if !got[i].FireAt.Equal(want[i]) {
+			t.Errorf("run %s fired at %s (%s), want %s", got[i].Key, got[i].FireAt.UTC(), got[i].FireAt, want[i])
+		}
+	}
+}
+
+func TestISOWeek53Boundary(t *testing.T) {
+	e := newEnv(t)
+	var sugg, draft recorder
+	// Suggestions Sunday 08:00 keys the ISO week ending that Sunday; the
+	// plan draft Friday 09:00 keys the week after.
+	r := e.start(at(2026, 12, 20, 9, 0), suggestions(&sugg), planDraft(&draft))
+	r.runUntil(at(2027, 1, 11, 0, 0))
+
+	wantKeys(t, "suggestions", sugg.keys(), []string{"2026-W51", "2026-W52", "2026-W53", "2027-W01"})
+	// Sunday 2027-01-03 is the last day of 2026-W53.
+	if p := sugg.periods()[2]; p.Date.String() != "2027-01-03" || p.Week.String() != "2026-12-28" {
+		t.Errorf("2026-W53 suggestions ran on %s for week %s, want 2027-01-03 for 2026-12-28", p.Date, p.Week)
+	}
+	// Friday Dec 18, two days before boot, was missed.
+	wantKeys(t, "plan drafts", draft.keys(), []string{"2026-W53", "2027-W01", "2027-W02"})
+	// Friday 2026-12-25 drafts 2026-W53; Friday 2027-01-01 drafts 2027-W01.
+	if p := draft.periods()[0]; p.Date.String() != "2026-12-25" || p.Week.String() != "2026-12-28" {
+		t.Errorf("2026-W53 draft ran on %s for week %s, want 2026-12-25 for 2026-12-28", p.Date, p.Week)
+	}
+	if p := draft.periods()[1]; p.Date.String() != "2027-01-01" || p.Week.String() != "2027-01-04" {
+		t.Errorf("2027-W01 draft ran on %s for week %s, want 2027-01-01 for 2027-01-04", p.Date, p.Week)
+	}
+}
+
+func TestPeriodKey(t *testing.T) {
+	date := func(s string) store.LocalDate {
+		d, err := store.ParseLocalDate(s)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return d
+	}
+	tests := []struct {
+		rule scheduler.Rule
+		date string
+		want string
+	}{
+		{scheduler.Daily("16:30"), "2026-12-31", "2026-12-31"},
+		{scheduler.Weekly(time.Monday, "00:00"), "2026-12-28", "2026-W53"},
+		{scheduler.Weekly(time.Sunday, "08:00"), "2027-01-03", "2026-W53"},
+		{scheduler.Weekly(time.Monday, "00:00"), "2027-01-04", "2027-W01"},
+		{scheduler.WeeklyForNextWeek(time.Friday, "09:00"), "2026-12-25", "2026-W53"},
+		{scheduler.WeeklyForNextWeek(time.Friday, "09:00"), "2027-01-01", "2027-W01"},
+	}
+	for _, tt := range tests {
+		if got := tt.rule.PeriodKey(date(tt.date)); got != tt.want {
+			t.Errorf("%+v.PeriodKey(%s) = %s, want %s", tt.rule, tt.date, got, tt.want)
+		}
+	}
+}
+
+func TestSettingsChangeMovesNextFire(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	r := e.start(at(2026, 10, 7, 12, 0), reminder(&rec))
+	wantKeys(t, "boot", rec.keys(), []string{"2026-10-06"})
+
+	// Earlier but still ahead: fires at the new time, not the old.
+	e.update(household.SettingsPatch{ReminderTime: ptr("13:00")})
+	r.changed()
+	if next, _ := r.clock.nextDeadline(); !next.Equal(at(2026, 10, 7, 13, 0)) {
+		t.Errorf("next wake %s, want the new 13:00", next)
+	}
+	r.runUntil(at(2026, 10, 7, 13, 0))
+	wantKeys(t, "at the new time", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+	r.runUntil(at(2026, 10, 7, 23, 0))
+	wantKeys(t, "at the old time", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+
+	// Moved to a time already passed today: nothing fires now, and
+	// tomorrow fires at the new time.
+	r.runUntil(at(2026, 10, 8, 12, 0))
+	e.update(household.SettingsPatch{ReminderTime: ptr("11:00")})
+	r.changed()
+	wantKeys(t, "moved into the past", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+	r.runUntil(at(2026, 10, 9, 10, 59))
+	wantKeys(t, "before the new time", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+	r.runUntil(at(2026, 10, 9, 11, 0))
+	wantKeys(t, "the new time", rec.keys(), []string{"2026-10-06", "2026-10-07", "2026-10-09"})
+}
+
+// A change saved at 12:00 moving the 16:30 reminder to 12:01 must fire it
+// even when the scheduler only gets to the change at 12:02, after the new
+// fire time has passed.
+func TestSettingsChangeAppliedLateStillFires(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	// blocker holds the scheduler in a Run at 12:00 on 2026-10-07 while
+	// the settings change and the clock moves on.
+	started := make(chan struct{})
+	release := make(chan struct{})
+	blocker := scheduler.Schedule{
+		Name: scheduler.RotationCheck,
+		Rule: func(household.Settings) scheduler.Rule { return scheduler.Daily("12:00") },
+		Run: func(_ context.Context, p scheduler.Period) error {
+			if p.Key == "2026-10-07" {
+				close(started)
+				<-release
+			}
+			return nil
+		},
+	}
+	r := e.start(at(2026, 10, 7, 11, 0), reminder(&rec), blocker)
+	wantKeys(t, "boot", rec.keys(), []string{"2026-10-06"})
+
+	r.clock.set(at(2026, 10, 7, 12, 0))
+	<-started
+	e.update(household.SettingsPatch{ReminderTime: ptr("12:01")})
+	r.clock.set(at(2026, 10, 7, 12, 2))
+	close(release)
+	r.idle() // the pass the blocker held
+	r.idle() // the pass that applies the change
+	wantKeys(t, "after the late change", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+
+	r.runUntil(at(2026, 10, 7, 23, 0))
+	wantKeys(t, "end of day", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+	wantKeys(t, "claims", e.claimed(scheduler.DayOfReminder), []string{"2026-10-06", "2026-10-07"})
+}
+
+// failClaims makes every claim fail until recover is called.
+func (e *env) failClaims() (recover func()) {
+	e.t.Helper()
+	for _, q := range []string{
+		`CREATE TABLE fail_claims (on_ INTEGER NOT NULL)`,
+		`INSERT INTO fail_claims VALUES (1)`,
+		`CREATE TRIGGER fail_claim BEFORE INSERT ON schedule_runs
+			WHEN (SELECT on_ FROM fail_claims) = 1
+			BEGIN SELECT RAISE(ABORT, 'injected claim failure'); END`,
+	} {
+		if _, err := e.st.Writer.Exec(q); err != nil {
+			e.t.Fatal(err)
+		}
+	}
+	return func() {
+		e.t.Helper()
+		if _, err := e.st.Writer.Exec(`UPDATE fail_claims SET on_ = 0`); err != nil {
+			e.t.Fatal(err)
+		}
+	}
+}
+
+// A claim that fails is retried, not skipped, and the period then runs once.
+func TestClaimFailureIsRetried(t *testing.T) {
+	e := newEnv(t)
+	recoverClaims := e.failClaims()
+	var rec recorder
+	r := e.start(at(2026, 10, 7, 12, 0), reminder(&rec))
+	wantKeys(t, "boot with failing claims", rec.keys(), nil)
+	wantKeys(t, "claims while failing", e.claimed(scheduler.DayOfReminder), nil)
+	if next, _ := r.clock.nextDeadline(); !next.Equal(at(2026, 10, 7, 12, 0).Add(scheduler.ClaimRetry)) {
+		t.Errorf("next wake %s, want a retry after %s", next, scheduler.ClaimRetry)
+	}
+
+	recoverClaims()
+	r.runUntil(at(2026, 10, 7, 12, 0).Add(scheduler.ClaimRetry))
+	wantKeys(t, "after the retry", rec.keys(), []string{"2026-10-06"})
+	r.runUntil(at(2026, 10, 7, 23, 0))
+	wantKeys(t, "end of day", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+	wantKeys(t, "claims", e.claimed(scheduler.DayOfReminder), []string{"2026-10-06", "2026-10-07"})
+}
+
+// A claim that keeps failing past the next daily fire is retried for its
+// own period, not the most recent one: that period, now more than
+// CatchUpWindow old, is recorded as missed, and the later period runs once.
+func TestClaimFailureRecoversAfterNextFire(t *testing.T) {
+	e := newEnv(t)
+	recoverClaims := e.failClaims()
+	var rec recorder
+	// The 7 October 16:30 reminder is due and its claim fails, past the
+	// 8 October 16:30 fire.
+	r := e.start(at(2026, 10, 7, 16, 45), reminder(&rec))
+	r.runUntil(at(2026, 10, 8, 17, 0))
+	wantKeys(t, "runs while failing", rec.keys(), nil)
+	wantKeys(t, "claims while failing", e.claimed(scheduler.DayOfReminder), nil)
+
+	// Claims recover 24h31m after the 7 October fire.
+	recoverClaims()
+	r.runUntil(at(2026, 10, 8, 17, 1))
+	wantKeys(t, "after recovery", rec.keys(), []string{"2026-10-08"})
+	wantKeys(t, "claims after recovery", e.claimed(scheduler.DayOfReminder), []string{"2026-10-07", "2026-10-08"})
+
+	r.runUntil(at(2026, 10, 9, 16, 0))
+	wantKeys(t, "next day", rec.keys(), []string{"2026-10-08"})
+}
+
+func TestSettingsChangeTimezone(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	r := e.start(at(2026, 10, 7, 12, 0), reminder(&rec))
+	e.update(household.SettingsPatch{Timezone: ptr("America/New_York")})
+	r.changed()
+	// 16:30 in New York is 15:30 in Chicago.
+	r.runUntil(at(2026, 10, 7, 15, 30))
+	wantKeys(t, "after the zone change", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+	if got := rec.periods()[1].FireAt.Location().String(); got != "America/New_York" {
+		t.Errorf("fired in zone %s, want America/New_York", got)
+	}
+}
+
+func TestRunErrorKeepsPeriodClaimed(t *testing.T) {
+	e := newEnv(t)
+	rec := recorder{err: errors.New("boom")}
+	r := e.start(at(2026, 10, 7, 16, 0), reminder(&rec))
+	r.runUntil(at(2026, 10, 7, 23, 0))
+	wantKeys(t, "runs", rec.keys(), []string{"2026-10-06", "2026-10-07"})
+	r.stop()
+	var again recorder
+	e.start(at(2026, 10, 7, 23, 0), reminder(&again))
+	wantKeys(t, "after restart", again.keys(), nil)
+}
+
+func TestRegister(t *testing.T) {
+	e := newEnv(t)
+	s, err := scheduler.New(e.st, e.settings, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var rec recorder
+	bad := []scheduler.Schedule{
+		{Name: "hourly", Rule: reminder(&rec).Rule, Run: rec.run},
+		{Name: scheduler.DayOfReminder, Run: rec.run},
+		{Name: scheduler.DayOfReminder, Rule: reminder(&rec).Rule},
+		{Name: scheduler.DayOfReminder, Key: "start", PeriodKey: func(p scheduler.Period) string { return p.Key }, Rule: reminder(&rec).Rule, Run: rec.run},
+	}
+	for _, sch := range bad {
+		if err := s.Register(sch); err == nil {
+			t.Errorf("Register(%q) accepted an invalid schedule", sch.Name)
+		}
+	}
+	if err := s.Register(reminder(&rec)); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Register(reminder(&rec)); err == nil {
+		t.Error("Register accepted a second schedule with the same name")
+	}
+}
+
+func TestStartRejectsInvalidRule(t *testing.T) {
+	e := newEnv(t)
+	s, err := scheduler.New(e.st, e.settings, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var rec recorder
+	if err := s.Register(scheduler.Schedule{
+		Name: scheduler.WeekRollover,
+		Rule: func(household.Settings) scheduler.Rule { return scheduler.Weekly(7, "00:00") },
+		Run:  rec.run,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Start(context.Background()); err == nil {
+		s.Wait()
+		t.Fatal("Start accepted weekday 7")
+	}
+}
+
+func TestStopEndsTheLoop(t *testing.T) {
+	e := newEnv(t)
+	var rec recorder
+	r := e.start(at(2026, 10, 7, 12, 0), reminder(&rec))
+	done := make(chan struct{})
+	go func() {
+		r.stop()
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(10 * time.Second):
+		t.Fatal("scheduler did not stop")
+	}
+}

internal/scheduler/suggestions_test.go

@@ -0,0 +1,370 @@
+package scheduler_test
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify/notifytest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
+)
+
+// The tests in this file run suggest's suggestions_weekly schedule on the
+// fake clock against the real suggestion service, job runner, harness and
+// notification outbox, with the AI and recipe sources faked.
+
+// suggestEnv is a suggestion service over a scheduler env's store, the
+// "process" a scheduler runs it in. side answers suggest_side_quests and
+// model normalize_recipe while grounding.
+type suggestEnv struct {
+	e      *env
+	svc    *suggest.Service
+	side   *llm.Fake
+	model  *llm.Fake
+	search *recipestest.Search
+	pages  *recipestest.Pages
+	images *recipestest.Images
+	logs   *syncBuffer
+	stop   func()
+}
+
+// syncBuffer collects log output written by concurrent goroutines.
+type syncBuffer struct {
+	mu  sync.Mutex
+	buf strings.Builder
+}
+
+func (b *syncBuffer) Write(p []byte) (int, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.Write(p)
+}
+
+func (b *syncBuffer) String() string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.buf.String()
+}
+
+// regulars stores the Regulars Beef Chili and Chicken Fajitas, so a batch
+// has Regulars to suggest from.
+func (e *env) regulars() {
+	e.t.Helper()
+	for _, name := range []string{"Beef Chili", "Chicken Fajitas"} {
+		now := store.Now().String()
+		if _, err := db.New(e.st.Writer).CreateDinner(context.Background(), db.CreateDinnerParams{
+			ID:              store.NewID(),
+			Name:            name,
+			NormalizedName:  harness.Normalize(name),
+			Status:          "regular",
+			Origin:          "regular",
+			GroundingStatus: "manual",
+			CreatedAt:       now,
+			UpdatedAt:       now,
+		}); err != nil {
+			e.t.Fatal(err)
+		}
+	}
+}
+
+// suggestions builds a suggestion service over e with a started job
+// runner, which stop stops (and the test's end, if not before).
+func (e *env) suggestions() *suggestEnv {
+	e.t.Helper()
+	s := &suggestEnv{
+		e:      e,
+		side:   &llm.Fake{},
+		model:  &llm.Fake{},
+		search: &recipestest.Search{Results: map[string][]recipes.Candidate{}},
+		pages:  &recipestest.Pages{Bodies: map[string][]byte{}},
+		images: &recipestest.Images{JPEGs: map[string][]byte{}},
+		logs:   &syncBuffer{},
+	}
+	g := recipestest.NewGrounder(e.t, e.st, e.t.TempDir(), s.search, s.pages, s.images, s.model)
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	cfg := harness.Config{
+		Settings:    llm.Settings{Provider: "anthropic", Model: "claude-test", Temperature: 0.7},
+		NewProvider: func(llm.Settings, string) (llm.Provider, error) { return s.side, nil },
+		Store:       e.st,
+		Guard:       guard,
+	}
+	suggester := func(ctx context.Context, scope string, in skills.SideQuestsRequest) (skills.SideQuests, error) {
+		return skills.SuggestSideQuests(ctx, cfg, scope, in)
+	}
+	logger := slog.New(slog.NewTextHandler(s.logs, nil))
+	runner, err := jobs.NewRunner(e.st, logger, 1)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	s.svc, err = suggest.NewService(e.st, g, suggester, runner, notifytest.New(e.t, e.st), logger)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := runner.Start(ctx); err != nil {
+		cancel()
+		e.t.Fatal(err)
+	}
+	var once sync.Once
+	s.stop = func() {
+		once.Do(func() {
+			cancel()
+			runner.Wait()
+		})
+	}
+	e.t.Cleanup(s.stop)
+	return s
+}
+
+// week scripts the next batch: suggest_side_quests answers with the
+// Side quests named names, each grounded by its own recipe.
+func (s *suggestEnv) week(names ...string) {
+	s.e.t.Helper()
+	var quests []string
+	for _, name := range names {
+		slug := strings.ReplaceAll(strings.ToLower(name), " ", "-")
+		page, photo := "https://r.example/"+slug, "https://r.example/"+slug+".jpg"
+		s.search.Results[name] = []recipes.Candidate{{URL: page}}
+		s.pages.Bodies[page] = recipestest.RecipePage(name, "R Kitchen", photo, 35)
+		s.images.JPEGs[photo] = recipestest.JPEG(s.e.t, 400, 320, uint8(len(s.images.JPEGs)+1))
+		s.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 35))
+		quests = append(quests, fmt.Sprintf(`{"name":%q,"cuisine":"Fusion","method":"stovetop","est_minutes":35,"difficulty":"easy","reason":"Like your Beef Chili.","cited_regulars":["Beef Chili"],"search_query":%q}`, name, name))
+	}
+	js := `{"suggestions":[` + strings.Join(quests, ",") + `]}`
+	s.side.QueueGenerate(llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}})
+}
+
+// batch is a suggestion_batches row.
+type batch struct {
+	ID, Trigger, Status string
+}
+
+// batches returns every suggestion batch, oldest first.
+func (e *env) batches() []batch {
+	e.t.Helper()
+	rows, err := e.st.Reader.Query(`SELECT id, trigger, status FROM suggestion_batches ORDER BY created_at, id`)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	defer rows.Close()
+	var out []batch
+	for rows.Next() {
+		var b batch
+		if err := rows.Scan(&b.ID, &b.Trigger, &b.Status); err != nil {
+			e.t.Fatal(err)
+		}
+		out = append(out, b)
+	}
+	if err := rows.Err(); err != nil {
+		e.t.Fatal(err)
+	}
+	return out
+}
+
+// settled waits until no batch is pending or running and returns the
+// batches.
+func (e *env) settled() []batch {
+	e.t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		bs := e.batches()
+		busy := false
+		for _, b := range bs {
+			busy = busy || b.Status == suggest.BatchPending || b.Status == suggest.BatchRunning
+		}
+		if !busy {
+			return bs
+		}
+		if time.Now().After(deadline) {
+			e.t.Fatalf("batches still under way: %+v", bs)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+// wantBatches fails unless the batches are scheduled with statuses want.
+func wantBatches(t *testing.T, what string, got []batch, want ...string) {
+	t.Helper()
+	ok := len(got) == len(want)
+	for i := 0; ok && i < len(got); i++ {
+		ok = got[i].Trigger == suggest.TriggerScheduled && got[i].Status == want[i]
+	}
+	if !ok {
+		t.Fatalf("%s: batches = %+v, want scheduled %q", what, got, want)
+	}
+}
+
+// notified returns the new_suggestions keys stored, oldest first, and
+// reports an error for any whose title is not the one titles gives it.
+func (e *env) notified(titles ...string) []string {
+	e.t.Helper()
+	var keys []string
+	rows := notifytest.Rows(e.t, e.st, notify.NewSuggestions)
+	for i, r := range rows {
+		keys = append(keys, r.Key)
+		if i < len(titles) && r.Payload.Title != titles[i] {
+			e.t.Errorf("new_suggestions %s title = %q, want %q", r.Key, r.Payload.Title, titles[i])
+		}
+	}
+	return keys
+}
+
+// TestSuggestionsWeeklyOneBatchAndNotificationPerWeek: at the seeded
+// Sunday 08:00 the schedule starts one scheduled batch a week, period
+// suggestions_weekly:YYYY-Www, and each tells the household once, with
+// new_suggestions:YYYY-Www counting its new Side quests.
+func TestSuggestionsWeeklyOneBatchAndNotificationPerWeek(t *testing.T) {
+	e := newEnv(t)
+	e.regulars()
+	s := e.suggestions()
+	s.week("Chili Verde", "Chicken Shawarma Bowls")
+	s.week("Lamb Kofta", "Black Bean Tostadas", "Pork Carnitas")
+
+	// Wednesday Oct 7: the Sunday Oct 4 08:00 fire is days ago, missed.
+	r := e.start(at(2026, 10, 7, 12, 0), s.svc.WeeklySchedule())
+	r.runUntil(at(2026, 10, 11, 7, 59))
+	wantBatches(t, "before Sunday 08:00", e.settled())
+	wantKeys(t, "new_suggestions before Sunday 08:00", e.notified(), nil)
+
+	r.runUntil(at(2026, 10, 11, 8, 0))
+	wantBatches(t, "at Sunday 08:00", e.settled(), suggest.BatchDone)
+	wantKeys(t, "new_suggestions of W41", e.notified("2 new Side quests are in"), []string{"new_suggestions:2026-W41"})
+
+	r.runUntil(at(2026, 10, 18, 7, 59))
+	wantBatches(t, "rest of W41", e.settled(), suggest.BatchDone)
+	r.runUntil(at(2026, 10, 18, 9, 0))
+	wantBatches(t, "W42", e.settled(), suggest.BatchDone, suggest.BatchDone)
+	wantKeys(t, "new_suggestions of W41 and W42", e.notified("2 new Side quests are in", "3 new Side quests are in"),
+		[]string{"new_suggestions:2026-W41", "new_suggestions:2026-W42"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.SuggestionsWeekly), []string{"2026-W40", "2026-W41", "2026-W42"})
+}
+
+// TestSuggestionsWeeklyFollowsSettings: the schedule fires at the
+// household's suggestions_dow and suggestions_time.
+func TestSuggestionsWeeklyFollowsSettings(t *testing.T) {
+	e := newEnv(t)
+	e.regulars()
+	e.update(household.SettingsPatch{SuggestionsDow: ptr(3), SuggestionsTime: ptr("18:30")})
+	s := e.suggestions()
+	s.week("Chili Verde")
+
+	r := e.start(at(2026, 10, 12, 12, 0), s.svc.WeeklySchedule()) // Monday
+	r.runUntil(at(2026, 10, 14, 18, 29))                          // Wednesday
+	wantBatches(t, "before Wednesday 18:30", e.settled())
+	r.runUntil(at(2026, 10, 14, 18, 30))
+	wantBatches(t, "at Wednesday 18:30", e.settled(), suggest.BatchDone)
+	wantKeys(t, "new_suggestions", e.notified("1 new Side quest is in"), []string{"new_suggestions:2026-W42"})
+}
+
+// TestSuggestionsWeeklyAIFailureSendsNothing: when suggest_side_quests
+// fails the batch fails with the failure logged and recorded in ai_runs,
+// and the household is not notified.
+func TestSuggestionsWeeklyAIFailureSendsNothing(t *testing.T) {
+	e := newEnv(t)
+	e.regulars()
+	s := e.suggestions()
+	s.side.QueueGenerate(llm.GenerateResult{Err: errors.New("provider down")})
+
+	r := e.start(at(2026, 10, 11, 7, 0), s.svc.WeeklySchedule())
+	r.runUntil(at(2026, 10, 11, 8, 0))
+	wantBatches(t, "after the AI failed", e.settled(), suggest.BatchFailed)
+	wantKeys(t, "new_suggestions after the AI failed", e.notified(), nil)
+	// W40 is the boot's missed period, recorded without running.
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.SuggestionsWeekly), []string{"2026-W40", "2026-W41"})
+
+	var status, msg string
+	if err := e.st.Reader.QueryRow(`SELECT status, COALESCE(error, '') FROM ai_runs WHERE skill = 'suggest_side_quests'`).Scan(&status, &msg); err != nil {
+		t.Fatalf("ai_runs row of suggest_side_quests: %v", err)
+	}
+	if status != string(harness.StatusProviderError) || msg == "" {
+		t.Errorf("ai_runs suggest_side_quests = %s %q, want %s with its message", status, msg, harness.StatusProviderError)
+	}
+	if logs := s.logs.String(); !strings.Contains(logs, "suggestion batch failed") || !strings.Contains(logs, "reason="+suggest.ReasonAIFailed) {
+		t.Errorf("logs = %s, want the batch failure with reason %s", logs, suggest.ReasonAIFailed)
+	}
+}
+
+// TestSuggestionsWeeklyNoDuplicateAfterRestart: a restart after the week's
+// batch ran, still within the catch-up window, starts no second batch and
+// sends no second notification: the period is already claimed.
+func TestSuggestionsWeeklyNoDuplicateAfterRestart(t *testing.T) {
+	e := newEnv(t)
+	e.regulars()
+	s := e.suggestions()
+	s.week("Chili Verde", "Chicken Shawarma Bowls")
+	r := e.start(at(2026, 10, 11, 7, 0), s.svc.WeeklySchedule())
+	r.runUntil(at(2026, 10, 11, 8, 0))
+	wantBatches(t, "first process", e.settled(), suggest.BatchDone)
+	r.stop()
+	s.stop()
+
+	// The restarted process has a new job runner, suggestion service and
+	// scheduler; it would answer a second batch if one were started.
+	s2 := e.suggestions()
+	s2.week("Lamb Kofta")
+	r2 := e.start(at(2026, 10, 11, 9, 0), s2.svc.WeeklySchedule())
+	r2.runUntil(at(2026, 10, 18, 7, 59))
+	wantBatches(t, "after restart", e.settled(), suggest.BatchDone)
+	wantKeys(t, "new_suggestions after restart", e.notified(), []string{"new_suggestions:2026-W41"})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.SuggestionsWeekly), []string{"2026-W40", "2026-W41"})
+}
+
+// TestSuggestionsWeeklyCatchUpAfterTheWeekEnds: a Sunday fire caught up on
+// Monday, in the next ISO week, still runs W41's batch keyed by W41, and
+// the next Sunday's batch notifies for W42.
+func TestSuggestionsWeeklyCatchUpAfterTheWeekEnds(t *testing.T) {
+	e := newEnv(t)
+	e.regulars()
+	s := e.suggestions()
+	s.week("Chili Verde")
+	s.week("Lamb Kofta")
+
+	r := e.start(at(2026, 10, 12, 7, 0), s.svc.WeeklySchedule()) // Monday, 23h late
+	wantBatches(t, "after catch-up", e.settled(), suggest.BatchDone)
+	wantKeys(t, "new_suggestions after catch-up", e.notified(), []string{"new_suggestions:2026-W41"})
+	r.runUntil(at(2026, 10, 18, 8, 0))
+	wantBatches(t, "W42", e.settled(), suggest.BatchDone, suggest.BatchDone)
+	wantKeys(t, "new_suggestions", e.notified(), []string{"new_suggestions:2026-W41", "new_suggestions:2026-W42"})
+}
+
+// TestSuggestionsWeeklyStartsNoBatchWhileOneIsUnderWay: a period that
+// fires while a batch is pending starts no second one and says so.
+func TestSuggestionsWeeklyStartsNoBatchWhileOneIsUnderWay(t *testing.T) {
+	e := newEnv(t)
+	e.regulars()
+	s := e.suggestions()
+	s.stop() // the manual batch stays pending
+	manual, err := s.svc.StartBatch(context.Background(), suggest.TriggerManual)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	r := e.start(at(2026, 10, 11, 7, 0), s.svc.WeeklySchedule())
+	r.runUntil(at(2026, 10, 11, 8, 0))
+	if bs := e.batches(); len(bs) != 1 || bs[0].ID != manual.ID {
+		t.Fatalf("batches = %+v, want only the manual batch %s", bs, manual.ID)
+	}
+	if logs := s.logs.String(); !strings.Contains(logs, "scheduled suggestion batch not started") || !strings.Contains(logs, "period=2026-W41") {
+		t.Errorf("logs = %s, want the skipped period logged", logs)
+	}
+}

internal/scheduler/weekly_automation_test.go

@@ -0,0 +1,421 @@
+package scheduler_test
+
+import (
+	"context"
+	"crypto/rand"
+	"database/sql"
+	"encoding/base64"
+	"errors"
+	"log/slog"
+	"strings"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/chat"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/chat/chattest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify/notifytest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/secretbox"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/shopping"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// The tests in this file run shopping's shopping_chat_autosend and
+// week_rollover schedules, and harness's ai_runs_purge, on the fake clock
+// against the real shopping service, Google Chat client (posting to a fake
+// webhook), notification preferences and ai_runs purge. The seeded
+// autosend is Saturday 08:00 in Chicago.
+
+// w41 is the Monday of 2026-W41.
+var w41 = mustLocalDate("2026-10-05")
+
+// shopEnv is a shopping service over a scheduler env's store. Its job
+// runner never starts, so Generate's title jobs stay queued and every
+// Supply run stays untitled until Freeze titles it, which fails.
+type shopEnv struct {
+	e     *env
+	svc   *shopping.Service
+	chat  *chattest.Chat
+	cs    *chat.Service
+	plans *planEnv
+	logs  *syncBuffer
+}
+
+// shopping builds a shopping service over e, with Regulars to plan from.
+func (e *env) shopping() *shopEnv {
+	e.t.Helper()
+	s := &shopEnv{e: e, chat: chattest.New(e.t), plans: e.plans(e.pool()), logs: &syncBuffer{}}
+	key := make([]byte, secretbox.KeySize)
+	rand.Read(key)
+	box, err := secretbox.New(base64.StdEncoding.EncodeToString(key))
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	s.cs, err = chat.NewService(e.st, box, publicURL, s.chat.Transport())
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	logger := slog.New(slog.NewTextHandler(s.logs, nil))
+	runner, err := jobs.NewRunner(e.st, logger, 1)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	noTitle := func(context.Context, string, skills.ArchiveTitleRequest) (skills.ArchiveTitle, error) {
+		return skills.ArchiveTitle{}, errors.New("no AI in this test")
+	}
+	s.svc, err = shopping.NewService(e.st, noTitle, runner, notifytest.New(e.t, e.st), s.cs, logger)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	return s
+}
+
+// list plans the week starting weekStart and generates its Supply run.
+func (s *shopEnv) list(weekStart store.LocalDate) {
+	s.e.t.Helper()
+	s.plans.planWeek(weekStart)
+	if _, err := s.svc.Generate(context.Background(), weekStart); err != nil {
+		s.e.t.Fatal(err)
+	}
+}
+
+// webhook stores the fake Google Chat webhook.
+func (s *shopEnv) webhook() {
+	s.e.t.Helper()
+	if _, err := s.cs.Put(context.Background(), chattest.Webhook, "Family"); err != nil {
+		s.e.t.Fatal(err)
+	}
+}
+
+// get returns the Supply run of the week starting weekStart.
+func (s *shopEnv) get(weekStart store.LocalDate) shopping.List {
+	s.e.t.Helper()
+	l, err := s.svc.Get(context.Background(), weekStart)
+	if err != nil {
+		s.e.t.Fatal(err)
+	}
+	return l
+}
+
+// wantLogged fails unless the service logged want and logged no error.
+func (s *shopEnv) wantLogged(want string) {
+	s.e.t.Helper()
+	if logs := s.logs.String(); !strings.Contains(logs, want) || strings.Contains(logs, "level=ERROR") {
+		s.e.t.Errorf("logs = %s, want %q and no error", logs, want)
+	}
+}
+
+// TestChatAutosendSendsComingWeek: at the seeded Saturday 08:00 the
+// schedule posts the coming week's Supply run, W43's, to Google Chat
+// through SendToChat, in that week's thread, and records sent_to_chat_at;
+// its period is claimed in schedule_runs as list_ready:chat:2026-10-19,
+// the coming week's start. It posts once.
+func TestChatAutosendSendsComingWeek(t *testing.T) {
+	e := newEnv(t)
+	s := e.shopping()
+	s.list(w43)
+	s.webhook()
+
+	// Saturday 07:00: the previous Saturday's period is past the
+	// catch-up window, so it is recorded as missed.
+	r := e.start(at(2026, 10, 17, 7, 0), s.svc.ChatAutosendSchedule())
+	r.runUntil(at(2026, 10, 17, 7, 59))
+	if n := len(s.chat.Posts()); n != 0 || s.get(w43).SentToChatAt != nil {
+		t.Fatalf("before 08:00: %d posts, sent_to_chat_at %v, want none", n, s.get(w43).SentToChatAt)
+	}
+
+	r.runUntil(at(2026, 10, 17, 8, 0))
+	posts := s.chat.Posts()
+	if len(posts) != 1 {
+		t.Fatalf("at 08:00: %d posts, want 1", len(posts))
+	}
+	if !strings.HasPrefix(posts[0].Text(), "Supply run · Week 43 · Oct 19 – 25") {
+		t.Errorf("posted %q, want the W43 Supply run", posts[0].Text())
+	}
+	if got := posts[0].Query.Get("threadKey"); got != chat.ThreadKey(w43) {
+		t.Errorf("posted in thread %q, want %q", got, chat.ThreadKey(w43))
+	}
+	if s.get(w43).SentToChatAt == nil {
+		t.Error("sent_to_chat_at not recorded")
+	}
+	s.wantLogged("Supply run sent to Google Chat")
+	s.wantLogged("period=list_ready:chat:2026-10-19")
+
+	r.runUntil(at(2026, 10, 24, 7, 0))
+	if n := len(s.chat.Posts()); n != 1 {
+		t.Errorf("a week on: %d posts, want 1", n)
+	}
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.ShoppingChatAutosend), []string{"list_ready:chat:2026-10-12", "list_ready:chat:2026-10-19"})
+}
+
+// TestChatAutosendFollowsSettings: chat_autosend_dow and
+// chat_autosend_time move the send without a restart, here to Friday
+// 18:00, still for the coming week.
+func TestChatAutosendFollowsSettings(t *testing.T) {
+	e := newEnv(t)
+	s := e.shopping()
+	s.list(w43)
+	s.webhook()
+
+	r := e.start(at(2026, 10, 16, 12, 0), s.svc.ChatAutosendSchedule())
+	e.update(household.SettingsPatch{ChatAutosendDow: ptr(5), ChatAutosendTime: ptr("18:00")})
+	r.changed()
+	r.runUntil(at(2026, 10, 16, 17, 59))
+	if n := len(s.chat.Posts()); n != 0 {
+		t.Fatalf("before Friday 18:00: %d posts, want 0", n)
+	}
+	r.runUntil(at(2026, 10, 16, 18, 0))
+	if n := len(s.chat.Posts()); n != 1 || s.get(w43).SentToChatAt == nil {
+		t.Fatalf("at Friday 18:00: %d posts, sent_to_chat_at %v, want 1 and set", n, s.get(w43).SentToChatAt)
+	}
+	r.runUntil(at(2026, 10, 17, 9, 0))
+	if n := len(s.chat.Posts()); n != 1 {
+		t.Errorf("Saturday: %d posts, want still 1", n)
+	}
+}
+
+// TestChatAutosendSkips: the schedule posts nothing, records no send and
+// fails nothing when the coming week's Supply run was already sent, when
+// the week has no Supply run, when list_ready is switched off for Google
+// Chat, and when no webhook is stored. Each period is still claimed and
+// the reason logged.
+func TestChatAutosendSkips(t *testing.T) {
+	cases := []struct {
+		name  string
+		setup func(t *testing.T, s *shopEnv)
+		// posts is how many posts the setup itself made.
+		posts  int
+		reason string
+	}{
+		{
+			name: "already sent",
+			setup: func(t *testing.T, s *shopEnv) {
+				s.list(w43)
+				s.webhook()
+				if _, err := s.svc.SendToChat(context.Background(), w43, false); err != nil {
+					t.Fatal(err)
+				}
+			},
+			posts:  1,
+			reason: shopping.AutosendAlreadySent,
+		},
+		{
+			name: "no list",
+			setup: func(t *testing.T, s *shopEnv) {
+				s.list(w42)
+				s.webhook()
+			},
+			reason: shopping.AutosendNoList,
+		},
+		{
+			name: "chat off for list_ready",
+			setup: func(t *testing.T, s *shopEnv) {
+				s.list(w43)
+				s.webhook()
+				if _, err := s.e.st.Writer.Exec(`UPDATE notification_prefs SET chat = 0 WHERE event = 'list_ready'`); err != nil {
+					t.Fatal(err)
+				}
+			},
+			reason: shopping.AutosendChatOff,
+		},
+		{
+			name: "no webhook",
+			setup: func(t *testing.T, s *shopEnv) {
+				s.list(w43)
+			},
+			reason: shopping.AutosendNotConfigured,
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			e := newEnv(t)
+			s := e.shopping()
+			c.setup(t, s)
+			var sentBefore *string
+			if l, err := s.svc.Get(context.Background(), w43); err == nil {
+				sentBefore = l.SentToChatAt
+			}
+
+			r := e.start(at(2026, 10, 17, 7, 0), s.svc.ChatAutosendSchedule())
+			r.runUntil(at(2026, 10, 17, 9, 0))
+			if n := len(s.chat.Posts()); n != c.posts {
+				t.Errorf("posts = %d, want %d", n, c.posts)
+			}
+			if l, err := s.svc.Get(context.Background(), w43); err == nil && !equalPtr(l.SentToChatAt, sentBefore) {
+				t.Errorf("sent_to_chat_at = %v, want %v", l.SentToChatAt, sentBefore)
+			}
+			s.wantLogged("Supply run not sent to Google Chat: " + c.reason)
+			wantKeys(t, "schedule_runs", e.claimed(scheduler.ShoppingChatAutosend), []string{"list_ready:chat:2026-10-12", "list_ready:chat:2026-10-19"})
+		})
+	}
+}
+
+// TestChatAutosendFailureSurfaces: a send Google Chat refuses is the
+// period's error, logged as such; the period stays claimed and is not
+// retried, and sent_to_chat_at is not recorded.
+func TestChatAutosendFailureSurfaces(t *testing.T) {
+	e := newEnv(t)
+	s := e.shopping()
+	s.list(w43)
+	s.webhook()
+	s.chat.SetStatus(500)
+
+	var logs syncBuffer
+	sched, err := scheduler.New(e.st, e.settings, slog.New(slog.NewTextHandler(&logs, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	clock := newFakeClock(at(2026, 10, 17, 7, 0))
+	scheduler.SetClock(sched, clock.Now, clock.After)
+	if err := sched.Register(s.svc.ChatAutosendSchedule()); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(func() {
+		cancel()
+		sched.Wait()
+	})
+	if err := sched.Start(ctx); err != nil {
+		t.Fatal(err)
+	}
+	r := &running{t: t, clock: clock, stop: cancel}
+	r.idle()
+	r.runUntil(at(2026, 10, 17, 9, 0))
+
+	if n := len(s.chat.Posts()); n != 1 {
+		t.Errorf("posts = %d, want the one refused", n)
+	}
+	if s.get(w43).SentToChatAt != nil {
+		t.Error("sent_to_chat_at recorded for a refused send")
+	}
+	if got := logs.String(); !strings.Contains(got, "level=ERROR") || !strings.Contains(got, "scheduler: run failed") || !strings.Contains(got, "schedule=shopping_chat_autosend") {
+		t.Errorf("scheduler logs = %s, want the refused send logged as a failed run", got)
+	}
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.ShoppingChatAutosend), []string{"list_ready:chat:2026-10-12", "list_ready:chat:2026-10-19"})
+}
+
+func equalPtr(a, b *string) bool {
+	return (a == nil && b == nil) || (a != nil && b != nil && *a == *b)
+}
+
+// TestWeekRolloverFreezesPreviousWeek: at Monday 00:05 the schedule
+// freezes exactly the week that has just ended into the Supply archive,
+// not the week before it nor the new week; the next Monday freezes the
+// next week; a Monday whose previous week has no Supply run freezes
+// nothing and fails nothing. Its periods are week_rollover:YYYY-Www of the
+// Monday.
+func TestWeekRolloverFreezesPreviousWeek(t *testing.T) {
+	e := newEnv(t)
+	s := e.shopping()
+	s.list(w41)
+	s.list(w42)
+	s.list(w43)
+
+	status := func() []string {
+		return []string{s.get(w41).Status, s.get(w42).Status, s.get(w43).Status}
+	}
+	cur, arc := shopping.StatusCurrent, shopping.StatusArchived
+
+	// Sunday 23:00: last Monday's rollover is past the catch-up window and
+	// recorded as missed, so W41 is never frozen by it.
+	r := e.start(at(2026, 10, 18, 23, 0), s.svc.RolloverSchedule())
+	r.runUntil(at(2026, 10, 19, 0, 4))
+	wantKeys(t, "before Monday 00:05", status(), []string{cur, cur, cur})
+
+	r.runUntil(at(2026, 10, 19, 0, 5))
+	wantKeys(t, "at Monday 00:05", status(), []string{cur, arc, cur})
+	if s.get(w42).Title != nil {
+		t.Errorf("W42 title = %q, want frozen untitled", *s.get(w42).Title)
+	}
+	if _, err := s.svc.Generate(context.Background(), w42); !errors.Is(err, shopping.ErrFrozen) {
+		t.Errorf("generate W42 after the rollover: %v, want ErrFrozen", err)
+	}
+
+	r.runUntil(at(2026, 10, 26, 0, 5))
+	wantKeys(t, "next Monday", status(), []string{cur, arc, arc})
+
+	r.runUntil(at(2026, 11, 2, 0, 5))
+	s.wantLogged("week rollover froze nothing: the week has no Supply run")
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.WeekRollover), []string{"2026-W42", "2026-W43", "2026-W44", "2026-W45"})
+}
+
+// aiRun stores an ai_runs row created at created and returns its id.
+func (e *env) aiRun(created time.Time) string {
+	e.t.Helper()
+	id := store.NewID()
+	ts := store.Timestamp{Time: created.UTC()}.String()
+	if err := db.New(e.st.Writer).CreateAIRun(context.Background(), db.CreateAIRunParams{
+		ID: id, Skill: "draft_week", SkillVersion: "1", Provider: "anthropic", Model: "claude-test",
+		Temperature: 0.7, Status: "ok", RequestRedacted: "{}", ResponseRedacted: sql.NullString{String: "{}", Valid: true},
+		CreatedAt: ts, UpdatedAt: ts,
+	}); err != nil {
+		e.t.Fatal(err)
+	}
+	return id
+}
+
+// aiRuns returns the ids of the ai_runs rows, oldest first.
+func (e *env) aiRuns() []string {
+	e.t.Helper()
+	rows, err := e.st.Reader.Query(`SELECT id FROM ai_runs ORDER BY created_at`)
+	if err != nil {
+		e.t.Fatal(err)
+	}
+	defer rows.Close()
+	var ids []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			e.t.Fatal(err)
+		}
+		ids = append(ids, id)
+	}
+	if err := rows.Err(); err != nil {
+		e.t.Fatal(err)
+	}
+	return ids
+}
+
+// TestAIRunsPurgeDaily: every day at 03:00 the schedule deletes the
+// ai_runs rows created more than 30 days before, and no younger row; its
+// periods are ai_runs_purge:YYYY-MM-DD.
+func TestAIRunsPurgeDaily(t *testing.T) {
+	e := newEnv(t)
+	e.aiRun(at(2026, 9, 10, 12, 0)) // older than Sep 11 03:00
+	edge := e.aiRun(at(2026, 9, 12, 2, 59))
+	young := e.aiRun(at(2026, 9, 12, 3, 1))
+	recent := e.aiRun(at(2026, 10, 11, 12, 0))
+
+	sch, err := harness.PurgeSchedule(e.st, slog.New(slog.NewTextHandler(&syncBuffer{}, nil)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Monday 02:00: the catch-up of Sunday 03:00 purges before Sep 11 03:00.
+	r := e.start(at(2026, 10, 12, 2, 0), sch)
+	wantKeys(t, "after the catch-up", e.aiRuns(), []string{edge, young, recent})
+
+	r.runUntil(at(2026, 10, 12, 2, 59))
+	wantKeys(t, "before 03:00", e.aiRuns(), []string{edge, young, recent})
+	r.runUntil(at(2026, 10, 12, 3, 0))
+	wantKeys(t, "at 03:00", e.aiRuns(), []string{young, recent})
+	r.runUntil(at(2026, 10, 13, 3, 0))
+	wantKeys(t, "next day", e.aiRuns(), []string{recent})
+	wantKeys(t, "schedule_runs", e.claimed(scheduler.AIRunsPurge), []string{"2026-10-11", "2026-10-12", "2026-10-13"})
+}
+
+// TestPurgeScheduleRejectsNil: the purge schedule needs a store and a
+// logger.
+func TestPurgeScheduleRejectsNil(t *testing.T) {
+	e := newEnv(t)
+	if _, err := harness.PurgeSchedule(nil, slog.Default()); err == nil {
+		t.Error("nil store accepted")
+	}
+	if _, err := harness.PurgeSchedule(e.st, nil); err == nil {
+		t.Error("nil logger accepted")
+	}
+}

internal/server/aisettings_test.go

@@ -29,7 +29,7 @@ func newAIRouter(t *testing.T) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
 	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t),
-		newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/chat_test.go

@@ -86,7 +86,7 @@ func (b *lockedBuffer) String() string {
 func newChatRouter(t *testing.T, svc *chat.Service, logs io.Writer) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(logs, &slog.HandlerOptions{Level: slog.LevelDebug}))
-	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), svc, newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), svc, newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t),
 		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
@@ -233,7 +233,7 @@ func TestChatWebhookNeedsCSRF(t *testing.T) {
 func TestNewRouterRequiresChat(t *testing.T) {
 	t.Parallel()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), nil, newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil Google Chat service")
 	}
 }

internal/server/dinners.go

@@ -112,6 +112,20 @@ func postDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
 	}
 }
 
+// postPhotoBackfill starts a photo backfill over every dinner without a
+// photo and answers 202 with its job id, which GET /jobs/{id} reports on,
+// without waiting for the job.
+func postPhotoBackfill(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		id, err := svc.StartPhotoBackfill(r.Context())
+		if err != nil {
+			writeDinnerError(w, r, logger, "start photo backfill", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusAccepted, jobCreated{ID: id})
+	}
+}
+
 // patchDinner edits a dinner, recording the session's actor as updated_by.
 func patchDinner(logger *slog.Logger, svc *dinners.Service) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {

internal/server/dinners_test.go

@@ -93,12 +93,12 @@ func newDinnersEnv(t *testing.T) *dinnersEnv {
 	if err != nil {
 		t.Fatal(err)
 	}
-	svc, err := dinners.NewService(st, g, runner, logger)
+	svc, err := dinners.NewService(st, g, runner, func() {}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
 	e.h, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t),
-		svc, newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), runner, photos, fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		svc, newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), runner, photos, fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/google_test.go

@@ -69,7 +69,7 @@ func newGoogleEnv(t *testing.T) *googleEnv {
 	}
 	logger := slog.New(slog.NewJSONHandler(e.logs, &slog.HandlerOptions{Level: slog.LevelDebug}))
 	e.h, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t),
-		newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), svc, newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t),
+		newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), svc, newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t),
 		fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/grounding_test.go

@@ -556,3 +556,43 @@ func TestPostDinnerEnqueueFailureAnswersFailedDinner(t *testing.T) {
 		t.Errorf("listed = %v, want failed", got)
 	}
 }
+
+func TestPostPhotoBackfillGroundsFailedDinners(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	e.start(t)
+
+	// No model reply is scripted, so grounding on creation fails.
+	rec, created := callDinners(t, e.h, http.MethodPost, dinnersPath, `{"name":"Chicken curry"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	id := created["id"].(string)
+	waitJob(t, e.h, created["grounding_job_id"].(string))
+	if d := listedDinner(t, e.h, id); d["grounding_status"] != "failed" || d["photo_url"] != nil {
+		t.Fatalf("dinner = %v, want failed without a photo", d)
+	}
+
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	rec, started := callDinners(t, e.h, http.MethodPost, "/api/v1/settings/photo-backfill", "")
+	jobID, _ := started["id"].(string)
+	if rec.Code != http.StatusAccepted || jobID == "" {
+		t.Fatalf("POST photo-backfill = %d: %s, want 202 with a job id", rec.Code, rec.Body)
+	}
+	job := waitJob(t, e.h, jobID)
+	want := fmt.Sprintf(`map[dinners:[map[dinner_id:%s outcome:grounded reason:<nil>]]]`, id)
+	if job["status"] != "succeeded" || job["kind"] != "backfill_dinner_photos" || fmt.Sprint(job["result"]) != want {
+		t.Fatalf("job = %v, want backfill_dinner_photos succeeded with %s", job, want)
+	}
+	d := listedDinner(t, e.h, id)
+	photo, _ := d["photo_url"].(string)
+	if d["grounding_status"] != "grounded" || d["grounding_error"] != nil || !strings.HasSuffix(photo, "-400.jpg") {
+		t.Errorf("dinner = %v, want grounded with a photo", d)
+	}
+
+	// The backfill is started only by its own endpoint.
+	rec, _ = callDinners(t, e.h, http.MethodPost, "/api/v1/jobs", `{"kind":"backfill_dinner_photos","payload":{}}`)
+	if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), "service_only_kind") {
+		t.Errorf("POST /jobs backfill = %d: %s, want 400 service_only_kind", rec.Code, rec.Body)
+	}
+}

internal/server/home.go

@@ -0,0 +1,85 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/home"
+)
+
+// getHome answers GET /home with the Home screen at the household's local
+// "now".
+func getHome(logger *slog.Logger, svc *home.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		h, err := svc.Get(r.Context())
+		if err != nil {
+			logger.ErrorContext(r.Context(), "read home", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, h)
+	}
+}
+
+// updatesBody is the GET /updates answer.
+type updatesBody struct {
+	Updates []home.Update `json:"updates"`
+}
+
+// getUpdates answers GET /updates with the Recent updates: the last
+// home.RecentLimit distinct notification events, newest first.
+func getUpdates(logger *slog.Logger, svc *home.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		updates, err := svc.Updates(r.Context())
+		if err != nil {
+			logger.ErrorContext(r.Context(), "read recent updates", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, updatesBody{Updates: updates})
+	}
+}
+
+// maxUpdatesSeenBody bounds a POST /updates/seen request body.
+const maxUpdatesSeenBody = 1 << 10
+
+// updatesSeenRequest is the POST /updates/seen body: through is the
+// created_at of the newest update the household was shown.
+type updatesSeenRequest struct {
+	Through *string `json:"through"`
+}
+
+// postUpdatesSeen answers POST /updates/seen by recording that the
+// household has seen its updates through the body's through, and answers
+// 204. A through before the one already recorded changes nothing.
+func postUpdatesSeen(logger *slog.Logger, svc *home.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		req, err := decodePatch[updatesSeenRequest](http.MaxBytesReader(w, r.Body, maxUpdatesSeenBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		if req.Through == nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", "through: required")
+			return
+		}
+		through, err := time.Parse(time.RFC3339Nano, *req.Through)
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", "through: want an RFC 3339 timestamp")
+			return
+		}
+		err = svc.MarkUpdatesSeen(r.Context(), through)
+		if errors.Is(err, home.ErrSeenInFuture) {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", "through: must not be after now")
+			return
+		}
+		if err != nil {
+			logger.ErrorContext(r.Context(), "mark recent updates seen", "error", err)
+			writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+			return
+		}
+		w.WriteHeader(http.StatusNoContent)
+	}
+}

internal/server/home_test.go

@@ -0,0 +1,245 @@
+package server
+
+import (
+	"database/sql"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// GET /home answers the Home screen in its JSON shape; newTestHome's
+// household (America/New_York) has no plan, no suggestions, no Supply run
+// and no notifications.
+func TestGetHome(t *testing.T) {
+	t.Parallel()
+	h := newTestRouter(t, "dev")
+	loc, err := time.LoadLocation("America/New_York")
+	if err != nil {
+		t.Fatal(err)
+	}
+	// want is the answer at instant now; the request is read between two
+	// instants, so it matches the answer at one of them.
+	want := func(now time.Time) string {
+		week := household.WeekStart(household.Today(now, loc))
+		label, err := household.WeekLabel(week)
+		if err != nil {
+			t.Fatal(err)
+		}
+		body, err := json.Marshal(map[string]any{
+			"dateLabel":      now.In(loc).Format("Monday, Jan 2"),
+			"timezone":       loc.String(),
+			"tonight":        nil,
+			"sideQuestCount": 0,
+			"shoppingList":   map[string]any{"weekStart": week.String(), "label": label, "ready": false, "sentToChatAt": nil},
+			"recentUpdates":  map[string]any{"unread": false},
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return string(body)
+	}
+	before := time.Now()
+	rec, _ := serve(t, h, signedIn(http.MethodGet, "/api/v1/home", nil))
+	after := time.Now()
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET /api/v1/home = %d: %s", rec.Code, rec.Body)
+	}
+	var got any
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	canonical, err := json.Marshal(got)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(canonical) != want(before) && string(canonical) != want(after) {
+		t.Errorf("GET /api/v1/home = %s, want %s", canonical, want(after))
+	}
+}
+
+func TestGetHomeNeedsSession(t *testing.T) {
+	t.Parallel()
+	rec := httptest.NewRecorder()
+	newTestRouter(t, "dev").ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/v1/home", nil))
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("GET /api/v1/home without a session = %d, want 401", rec.Code)
+	}
+}
+
+// homeRouter returns a router whose Home reads st, and st.
+func homeRouter(t *testing.T) (http.Handler, *store.Store) {
+	t.Helper()
+	st := newTestStore(t)
+	svc := newTestHomeOn(t, st)
+	return newTestRouterWithHome(t, "dev", newTestSettings(t), newTestRunner(t), svc), st
+}
+
+// storeEvent stores event key in st's outbox at instant at for each of
+// channels, as notify stores an event, and returns at as stored.
+func storeEvent(t *testing.T, st *store.Store, typ notify.EventType, key, title string, at time.Time, channels ...notify.Channel) string {
+	t.Helper()
+	payload, err := json.Marshal(notify.Payload{Event: typ, Title: title, Body: "Body of " + key, URL: "/plan", Tag: key})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ts := store.Timestamp{Time: at.UTC().Truncate(time.Millisecond)}.String()
+	for _, ch := range channels {
+		if _, err := db.New(st.Writer).InsertNotification(t.Context(), db.InsertNotificationParams{
+			ID: store.NewID(), EventKey: key, Channel: string(ch), Payload: string(payload),
+			NextAttemptAt: sql.NullString{String: ts, Valid: true}, Now: ts,
+		}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return ts
+}
+
+// unread reads recentUpdates.unread from GET /home.
+func unread(t *testing.T, h http.Handler) bool {
+	t.Helper()
+	rec, body := serve(t, h, signedIn(http.MethodGet, "/api/v1/home", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET /api/v1/home = %d: %s", rec.Code, rec.Body)
+	}
+	updates, ok := body["recentUpdates"].(map[string]any)
+	if !ok {
+		t.Fatalf("GET /api/v1/home has no recentUpdates: %s", rec.Body)
+	}
+	return updates["unread"] == true
+}
+
+// markSeen posts body to /updates/seen and returns the answer.
+func markSeen(t *testing.T, h http.Handler, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, signedIn(http.MethodPost, "/api/v1/updates/seen", strings.NewReader(body)))
+	return rec
+}
+
+// GET /updates lists the last distinct events newest first, one per event
+// whatever its channels, in their JSON shape.
+func TestGetUpdates(t *testing.T) {
+	t.Parallel()
+	h, st := homeRouter(t)
+
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, signedIn(http.MethodGet, "/api/v1/updates", nil))
+	if rec.Code != http.StatusOK || rec.Body.String() != `{"updates":[]}` {
+		t.Errorf("GET /api/v1/updates with none = %d %s, want 200 {\"updates\":[]}", rec.Code, rec.Body)
+	}
+
+	now := time.Now()
+	older := storeEvent(t, st, notify.NewSuggestions, "new_suggestions:1", "New Side quests", now.Add(-2*time.Minute), notify.ChannelPush)
+	newer := storeEvent(t, st, notify.PlanReady, "plan_ready:2026-10-12", "Your week is drafted", now.Add(-time.Minute), notify.ChannelPush, notify.ChannelChat)
+
+	rec = httptest.NewRecorder()
+	h.ServeHTTP(rec, signedIn(http.MethodGet, "/api/v1/updates", nil))
+	want := `{"updates":[` +
+		`{"type":"plan_ready","title":"Your week is drafted","body":"Body of plan_ready:2026-10-12","url":"/plan","created_at":"` + newer + `"},` +
+		`{"type":"new_suggestions","title":"New Side quests","body":"Body of new_suggestions:1","url":"/plan","created_at":"` + older + `"}]}`
+	if rec.Code != http.StatusOK || rec.Body.String() != want {
+		t.Errorf("GET /api/v1/updates = %d %s, want 200 %s", rec.Code, rec.Body, want)
+	}
+}
+
+// Unread is true while an event newer than the last seen one exists,
+// clears once POST /updates/seen marks the newest seen, and returns when a
+// newer event is stored; marking an older one seen again moves nothing.
+func TestUpdatesSeen(t *testing.T) {
+	t.Parallel()
+	h, st := homeRouter(t)
+	now := time.Now()
+
+	if unread(t, h) {
+		t.Error("unread with no events")
+	}
+	first := storeEvent(t, st, notify.PlanReady, "plan_ready:1", "Drafted", now.Add(-2*time.Minute), notify.ChannelPush, notify.ChannelChat)
+	if !unread(t, h) {
+		t.Error("not unread with an event never seen")
+	}
+	if rec := markSeen(t, h, `{"through":"`+first+`"}`); rec.Code != http.StatusNoContent || rec.Body.Len() != 0 {
+		t.Fatalf("POST /api/v1/updates/seen = %d %s, want 204", rec.Code, rec.Body)
+	}
+	if unread(t, h) {
+		t.Error("unread after the newest event was marked seen")
+	}
+
+	second := storeEvent(t, st, notify.ListReady, "list_ready:2", "Supply run ready", now.Add(-time.Minute), notify.ChannelPush)
+	if !unread(t, h) {
+		t.Error("not unread with an event newer than the last seen")
+	}
+	// Already seen: marking the older event seen again is accepted and
+	// changes nothing.
+	if rec := markSeen(t, h, `{"through":"`+first+`"}`); rec.Code != http.StatusNoContent {
+		t.Fatalf("POST /api/v1/updates/seen of an older event = %d %s, want 204", rec.Code, rec.Body)
+	}
+	if !unread(t, h) {
+		t.Error("marking an older event seen hid a newer one")
+	}
+	if rec := markSeen(t, h, `{"through":"`+second+`"}`); rec.Code != http.StatusNoContent {
+		t.Fatalf("POST /api/v1/updates/seen = %d %s, want 204", rec.Code, rec.Body)
+	}
+	if unread(t, h) {
+		t.Error("unread after the newer event was marked seen")
+	}
+}
+
+// A malformed POST /updates/seen is 400 and records nothing.
+func TestUpdatesSeenRejectsMalformed(t *testing.T) {
+	t.Parallel()
+	h, st := homeRouter(t)
+	storeEvent(t, st, notify.PlanReady, "plan_ready:1", "Drafted", time.Now().Add(-time.Minute), notify.ChannelPush)
+
+	for _, body := range []string{
+		``,
+		`[]`,
+		`{}`,
+		`{"through":null}`,
+		`{"through":42}`,
+		`{"through":"yesterday"}`,
+		`{"through":"2026-10-13 12:00:00"}`,
+		`{"through":"2026-10-13T12:00:00.000Z","extra":true}`,
+		`{"through":"2026-10-13T12:00:00.000Z"} {}`,
+		`{"through":"` + time.Now().Add(time.Hour).UTC().Format(time.RFC3339Nano) + `"}`,
+	} {
+		rec := markSeen(t, h, body)
+		if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), `"invalid_request"`) {
+			t.Errorf("POST /api/v1/updates/seen %q = %d %s, want 400 invalid_request", body, rec.Code, rec.Body)
+		}
+	}
+	if !unread(t, h) {
+		t.Error("a malformed POST /updates/seen marked updates seen")
+	}
+}
+
+// Both endpoints need a session, and POST /updates/seen the CSRF token.
+func TestUpdatesNeedSessionAndCSRF(t *testing.T) {
+	t.Parallel()
+	h, _ := homeRouter(t)
+	body := `{"through":"2026-10-01T12:00:00.000Z"}`
+	for _, req := range []*http.Request{
+		httptest.NewRequest(http.MethodGet, "/api/v1/updates", nil),
+		httptest.NewRequest(http.MethodPost, "/api/v1/updates/seen", strings.NewReader(body)),
+	} {
+		rec := httptest.NewRecorder()
+		h.ServeHTTP(rec, req)
+		if rec.Code != http.StatusUnauthorized {
+			t.Errorf("%s %s without a session = %d, want 401", req.Method, req.URL.Path, rec.Code)
+		}
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/updates/seen", strings.NewReader(body))
+	req.AddCookie(validSessionCookie)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("POST /api/v1/updates/seen without the CSRF token = %d, want 403", rec.Code)
+	}
+}

internal/server/ideaactions_test.go

@@ -65,7 +65,7 @@ func newIdeaActionsRouter(t *testing.T, model, normalize *llm.Fake, search *reci
 	if err != nil {
 		t.Fatal(err)
 	}
-	dinnerSvc, err := dinners.NewService(st, g, runner, logger)
+	dinnerSvc, err := dinners.NewService(st, g, runner, func() {}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -73,12 +73,12 @@ func newIdeaActionsRouter(t *testing.T, model, normalize *llm.Fake, search *reci
 		t.Error("draft_week ran: an idea action must never draft a plan")
 		return skills.Week{}, context.Canceled
 	}
-	planSvc, err := plan.NewService(st, draft, runner, newTestGoogle(t), notifytest.New(t, st), &url.URL{Scheme: "https", Host: "mealquest.example"}, logger)
+	planSvc, err := plan.NewService(st, draft, runner, newTestGoogle(t), notifytest.New(t, st), func() {}, &url.URL{Scheme: "https", Host: "mealquest.example"}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
 	h, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t),
-		dinnerSvc, newTestSuggest(t), planSvc, newTestShopping(t), newTestGoogle(t), newTestPush(t), ideasSvc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		dinnerSvc, newTestSuggest(t), planSvc, newTestShopping(t), newTestGoogle(t), newTestPush(t), ideasSvc, newTestHome(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/ideas_test.go

@@ -66,7 +66,7 @@ func newIdeasRouter(t *testing.T, model, normalize *llm.Fake, search *recipestes
 		t.Fatal(err)
 	}
 	h, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t),
-		newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), svc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), svc, newTestHome(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/ideasource_test.go

@@ -0,0 +1,197 @@
+package server
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ideas"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+)
+
+// sourceCase is a recipe page an idea grounds in: its link and the site
+// name its page gives (empty for none, so the host is stored instead).
+type sourceCase struct {
+	dish, link, site string
+	// want is the idea's source_url and site_name; nil is null.
+	wantURL, wantSite any
+}
+
+const (
+	cleanSourceLink = "https://kitchen.example/recipes/chicken-curry"
+	queryToken      = "query-token-abc123"
+	queryHost       = "query-host-q1.example"
+	userinfoToken   = "user-token-def456"
+	userinfoHost    = "userinfo-host-u2.example"
+)
+
+// sourceCases are a clean link, credited by its page's name, and links
+// carrying a token in the query and the userinfo whose pages name no site,
+// so the stored name is the link's host.
+var sourceCases = []sourceCase{
+	{"Chicken Curry", cleanSourceLink, "Curry House", cleanSourceLink, "Curry House"},
+	{"Beef Stew", "https://" + queryHost + "/stew?access_token=" + queryToken, "", nil, nil},
+	{"Bean Chili", "https://" + userinfoToken + "@" + userinfoHost + "/chili", "", nil, nil},
+}
+
+// sourceSecrets are what no idea job response may contain.
+var sourceSecrets = []string{queryToken, "access_token", queryHost, userinfoToken, userinfoHost}
+
+// sourceFakes makes the search for each case's dish find its page and
+// scripts the normalize_recipe reply grounding it takes.
+func sourceFakes(t *testing.T, minutes int) (*llm.Fake, *llm.Fake, *recipestest.Search, *recipestest.Pages, *recipestest.Images) {
+	t.Helper()
+	model, normalize, search, pages, images := newQuickFakes()
+	for i, c := range sourceCases {
+		photo := fmt.Sprintf("https://img.example/%d.jpg", i)
+		search.Results[c.dish] = []recipes.Candidate{{URL: c.link}}
+		pages.Bodies[c.link] = recipestest.RecipePage(c.dish, c.site, photo, minutes)
+		images.JPEGs[photo] = recipestest.JPEG(t, 400, 320, uint8(i+1))
+		normalize.QueueGenerate(recipestest.NormalizedReply("stovetop", minutes))
+	}
+	return model, normalize, search, pages, images
+}
+
+// checkIdeaSources checks the finished job id: each idea shows its case's
+// safe source, and the response holds nothing of a token-bearing link.
+func checkIdeaSources(t *testing.T, h http.Handler, id string) {
+	t.Helper()
+	job := waitJob(t, h, id)
+	if job["status"] != "succeeded" {
+		t.Fatalf("GET job = %v", job)
+	}
+	rec, _ := callDinners(t, h, http.MethodGet, "/api/v1/jobs/"+id, "")
+	for _, secret := range sourceSecrets {
+		if strings.Contains(rec.Body.String(), secret) {
+			t.Errorf("job response contains %q: %s", secret, rec.Body)
+		}
+	}
+	list := job["result"].(map[string]any)["ideas"].([]any)
+	if len(list) != len(sourceCases) {
+		t.Fatalf("ideas = %v, want %d", list, len(sourceCases))
+	}
+	for i, c := range sourceCases {
+		idea := list[i].(map[string]any)
+		if idea["name"] != c.dish {
+			t.Fatalf("idea %d = %v, want %s", i, idea, c.dish)
+		}
+		for key, want := range map[string]any{"source_url": c.wantURL, "site_name": c.wantSite} {
+			got, ok := idea[key]
+			if !ok || !reflect.DeepEqual(got, want) {
+				t.Errorf("%s %s = %v (present %t), want %v", c.dish, key, got, ok, want)
+			}
+		}
+		if idea["recipe_id"] == "" || idea["photo_url"] == "" {
+			t.Errorf("idea %s = %v, want a recipe and photo", c.dish, idea)
+		}
+	}
+}
+
+// An ideas_from_ingredients job shows a clean link and its page's name,
+// and neither a token-bearing link nor a name taken from its host.
+func TestIdeasJobShowsOnlySafeSources(t *testing.T) {
+	t.Parallel()
+	model, normalize, search, pages, images := sourceFakes(t, 25)
+	list := make([]string, len(sourceCases))
+	for i, c := range sourceCases {
+		list[i] = fmt.Sprintf(`{"name":%q,"uses":["rice"],"missing":[],"est_minutes":25,"method":"stovetop","difficulty":"easy","search_query":%q}`, c.dish, c.dish)
+	}
+	js := `{"ideas":[` + strings.Join(list, ",") + `]}`
+	model.QueueGenerate(llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}})
+	h, _, _ := newIdeasRouter(t, model, normalize, search, pages, images, true)
+	checkIdeaSources(t, h, startIdeasJob(t, h))
+}
+
+// A quick_ideas job shows sources as an ideas_from_ingredients job does.
+func TestQuickJobShowsOnlySafeSources(t *testing.T) {
+	t.Parallel()
+	model, normalize, search, pages, images := sourceFakes(t, 25)
+	ideas := make([][3]any, len(sourceCases))
+	for i, c := range sourceCases {
+		ideas[i] = [3]any{c.dish, "stovetop", 20}
+	}
+	quickReply(model, ideas...)
+	h, _, _ := newIdeasRouter(t, model, normalize, search, pages, images, true)
+	rec, body := callDinners(t, h, http.MethodPost, quickPath, `{"kind": "under30", "exclude": []}`)
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	checkIdeaSources(t, h, body["jobId"].(string))
+}
+
+// legacyIdea is an idea as the result builders stored it before sources
+// were made safe: the grounded recipe's raw link and stored site name,
+// which is the link's host when its page named no site.
+func legacyIdea(name, link, site string) map[string]any {
+	return map[string]any{
+		"name": name, "method": "stovetop", "minutes_total": 25, "difficulty": "easy",
+		"recipe_id": "01JLEGACY" + strings.ToUpper(strings.ReplaceAll(name, " ", "")), "photo_url": "/api/v1/photos/legacy",
+		"source_url": link, "site_name": site,
+	}
+}
+
+// A job of either idea kind whose result was stored before sources were
+// made safe is served with the sources a job stored now holds: neither a
+// token-bearing link nor a name taken from its host.
+func TestJobServesLegacyIdeaResultsWithOnlySafeSources(t *testing.T) {
+	t.Parallel()
+	model, normalize, search, pages, images := newQuickFakes()
+	h, _, st := newIdeasRouter(t, model, normalize, search, pages, images, false)
+	legacy := []any{
+		legacyIdea("Chicken Curry", cleanSourceLink, "Curry House"),
+		legacyIdea("Beef Stew", "https://"+queryHost+"/stew?access_token="+queryToken, queryHost),
+		legacyIdea("Bean Chili", "https://"+userinfoToken+"@"+userinfoHost+"/chili", userinfoHost),
+	}
+	for kind, result := range map[string]map[string]any{
+		ideas.KindFromIngredients: {"stage": "done", "ingredients": []string{"rice"}, "quick_only": false, "ideas": legacy, "dropped": 0},
+		ideas.KindQuick:           {"stage": "done", "kind": "under30", "exclude": []string{}, "ideas": legacy, "dropped": 0},
+	} {
+		js, err := json.Marshal(result)
+		if err != nil {
+			t.Fatal(err)
+		}
+		id := "legacy-" + kind
+		if _, err := st.Writer.ExecContext(t.Context(),
+			`INSERT INTO jobs (id, kind, status, payload, result, created_at, updated_at) VALUES (?, ?, 'succeeded', '{}', ?, '2026-10-01T00:00:00Z', '2026-10-01T00:00:00Z')`,
+			id, kind, string(js)); err != nil {
+			t.Fatal(err)
+		}
+		checkIdeaSources(t, h, id)
+	}
+}
+
+// An idea job whose grounded recipe's stored link does not parse fails,
+// even when no site name is stored, rather than show the idea without a
+// source.
+func TestIdeaJobFailsOnUnparseableSourceWithoutSiteName(t *testing.T) {
+	t.Parallel()
+	const badLink = "https://kitchen.example/%zz"
+	model, normalize, search, pages, images := sourceFakes(t, 25)
+	idea := fmt.Sprintf(`{"name":%q,"uses":["rice"],"missing":[],"est_minutes":25,"method":"stovetop","difficulty":"easy","search_query":%q}`, sourceCases[0].dish, sourceCases[0].dish)
+	js := `{"ideas":[` + idea + `]}`
+	for range 2 {
+		model.QueueGenerate(llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}})
+	}
+	h, _, st := newIdeasRouter(t, model, normalize, search, pages, images, true)
+	if job := waitJob(t, h, startIdeasJob(t, h)); job["status"] != "succeeded" {
+		t.Fatalf("grounding job = %v", job)
+	}
+	// The recipe is now stored under badLink with no site name, and the
+	// search finds it there.
+	res, err := st.Writer.ExecContext(t.Context(), `UPDATE recipes SET source_url = ?, site_name = NULL WHERE source_url = ?`, badLink, cleanSourceLink)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n, err := res.RowsAffected(); err != nil || n != 1 {
+		t.Fatalf("updated %d recipes (%v), want 1", n, err)
+	}
+	search.Results[sourceCases[0].dish] = []recipes.Candidate{{URL: badLink}}
+	job := waitJob(t, h, startIdeasJob(t, h))
+	assertFailedWithoutIdeas(t, job, jobs.CodeInternal)
+}

internal/server/login_test.go

@@ -83,7 +83,7 @@ func newLoginRouter(t *testing.T, issuer string) http.Handler {
 		t.Fatal(err)
 	}
 	r, err := NewRouter(logger, "dev", trusted, flow, sessions, newTestSettings(t),
-		newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/media_test.go

@@ -51,7 +51,7 @@ func newMediaRouter(t *testing.T) (r http.Handler, id, orphan string) {
 		t.Fatal(err)
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t),
+	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t),
 		photos, fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/origin_test.go

@@ -45,7 +45,7 @@ func newOriginRouter(t *testing.T, logs io.Writer) http.Handler {
 	}
 	logger := slog.New(forwarded.LogHandler(slog.NewJSONHandler(logs, nil)))
 	r, err := NewRouter(logger, "dev", trusted, probeAuth{}, stubSessions{}, newTestSettings(t),
-		newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/plans_test.go

@@ -93,7 +93,7 @@ func newPlansRouterTitled(t *testing.T, title shopping.Titler) plansEnv {
 		t.Fatal(err)
 	}
 	notifier := notifytest.New(t, st)
-	svc, err := plan.NewService(st, fail, runner, googleSvc, notifier, pub, logger)
+	svc, err := plan.NewService(st, fail, runner, googleSvc, notifier, func() {}, pub, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -107,7 +107,7 @@ func newPlansRouterTitled(t *testing.T, title shopping.Titler) plansEnv {
 		t.Fatal(err)
 	}
 	h, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), chatSvc,
-		newTestDinners(t), newTestSuggest(t), svc, shop, googleSvc, newTestPush(t), newTestIdeas(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestDinners(t), newTestSuggest(t), svc, shop, googleSvc, newTestPush(t), newTestIdeas(t), newTestHome(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/push_test.go

@@ -55,7 +55,7 @@ func newTestPushWith(t *testing.T) (*push.Service, *store.Store, vapid.KeyPair)
 func newPushRouter(t *testing.T, svc *push.Service) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), svc, newTestIdeas(t), newTestRunner(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), svc, newTestIdeas(t), newTestHome(t), newTestRunner(t),
 		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
@@ -103,7 +103,7 @@ func TestNewRouterRequiresPush(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), nil, newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), nil, newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil push service")
 	}
 }

internal/server/recipesearch_test.go

@@ -22,7 +22,7 @@ const (
 func newRecipeSearchRouter(t *testing.T, search *recipes.SearchSettingsService) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t),
 		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/server.go

@@ -16,6 +16,7 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/forwarded"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/gcal"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/home"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ideas"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
@@ -66,12 +67,13 @@ type RouteMounter interface {
 // /api/v1/settings/notifications/test-push; ideasSvc serves POST
 // /api/v1/ideas/from-ingredients and POST /api/v1/ideas/quick, and with
 // dinnerSvc POST /api/v1/ideas/{jobId}/items/{i}/quest-log and, with
-// planSvc too, /cook-tonight; runner serves
+// planSvc too, /cook-tonight; homeSvc serves GET /api/v1/home, GET
+// /api/v1/updates and POST /api/v1/updates/seen; runner serves
 // POST /api/v1/jobs and GET /api/v1/jobs/{id}; photos serves
 // GET /media/photos/{id}-{size}.jpg; assets is the web build
 // served for every other GET. /health, /auth and the web build are public.
 // Requests to /api/v1 other than GET also need the session's CSRF token in CSRFHeader.
-func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, search *recipes.SearchSettingsService, ai *aisettings.Service, chatSvc *chat.Service, dinnerSvc *dinners.Service, suggestSvc *suggest.Service, planSvc *plan.Service, shopSvc *shopping.Service, googleSvc *gcal.Service, pushSvc *push.Service, ideasSvc *ideas.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
+func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, auth RouteMounter, sessions SessionLookup, settings *household.SettingsService, search *recipes.SearchSettingsService, ai *aisettings.Service, chatSvc *chat.Service, dinnerSvc *dinners.Service, suggestSvc *suggest.Service, planSvc *plan.Service, shopSvc *shopping.Service, googleSvc *gcal.Service, pushSvc *push.Service, ideasSvc *ideas.Service, homeSvc *home.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
 	if settings == nil {
 		return nil, errors.New("server: nil household settings service")
 	}
@@ -105,6 +107,9 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	if ideasSvc == nil {
 		return nil, errors.New("server: nil ideas service")
 	}
+	if homeSvc == nil {
+		return nil, errors.New("server: nil home service")
+	}
 	if runner == nil {
 		return nil, errors.New("server: nil job runner")
 	}
@@ -137,6 +142,9 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 		sub.NotFound(notFound)
 	}
 	apiV1.Get("/me", me(logger))
+	apiV1.Get("/home", getHome(logger, homeSvc))
+	apiV1.Get("/updates", getUpdates(logger, homeSvc))
+	apiV1.Post("/updates/seen", postUpdatesSeen(logger, homeSvc))
 	apiV1.Get("/settings/household", getHouseholdSettings(logger, settings))
 	apiV1.Patch("/settings/household", patchHouseholdSettings(logger, settings))
 	apiV1.Get("/settings/notifications", getNotificationSettings(logger, settings))
@@ -154,6 +162,7 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	apiV1.Get("/settings/chat-webhook", getChatWebhook(logger, chatSvc))
 	apiV1.Put("/settings/chat-webhook", putChatWebhook(logger, chatSvc))
 	apiV1.Post("/settings/chat-webhook/test", postChatWebhookTest(logger, chatSvc))
+	apiV1.Post("/settings/photo-backfill", postPhotoBackfill(logger, dinnerSvc))
 	apiV1.Get("/dinners", getDinners(logger, dinnerSvc))
 	apiV1.Post("/dinners", postDinner(logger, dinnerSvc))
 	apiV1.Get("/dinners/{id}", getDinner(logger, dinnerSvc))

internal/server/server_test.go

@@ -22,8 +22,10 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/aisettings"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/chat"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/gcal"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/home"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ideas"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
@@ -50,13 +52,19 @@ func newTestRouter(t *testing.T, version string) http.Handler {
 }
 
 func newTestRouterWith(t *testing.T, version string, settings *household.SettingsService, runner *jobs.Runner) http.Handler {
+	t.Helper()
+	return newTestRouterWithHome(t, version, settings, runner, newTestHome(t))
+}
+
+// newTestRouterWithHome is newTestRouterWith serving Home from homeSvc.
+func newTestRouterWithHome(t *testing.T, version string, settings *household.SettingsService, runner *jobs.Runner, homeSvc *home.Service) http.Handler {
 	t.Helper()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
 	assets := fstest.MapFS{
 		"index.html":             {Data: []byte(fixtureIndex)},
 		"assets/index-AbC123.js": {Data: []byte(fixtureAsset)},
 	}
-	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), runner, newTestPhotos(t), assets)
+	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), homeSvc, runner, newTestPhotos(t), assets)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -166,7 +174,7 @@ func newTestDinners(t *testing.T) *dinners.Service {
 		t.Fatal(err)
 	}
 	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
-	svc, err := dinners.NewService(st, g, runner, logger)
+	svc, err := dinners.NewService(st, g, runner, func() {}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -232,7 +240,7 @@ func newTestPlan(t *testing.T) *plan.Service {
 	fail := func(context.Context, string, skills.WeekRequest) (skills.Week, error) {
 		return skills.Week{}, errors.New("no model in this test")
 	}
-	svc, err := plan.NewService(st, fail, runner, newTestGoogle(t), notifytest.New(t, st), &url.URL{Scheme: "https", Host: "mealquest.example"}, logger)
+	svc, err := plan.NewService(st, fail, runner, newTestGoogle(t), notifytest.New(t, st), func() {}, &url.URL{Scheme: "https", Host: "mealquest.example"}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -257,6 +265,71 @@ func newTestShopping(t *testing.T) *shopping.Service {
 	return svc
 }
 
+// newTestHome returns a home service whose services all share one
+// migrated temp database with zone America/New_York, with an unstarted job
+// runner, no model, and Google and Google Chat endpoints that refuse every
+// connection. One database keeps the routers that never ask for Home cheap.
+func newTestHome(t *testing.T) *home.Service {
+	t.Helper()
+	return newTestHomeOn(t, newTestStore(t))
+}
+
+// newTestHomeOn returns a home service over st, a migrated database, which
+// it seeds with zone America/New_York and the seed notification preferences.
+func newTestHomeOn(t *testing.T, st *store.Store) *home.Service {
+	t.Helper()
+	if err := household.SeedSettings(context.Background(), st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	notifier := notifytest.New(t, st)
+	draft := func(context.Context, string, skills.WeekRequest) (skills.Week, error) {
+		return skills.Week{}, errors.New("no model in this test")
+	}
+	pub := &url.URL{Scheme: "https", Host: "mealquest.example"}
+	googleSvc, err := gcal.NewService(st, newTestBox(t), gcal.Config{
+		ClientID:     "client-id",
+		ClientSecret: "client-secret",
+		PublicURL:    pub,
+		SecretKey:    []byte("server-secret-key"),
+		Endpoint:     oauth2.Endpoint{AuthURL: "http://127.0.0.1:1/auth", TokenURL: "http://127.0.0.1:1/token"},
+		RevokeURL:    "http://127.0.0.1:1/revoke",
+		CalendarAPI:  "http://127.0.0.1:1/calendar/v3",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	planSvc, err := plan.NewService(st, draft, runner, googleSvc, notifier, func() {}, pub, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	sideQuests := func(context.Context, string, skills.SideQuestsRequest) (skills.SideQuests, error) {
+		return skills.SideQuests{}, errors.New("no model in this test")
+	}
+	suggestSvc, err := suggest.NewService(st, g, sideQuests, runner, notifier, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	chatSvc, err := chat.NewService(st, newTestBox(t), pub, refuseTransport{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	shop, err := shopping.NewService(st, untitled, runner, notifier, chatSvc, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	svc, err := home.NewService(household.NewSettingsService(st), planSvc, suggestSvc, shop, notifier)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return svc
+}
+
 // untitled is a shopping.Titler with no model: every Supply run it is
 // asked to title stays untitled.
 func untitled(context.Context, string, skills.ArchiveTitleRequest) (skills.ArchiveTitle, error) {
@@ -317,7 +390,7 @@ func TestNewRouterRequiresAISettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil AI settings service")
 	}
 }
@@ -326,7 +399,7 @@ func TestNewRouterRequiresSearchSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil recipe search settings service")
 	}
 }
@@ -335,7 +408,7 @@ func TestNewRouterRequiresPhotoFiles(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted nil photo files")
 	}
 }
@@ -344,7 +417,7 @@ func TestNewRouterRequiresSettings(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil settings service")
 	}
 }
@@ -353,7 +426,7 @@ func TestNewRouterRequiresDinners(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), nil, newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), nil, newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil dinners service")
 	}
 }
@@ -362,7 +435,7 @@ func TestNewRouterRequiresSuggestions(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), nil, newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), nil, newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil suggestions service")
 	}
 }
@@ -371,7 +444,7 @@ func TestNewRouterRequiresPlan(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), nil, newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), nil, newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil plan service")
 	}
 }
@@ -380,7 +453,7 @@ func TestNewRouterRequiresShopping(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), nil, newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), nil, newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil shopping service")
 	}
 }
@@ -389,16 +462,25 @@ func TestNewRouterRequiresIdeas(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), nil, newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil ideas service")
 	}
 }
 
+func TestNewRouterRequiresHome(t *testing.T) {
+	t.Parallel()
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil home service")
+	}
+}
+
 func TestNewRouterRequiresGoogle(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), nil, newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), nil, newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil Google Calendar service")
 	}
 }
@@ -407,7 +489,7 @@ func TestNewRouterRequiresJobRunner(t *testing.T) {
 	t.Parallel()
 
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil job runner")
 	}
 }

internal/server/settings_test.go

@@ -277,7 +277,7 @@ func TestHouseholdSettingsWithRealSession(t *testing.T) {
 	}
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
 	router, err := NewRouter(logger, "dev", nil, stubAuth{}, sessions, household.NewSettingsService(st),
-		newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestChat(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/suggestions_test.go

@@ -46,7 +46,7 @@ func newSuggestionsRouter(t *testing.T, names ...string) (http.Handler, *store.S
 		t.Fatal(err)
 	}
 	h, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestChat(t),
-		newTestDinners(t), svc, newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestDinners(t), svc, newTestPlan(t), newTestShopping(t), newTestGoogle(t), newTestPush(t), newTestIdeas(t), newTestHome(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/shopping/archive.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"strconv"
+	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
@@ -39,11 +40,17 @@ const (
 // only when no job is running it. A job that runs after the freeze finds
 // the list titled, or frozen untitled, and stores nothing.
 func (s *Service) Freeze(ctx context.Context, weekStart store.LocalDate) error {
+	return s.freeze(ctx, weekStart, s.now())
+}
+
+// freeze is Freeze with the week ended by instant now rather than by the
+// service's clock.
+func (s *Service) freeze(ctx context.Context, weekStart store.LocalDate, now time.Time) error {
 	if _, err := household.WeekDays(weekStart); err != nil {
 		return fmt.Errorf("shopping: freeze: %w", err)
 	}
 	q := db.New(s.st.Writer)
-	thisWeek, err := s.thisWeek(ctx, q)
+	thisWeek, err := weekAt(ctx, q, now)
 	if err != nil {
 		return err
 	}
@@ -73,9 +80,9 @@ func (s *Service) Freeze(ctx context.Context, weekStart store.LocalDate) error {
 		}
 	}
 	// A list frozen meanwhile is left as it is: the freeze is done.
-	now := store.Now().String()
+	stamp := store.Now().String()
 	if _, err := q.FreezeShoppingList(ctx, db.FreezeShoppingListParams{
-		FrozenAt: sql.NullString{String: now, Valid: true}, UpdatedAt: now, ID: list.ID,
+		FrozenAt: sql.NullString{String: stamp, Valid: true}, UpdatedAt: stamp, ID: list.ID,
 	}); err != nil {
 		return fmt.Errorf("shopping: freeze %s: %w", weekStart, err)
 	}
@@ -103,6 +110,12 @@ func freezeTitleJob(ctx context.Context, q *db.Queries, list db.ShoppingList) (T
 // thisWeek returns the Monday of the household's current week, in its
 // time zone, by the service's clock.
 func (s *Service) thisWeek(ctx context.Context, q *db.Queries) (store.LocalDate, error) {
+	return weekAt(ctx, q, s.now())
+}
+
+// weekAt returns the Monday of the household's week at instant t, in its
+// time zone.
+func weekAt(ctx context.Context, q *db.Queries, t time.Time) (store.LocalDate, error) {
 	settings, err := q.GetHouseholdSettings(ctx)
 	if err != nil {
 		return store.LocalDate{}, fmt.Errorf("shopping: read household settings: %w", err)
@@ -111,7 +124,7 @@ func (s *Service) thisWeek(ctx context.Context, q *db.Queries) (store.LocalDate,
 	if err != nil {
 		return store.LocalDate{}, fmt.Errorf("shopping: household settings: %w", err)
 	}
-	return household.WeekStart(household.Today(s.now(), zone)), nil
+	return household.WeekStart(household.Today(t, zone)), nil
 }
 
 // Period is one heading of the Supply archive and its posts, newest first.

internal/shopping/notify_test.go

@@ -37,9 +37,9 @@ func TestGenerateEmitsListReadyOnce(t *testing.T) {
 	}
 	for _, r := range rows {
 		p := r.Payload
-		if r.Key != "list_ready:2026-10-12" || p.URL != "/plan/shopping" || p.Week != "2026-10-12" ||
+		if r.Key != "list_ready:2026-10-12" || p.URL != "/plan/shopping?week=2026-10-12" || p.Week != "2026-10-12" ||
 			p.Title != "This week's Supply run is ready" || p.Body != "3 items to buy for 2 dinners" {
-			t.Errorf("%s row = %+v, want list_ready:2026-10-12, 3 items for 2 dinners, /plan/shopping", r.Channel, r)
+			t.Errorf("%s row = %+v, want list_ready:2026-10-12, 3 items for 2 dinners, /plan/shopping?week=2026-10-12", r.Channel, r)
 		}
 	}
 

internal/shopping/schedule.go

@@ -0,0 +1,133 @@
+package shopping
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// RolloverTime is when, every Monday in the household zone, week_rollover
+// freezes the week that has just ended. It is fixed, not a setting.
+const RolloverTime = "00:05"
+
+// Reasons Autosend posts nothing.
+const (
+	AutosendNotConfigured = "no Google Chat webhook is configured"
+	AutosendChatOff       = "list_ready is switched off for Google Chat"
+	AutosendNoList        = "the week has no Supply run"
+	AutosendAlreadySent   = "the Supply run was already sent to Google Chat"
+	AutosendUnconfirmed   = "a send of the Supply run to Google Chat is unconfirmed"
+)
+
+// AutosendKey identifies the automatic send of the Supply run of the week
+// starting weekStart, list_ready:chat:YYYY-MM-DD: it is the
+// shopping_chat_autosend period key claimed in schedule_runs. The send
+// itself is recorded in the list's sent_to_chat_at.
+func AutosendKey(weekStart store.LocalDate) string {
+	return string(notify.ListReady) + ":" + string(notify.ChannelChat) + ":" + weekStart.String()
+}
+
+// ChatAutosendSchedule is the shopping_chat_autosend schedule: at the
+// household's chat_autosend_dow and chat_autosend_time it sends the Supply
+// run of the coming week, the week after the fire date's, to Google Chat
+// with Autosend. Its period is that week, scheduler.WeeklyForNextWeek's,
+// claimed under AutosendKey of the week's Monday. A send that fails is the
+// period's error and is not retried; the household can still send it from
+// the Supply run.
+func (s *Service) ChatAutosendSchedule() scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.ShoppingChatAutosend,
+		Rule: func(settings household.Settings) scheduler.Rule {
+			return scheduler.WeeklyForNextWeek(time.Weekday(settings.ChatAutosendDow), settings.ChatAutosendTime)
+		},
+		PeriodKey: func(p scheduler.Period) string {
+			return AutosendKey(p.Week)
+		},
+		Run: func(ctx context.Context, p scheduler.Period) error {
+			skipped, err := s.Autosend(ctx, p.Week)
+			if err != nil {
+				return err
+			}
+			log := s.logger.With("period", p.Key, "week_start", p.Week.String())
+			if skipped != "" {
+				log.InfoContext(ctx, "Supply run not sent to Google Chat: "+skipped)
+				return nil
+			}
+			log.InfoContext(ctx, "Supply run sent to Google Chat")
+			return nil
+		},
+	}
+}
+
+// Autosend sends the Supply run of the week starting weekStart to Google
+// Chat with SendToChat, as the household's send does, when a webhook is
+// stored, list_ready's Google Chat channel is switched on, and the week has
+// a Supply run not yet sent and with no send unconfirmed. Otherwise it
+// posts nothing and returns which of those reasons stopped it; it never
+// resends. A send that fails is SendToChat's error.
+func (s *Service) Autosend(ctx context.Context, weekStart store.LocalDate) (skipped string, err error) {
+	settings, err := s.chat.Get(ctx)
+	if err != nil {
+		return "", fmt.Errorf("shopping: autosend: %w", err)
+	}
+	if settings.URLMasked == nil {
+		return AutosendNotConfigured, nil
+	}
+	on, err := s.notifier.ChannelOn(ctx, notify.ListReady, notify.ChannelChat)
+	if err != nil {
+		return "", fmt.Errorf("shopping: autosend: %w", err)
+	}
+	if !on {
+		return AutosendChatOff, nil
+	}
+	l, err := s.Get(ctx, weekStart)
+	if errors.Is(err, ErrListNotFound) {
+		return AutosendNoList, nil
+	}
+	if err != nil {
+		return "", err
+	}
+	switch {
+	case l.SentToChatAt != nil:
+		return AutosendAlreadySent, nil
+	case l.ChatSendUnconfirmedAt != nil:
+		return AutosendUnconfirmed, nil
+	}
+	if _, err := s.SendToChat(ctx, weekStart, false); err != nil {
+		return "", err
+	}
+	return "", nil
+}
+
+// RolloverSchedule is the week_rollover schedule: every Monday at
+// RolloverTime it freezes the Supply run of the week before the fire
+// date's into the Supply archive with Freeze, the week ending by the fire
+// time. Its period scheduler.Weekly keys week_rollover:YYYY-Www for the
+// fire date's week. A week with no Supply run has nothing to freeze, and
+// the period says so; a freeze that fails is the period's error and is not
+// retried.
+func (s *Service) RolloverSchedule() scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.WeekRollover,
+		Rule: func(household.Settings) scheduler.Rule {
+			return scheduler.Weekly(time.Monday, RolloverTime)
+		},
+		Run: func(ctx context.Context, p scheduler.Period) error {
+			y, m, d := p.Week.Date()
+			last := store.LocalDateOf(time.Date(y, m, d-7, 0, 0, 0, 0, time.UTC))
+			err := s.freeze(ctx, last, p.FireAt)
+			if errors.Is(err, ErrListNotFound) {
+				s.logger.InfoContext(ctx, "week rollover froze nothing: the week has no Supply run",
+					"period", p.Key, "week_start", last.String())
+				return nil
+			}
+			return err
+		},
+	}
+}

internal/shopping/shopping_test.go

@@ -516,7 +516,7 @@ func TestGenerateManualRecipe(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	dsvc, err := dinners.NewService(e.st, grounder, runner, logger)
+	dsvc, err := dinners.NewService(e.st, grounder, runner, func() {}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}

internal/suggest/batch.go

@@ -22,6 +22,9 @@ import (
 // BatchJob is the KindSuggestionBatch payload: the batch to run.
 type BatchJob struct {
 	BatchID string `json:"batch_id"`
+	// Week is the YYYY-MM-DD Monday of the ISO week a scheduled batch is
+	// for, which keys its new_suggestions; empty for any other trigger.
+	Week string `json:"week,omitempty"`
 }
 
 // Batch stages, as the job's result reports them.
@@ -50,19 +53,22 @@ func (r batchResult) PublicJSON() ([]byte, error) { return json.Marshal(r) }
 // wanted at a time, until BatchSize are kept or none are left. A Side quest
 // no recipe grounds is dropped; any other grounding failure fails the
 // batch, as does suggest_side_quests failing, with no Side quest made up
-// instead. Each round's grounded Side quests are stored before the next
-// round starts, so the deck fills as the batch goes. The batch ends done
-// or failed; Side quests stored before a failure stay in the deck. When
-// recording the batch's end fails, so does the job; when it times out at
-// shutdown, the job is left running and the batch with it, for the next
-// start to fail.
+// instead. The batch ends done or failed. When recording the batch's end
+// fails, so does the job; when it times out at shutdown, the job is left
+// running and the batch with it, for the next start to fail.
 //
-// A scheduled or manual batch emits new_suggestions, keyed by the batch,
-// in the transaction that first adds Side quests to the deck, so the
-// household is told of every Side quest stored, whether or not the batch
-// then ends done: a later round, or recording the batch's end, may fail.
-// A replenish batch, which tops up the deck as the household swipes, never
-// notifies. See store.
+// When a batch stores its Side quests depends on whether it notifies (see
+// noticeOf). A scheduled or manual batch notifies: it holds every round's
+// grounded Side quests and, once the last round is done, stores them all
+// in one transaction with one new_suggestions counting and naming every
+// Side quest stored. So the household is told of exactly what the batch
+// added, once; and a batch that fails at any round, including a later
+// round's normalize_recipe, stores nothing and sends nothing, leaving no
+// Side quest in the deck that was never announced. A replenish batch,
+// which tops up the deck as the household swipes and never notifies,
+// stores each round's Side quests before the next round starts, so the
+// deck fills as it goes; those stored before a failure stay in the deck.
+// See store.
 func (s *Service) runBatch(ctx context.Context, p BatchJob, publish func(batchResult) error) (batchResult, error) {
 	batch, err := db.New(s.st.Reader).GetSuggestionBatch(ctx, p.BatchID)
 	if err != nil {
@@ -78,7 +84,7 @@ func (s *Service) runBatch(ctx context.Context, p BatchJob, publish func(batchRe
 	if n == 0 {
 		return batchResult{}, fmt.Errorf("suggest: batch %s is not pending", p.BatchID)
 	}
-	res, err := s.fill(ctx, p.BatchID, batch.Trigger != TriggerReplenish, publish)
+	res, err := s.fill(ctx, batch.Trigger, p, publish)
 	if err == nil {
 		if err := s.finishBatch(ctx, p.BatchID, BatchDone); err != nil {
 			return batchResult{}, err
@@ -98,10 +104,12 @@ func (s *Service) runBatch(ctx context.Context, p BatchJob, publish func(batchRe
 	return batchResult{}, errors.Join(err, finishErr)
 }
 
-// fill does runBatch's work, returning a *jobs.Failure for a failure the
-// household may see. When notifies is true, store emits new_suggestions
-// with the Side quests it adds.
-func (s *Service) fill(ctx context.Context, batchID string, notifies bool, publish func(batchResult) error) (batchResult, error) {
+// fill does runBatch's work for job of a batch with trigger, returning a
+// *jobs.Failure for a failure the household may see. A batch with a notice
+// is stored once, when its last round is done; any other batch round by
+// round.
+func (s *Service) fill(ctx context.Context, trigger string, job BatchJob, publish func(batchResult) error) (batchResult, error) {
+	batchID := job.BatchID
 	res := batchResult{BatchID: batchID, Stage: StageSuggesting, SuggestionIDs: []string{}}
 	if err := publish(res); err != nil {
 		return batchResult{}, err
@@ -110,6 +118,10 @@ func (s *Service) fill(ctx context.Context, batchID string, notifies bool, publi
 	if err != nil {
 		return batchResult{}, err
 	}
+	note, err := noticeOf(trigger, job, in.Context.Today)
+	if err != nil {
+		return batchResult{}, err
+	}
 	out, err := s.suggest(ctx, batchID, in)
 	if err != nil {
 		if ctx.Err() != nil {
@@ -122,34 +134,81 @@ func (s *Service) fill(ctx context.Context, batchID string, notifies bool, publi
 	if err := publish(res); err != nil {
 		return batchResult{}, err
 	}
-	var week *store.LocalDate
-	if notifies {
-		w := household.WeekStart(in.Context.Today)
-		week = &w
-	}
 	left := out.Suggestions
-	for len(res.SuggestionIDs) < BatchSize && len(left) > 0 {
-		round := left[:min(BatchSize-len(res.SuggestionIDs), len(left))]
+	// held are a notifying batch's grounded Side quests, not yet stored.
+	var held []groundedQuest
+	for len(res.SuggestionIDs)+len(held) < BatchSize && len(left) > 0 {
+		round := left[:min(BatchSize-len(res.SuggestionIDs)-len(held), len(left))]
 		left = left[len(round):]
 		grounded, err := s.ground(ctx, round)
 		if err != nil {
 			return batchResult{}, err
 		}
 		res.Dropped += len(round) - len(grounded)
-		ids, err := s.store(ctx, batchID, week, grounded)
-		if err != nil {
+		if note != nil {
+			held = append(held, grounded...)
+		} else if err := s.storeInto(ctx, &res, nil, grounded); err != nil {
 			return batchResult{}, err
 		}
-		res.Dropped += len(grounded) - len(ids)
-		res.SuggestionIDs = append(res.SuggestionIDs, ids...)
 		if err := publish(res); err != nil {
 			return batchResult{}, err
 		}
 	}
+	if note != nil {
+		if err := s.storeInto(ctx, &res, note, held); err != nil {
+			return batchResult{}, err
+		}
+	}
 	res.Stage = StageDone
 	return res, nil
 }
 
+// storeInto stores quests for res's batch with note (see store) and adds
+// the suggestions stored, and the Side quests left out, to res.
+func (s *Service) storeInto(ctx context.Context, res *batchResult, note *notice, quests []groundedQuest) error {
+	ids, err := s.store(ctx, res.BatchID, note, quests)
+	if err != nil {
+		return err
+	}
+	res.Dropped += len(quests) - len(ids)
+	res.SuggestionIDs = append(res.SuggestionIDs, ids...)
+	return nil
+}
+
+// notice is how a batch's new_suggestions is keyed: by id, as
+// new_suggestions:{id}, for the week starting on week.
+type notice struct {
+	id   string
+	week store.LocalDate
+}
+
+// noticeOf returns the notice of job, run for a batch with trigger on
+// household-local date today, or nil for a replenish batch, which never
+// notifies. A scheduled batch is keyed by the ISO week it was scheduled
+// for ("2026-W41"), not the week it happens to run in, so each week's
+// schedule tells the household once even when its batch runs late; a
+// manual batch is keyed by its batch id, for the week of today. A job
+// whose week does not fit its trigger is an error.
+func noticeOf(trigger string, job BatchJob, today store.LocalDate) (*notice, error) {
+	if trigger != TriggerScheduled {
+		if job.Week != "" {
+			return nil, fmt.Errorf("suggest: %s batch %s has a week", trigger, job.BatchID)
+		}
+		if trigger == TriggerReplenish {
+			return nil, nil
+		}
+		return &notice{id: job.BatchID, week: household.WeekStart(today)}, nil
+	}
+	week, err := store.ParseLocalDate(job.Week)
+	if err != nil {
+		return nil, fmt.Errorf("suggest: scheduled batch %s week: %w", job.BatchID, err)
+	}
+	if household.WeekStart(week) != week {
+		return nil, fmt.Errorf("suggest: scheduled batch %s week %s is not a Monday", job.BatchID, week)
+	}
+	return &notice{id: household.PeriodKey(week), week: week}, nil
+}
+
 // request reads what suggest_side_quests is given: the household context,
 // the deck's names and every passed name (ListPassedNames). A household with no Regulars
 // fails with ReasonNoRegulars.
@@ -224,13 +283,14 @@ func (s *Service) ground(ctx context.Context, quests []skills.SideQuest) ([]grou
 // or archived. Passed names are read in the same transaction as the store,
 // so a Pass or drop committed before it is never missed.
 //
-// When week is not nil and a Side quest is stored, new_suggestions:{batchID}
-// naming those stored is emitted in the same transaction, for the week
-// starting week, so the Side quests and their notification commit together
+// When note is not nil and a Side quest is stored, new_suggestions keyed by
+// note, counting and naming those stored, is emitted in the same
+// transaction, so the Side quests and their notification commit together
 // or not at all: a notification that cannot be stored fails the store, and
-// the batch with it. The event's key makes the first round to store Side
-// quests the one that notifies; a later round's emit stores nothing.
-func (s *Service) store(ctx context.Context, batchID string, week *store.LocalDate, quests []groundedQuest) ([]string, error) {
+// the batch with it. A notifying batch calls store once, with all its
+// Side quests, so the count is the batch's (see runBatch). This is the
+// only place new_suggestions is emitted.
+func (s *Service) store(ctx context.Context, batchID string, note *notice, quests []groundedQuest) ([]string, error) {
 	ids := []string{}
 	var stored []string
 	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
@@ -298,15 +358,15 @@ func (s *Service) store(ctx context.Context, batchID string, week *store.LocalDa
 			ids = append(ids, id)
 			stored = append(stored, d.Name)
 		}
-		if week == nil || len(stored) == 0 {
+		if note == nil || len(stored) == 0 {
 			return nil
 		}
-		return s.notifier.EmitTx(ctx, tx, chat.NewSuggestions(batchID, *week, stored))
+		return s.notifier.EmitTx(ctx, tx, chat.NewSuggestions(note.id, note.week, stored))
 	})
 	if err != nil {
 		return nil, err
 	}
-	if week != nil && len(stored) > 0 {
+	if note != nil && len(stored) > 0 {
 		s.notifier.Wake()
 	}
 	return ids, nil

internal/suggest/schedule.go

@@ -0,0 +1,36 @@
+package suggest
+
+import (
+	"context"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/scheduler"
+)
+
+// WeeklySchedule is the suggestions_weekly schedule: at the household's
+// suggestions_dow and suggestions_time it starts a scheduled batch for the
+// ISO week of the fire date, its period scheduler.Weekly keys
+// suggestions_weekly:YYYY-Www. The batch tells the household of the Side
+// quests it adds with new_suggestions:YYYY-Www for that week, once; a batch
+// that fails before adding any, as when the AI fails, sends nothing. When a
+// batch is already pending or running the period starts none, and says so.
+func (s *Service) WeeklySchedule() scheduler.Schedule {
+	return scheduler.Schedule{
+		Name: scheduler.SuggestionsWeekly,
+		Rule: func(settings household.Settings) scheduler.Rule {
+			return scheduler.Weekly(time.Weekday(settings.SuggestionsDow), settings.SuggestionsTime)
+		},
+		Run: func(ctx context.Context, p scheduler.Period) error {
+			b, err := s.StartScheduledBatch(ctx, p.Week)
+			if err != nil {
+				return err
+			}
+			if !b.Created {
+				s.logger.WarnContext(ctx, "scheduled suggestion batch not started: a batch is already under way",
+					"period", p.Key, "batch_id", b.ID, "trigger", b.Trigger)
+			}
+			return nil
+		},
+	}
+}

internal/suggest/suggest.go

@@ -19,6 +19,7 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/skills"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/dinners"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/jobs"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/notify"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
@@ -154,17 +155,35 @@ type Batch struct {
 	Created bool `json:"-"`
 }
 
-// StartBatch creates a batch with trigger and enqueues the
+// StartBatch creates a manual or replenish batch and enqueues the
 // KindSuggestionBatch job that runs it, unless a batch is already pending
-// or running, which it returns instead with Created false.
+// or running, which it returns instead with Created false. A scheduled
+// batch is started by StartScheduledBatch.
 func (s *Service) StartBatch(ctx context.Context, trigger string) (Batch, error) {
+	if trigger == TriggerScheduled {
+		return Batch{}, errors.New("suggest: a scheduled batch is started by StartScheduledBatch")
+	}
 	if !slices.Contains(triggers, trigger) {
 		return Batch{}, fmt.Errorf("suggest: unknown batch trigger %q", trigger)
 	}
+	return s.start(ctx, trigger, "")
+}
+
+// StartScheduledBatch is StartBatch for a scheduled batch for the ISO week
+// starting on Monday week, which keys its new_suggestions (see noticeOf).
+func (s *Service) StartScheduledBatch(ctx context.Context, week store.LocalDate) (Batch, error) {
+	if week.IsZero() || household.WeekStart(week) != week {
+		return Batch{}, fmt.Errorf("suggest: scheduled batch week %s is not a Monday", week)
+	}
+	return s.start(ctx, TriggerScheduled, week.String())
+}
+
+// start does StartBatch's work for a batch with trigger and the job week.
+func (s *Service) start(ctx context.Context, trigger, week string) (Batch, error) {
 	var b Batch
 	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
 		var err error
-		b, err = s.startBatch(ctx, tx, trigger)
+		b, err = s.startBatch(ctx, tx, trigger, week)
 		return err
 	})
 	if err != nil {
@@ -228,10 +247,11 @@ func failedBatch(ctx context.Context, q *db.Queries) (*Batch, error) {
 	return &Batch{ID: cur.ID, JobID: jobID, Trigger: cur.Trigger, Status: cur.Status}, nil
 }
 
-// startBatch does StartBatch's work in tx: the batch and the job that runs
-// it are committed together, so a batch is never seen without its job. The
-// caller wakes the job runner once tx has committed and Created is true.
-func (s *Service) startBatch(ctx context.Context, tx *sql.Tx, trigger string) (Batch, error) {
+// startBatch does StartBatch's work in tx, for a batch with trigger whose
+// job has week (BatchJob.Week): the batch and the job that runs it are
+// committed together, so a batch is never seen without its job. The caller
+// wakes the job runner once tx has committed and Created is true.
+func (s *Service) startBatch(ctx context.Context, tx *sql.Tx, trigger, week string) (Batch, error) {
 	q := db.New(tx)
 	cur, err := s.activeBatch(ctx, q)
 	if err != nil {
@@ -250,7 +270,7 @@ func (s *Service) startBatch(ctx context.Context, tx *sql.Tx, trigger string) (B
 	if err != nil {
 		return Batch{}, fmt.Errorf("suggest: create batch: %w", err)
 	}
-	jobID, err := s.batchJob.EnqueueTx(ctx, tx, BatchJob{BatchID: row.ID})
+	jobID, err := s.batchJob.EnqueueTx(ctx, tx, BatchJob{BatchID: row.ID, Week: week})
 	if err != nil {
 		return Batch{}, fmt.Errorf("suggest: enqueue batch %s: %w", row.ID, err)
 	}
@@ -346,6 +366,17 @@ func (s *Service) Deck(ctx context.Context) (Deck, error) {
 	return deck, nil
 }
 
+// PendingCount is how many Side quests are pending on the deck. Unlike
+// Deck it only reads: it does not fail orphaned batches, so a reader such
+// as Home never writes.
+func (s *Service) PendingCount(ctx context.Context) (int, error) {
+	rows, err := db.New(s.st.Reader).ListDeck(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("suggest: list deck: %w", err)
+	}
+	return len(rows), nil
+}
+
 // Decision is a suggestion once decided, with the id of the replenish
 // batch's job when the decision called for one: the batch it started, or
 // the one already pending or running that it joined.
@@ -428,7 +459,7 @@ func (s *Service) decide(ctx context.Context, id, decision, dinnerStatus, update
 		if left >= ReplenishBelow {
 			return nil
 		}
-		b, err := s.startBatch(ctx, tx, TriggerReplenish)
+		b, err := s.startBatch(ctx, tx, TriggerReplenish, "")
 		if err != nil {
 			return err
 		}

internal/suggest/suggest_test.go

@@ -300,6 +300,45 @@ func (e *env) runBatch(t *testing.T) batchResult {
 	return res
 }
 
+// scheduledWeek is the week the tests' scheduled batches are for: the
+// Monday of 2026-W41.
+var scheduledWeek = mustDate("2026-10-05")
+
+func mustDate(s string) store.LocalDate {
+	d, err := store.ParseLocalDate(s)
+	if err != nil {
+		panic(err)
+	}
+	return d
+}
+
+func mustZone(t *testing.T, name string) *time.Location {
+	t.Helper()
+	loc, err := household.LoadZone(name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return loc
+}
+
+// startBatch starts a batch with trigger, a scheduled one for
+// scheduledWeek, and returns it with the key its new_suggestions has.
+func (e *env) startBatch(t *testing.T, trigger string) (suggest.Batch, string) {
+	t.Helper()
+	if trigger == suggest.TriggerScheduled {
+		b, err := e.svc.StartScheduledBatch(t.Context(), scheduledWeek)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return b, "new_suggestions:2026-W41"
+	}
+	b, err := e.svc.StartBatch(t.Context(), trigger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return b, "new_suggestions:" + b.ID
+}
+
 func (e *env) batchStatus(t *testing.T, id string) string {
 	t.Helper()
 	var status string
@@ -404,8 +443,9 @@ func TestBatchStoresGroundedSideQuests(t *testing.T) {
 }
 
 // TestBatchEmitsNewSuggestions: a scheduled or manual batch that adds Side
-// quests stores new_suggestions keyed by the batch, naming them; a
-// replenish batch, or one that adds none, stores nothing.
+// quests stores new_suggestions counting and naming them, keyed by the
+// scheduled ISO week or the manual batch, for that week or the current
+// one; a replenish batch, or one that adds none, stores nothing.
 func TestBatchEmitsNewSuggestions(t *testing.T) {
 	for _, tc := range []struct {
 		trigger string
@@ -428,10 +468,7 @@ func TestBatchEmitsNewSuggestions(t *testing.T) {
 				sideQuest("Chicken Shawarma Bowls", "Spiced chicken, like your Chicken Fajitas.", "Chicken Fajitas"),
 				sideQuest("Chili Verde", "Your Beef Chili gone green.", "Beef Chili"),
 			)
-			b, err := e.svc.StartBatch(t.Context(), tc.trigger)
-			if err != nil {
-				t.Fatal(err)
-			}
+			b, key := e.startBatch(t, tc.trigger)
 			if job := e.waitJob(t, b.JobID); job.Status != jobs.StatusSucceeded {
 				t.Fatalf("batch job %s", job.Status)
 			}
@@ -446,64 +483,70 @@ func TestBatchEmitsNewSuggestions(t *testing.T) {
 				t.Fatalf("new_suggestions rows = %+v, want one on push", rows)
 			}
 			r := rows[0]
-			if r.Key != "new_suggestions:"+b.ID || r.Channel != notify.ChannelPush || r.Payload.URL != "/discover" ||
-				r.Payload.Title != "New Side quests are in" || r.Payload.Body != "Chicken Shawarma Bowls, Chili Verde" || r.Payload.Week == "" {
-				t.Errorf("new_suggestions row = %+v, want key new_suggestions:%s naming the Side quests, /discover", r, b.ID)
+			week := household.WeekStart(store.LocalDateOf(time.Now().In(mustZone(t, "America/New_York")))).String()
+			if tc.trigger == suggest.TriggerScheduled {
+				week = scheduledWeek.String()
+			}
+			if r.Key != key || r.Channel != notify.ChannelPush || r.Payload.URL != "/discover" ||
+				r.Payload.Title != "2 new Side quests are in" || r.Payload.Body != "Chicken Shawarma Bowls, Chili Verde" || r.Payload.Week != week {
+				t.Errorf("new_suggestions row = %+v, want key %s counting and naming the Side quests, week %s, /discover", r, key, week)
 			}
 		})
 	}
 }
 
-// TestBatchNotifiesAsSideQuestsAreStored: new_suggestions is stored with
-// the first round to add Side quests, so a batch whose later round fails
-// still tells the household of those in the deck, once; a later round that
-// succeeds adds no second notification; a replenish batch notifies nothing.
-func TestBatchNotifiesAsSideQuestsAreStored(t *testing.T) {
+// twoRoundBatch scripts a suggest_side_quests reply of BatchSize+1 Side
+// quests, Fajita Dish A to F, whose first round grounds all but B, so a
+// second round grounds F. Unless lastGrounds, normalize_recipe fails for
+// F.
+func (e *env) twoRoundBatch(t *testing.T, lastGrounds bool) {
+	t.Helper()
+	var quests []string
+	for i := range suggest.BatchSize + 1 {
+		name := fmt.Sprintf("Fajita Dish %c", 'A'+i)
+		e.search.Results[name] = nil
+		switch {
+		case i == suggest.BatchSize && !lastGrounds:
+			// A page is found, but no normalize_recipe reply is scripted
+			// for it, so the AI call grounding it fails.
+			slug := strings.ReplaceAll(strings.ToLower(name), " ", "-")
+			page, photo := "https://r.example/"+slug, "https://r.example/"+slug+".jpg"
+			e.search.Results[name] = []recipes.Candidate{{URL: page}}
+			e.pages.Bodies[page] = recipestest.RecipePage(name, "R Kitchen", photo, 35)
+			e.images.JPEGs[photo] = recipestest.JPEG(t, 400, 320, uint8(len(e.images.JPEGs)+1))
+		case i != 1:
+			e.recipe(t, name)
+		}
+		quests = append(quests, sideQuest(name, "Like your Chicken Fajitas.", "Chicken Fajitas"))
+	}
+	e.reply(quests...)
+}
+
+// TestBatchNotifiesOnceWithEverySideQuestStored: a batch that fills across
+// two grounding rounds stores new_suggestions once, when it completes,
+// counting and naming every Side quest it stored, not just the first
+// round's; a replenish batch notifies nothing.
+func TestBatchNotifiesOnceWithEverySideQuestStored(t *testing.T) {
 	for _, tc := range []struct {
-		trigger   string
-		lastFails bool
-		notify    bool
+		trigger string
+		notify  bool
 	}{
-		{suggest.TriggerScheduled, true, true},
-		{suggest.TriggerManual, true, true},
-		{suggest.TriggerManual, false, true},
-		{suggest.TriggerReplenish, true, false},
+		{suggest.TriggerScheduled, true},
+		{suggest.TriggerManual, true},
+		{suggest.TriggerReplenish, false},
 	} {
-		t.Run(fmt.Sprintf("%s last round fails %v", tc.trigger, tc.lastFails), func(t *testing.T) {
+		t.Run(tc.trigger, func(t *testing.T) {
 			e := newEnv(t)
 			e.start(t)
-			// The first round grounds BatchSize Side quests but B; the
-			// second round grounds F.
-			var quests []string
-			for i := range suggest.BatchSize + 1 {
-				name := fmt.Sprintf("Fajita Dish %c", 'A'+i)
-				e.search.Results[name] = nil
-				if i != 1 {
-					e.recipe(t, name)
-				}
-				quests = append(quests, sideQuest(name, "Like your Chicken Fajitas.", "Chicken Fajitas"))
-			}
-			e.reply(quests...)
-			if tc.lastFails {
-				if _, err := e.st.Writer.ExecContext(t.Context(), `CREATE TRIGGER refuse_f BEFORE INSERT ON dinners WHEN NEW.name = 'Fajita Dish F' BEGIN SELECT RAISE(ABORT, 'F refused'); END`); err != nil {
-					t.Fatal(err)
-				}
-			}
+			e.twoRoundBatch(t, true)
 
-			b, err := e.svc.StartBatch(t.Context(), tc.trigger)
-			if err != nil {
-				t.Fatal(err)
+			b, key := e.startBatch(t, tc.trigger)
+			if job := e.waitJob(t, b.JobID); job.Status != jobs.StatusSucceeded {
+				t.Fatalf("batch job %s, want succeeded", job.Status)
 			}
-			job := e.waitJob(t, b.JobID)
-			want, deck := jobs.StatusSucceeded, suggest.BatchSize
-			if tc.lastFails {
-				want, deck = jobs.StatusFailed, suggest.BatchSize-1
-			}
-			if job.Status != want {
-				t.Fatalf("batch job %s, want %s", job.Status, want)
-			}
-			if got := e.deckNames(t); len(got) != deck {
-				t.Fatalf("deck = %v, want %d Side quests", got, deck)
+			deck := e.deckNames(t)
+			if want := []string{"Fajita Dish A", "Fajita Dish C", "Fajita Dish D", "Fajita Dish E", "Fajita Dish F"}; !slices.Equal(deck, want) {
+				t.Fatalf("deck = %v, want %v", deck, want)
 			}
 			rows := notifytest.Rows(t, e.st, notify.NewSuggestions)
 			if !tc.notify {
@@ -512,9 +555,47 @@ func TestBatchNotifiesAsSideQuestsAreStored(t *testing.T) {
 				}
 				return
 			}
-			if len(rows) != 1 || rows[0].Key != "new_suggestions:"+b.ID ||
-				rows[0].Payload.Body != "Fajita Dish A, Fajita Dish C, Fajita Dish D + 1 more" {
-				t.Errorf("new_suggestions rows = %+v, want one keyed by batch %s naming the first round", rows, b.ID)
+			want := fmt.Sprintf("%d new Side quests are in", len(deck))
+			if len(rows) != 1 || rows[0].Key != key || rows[0].Payload.Title != want ||
+				rows[0].Payload.Body != "Fajita Dish A, Fajita Dish C, Fajita Dish D + 2 more" {
+				t.Errorf("new_suggestions rows = %+v, want one keyed %s titled %q", rows, key, want)
+			}
+		})
+	}
+}
+
+// TestBatchFailingInALaterRoundStoresNothing: when normalize_recipe fails
+// in a batch's second grounding round, a scheduled or manual batch stores
+// none of the first round's Side quests and sends no new_suggestions, so
+// no Side quest is left in the deck unannounced; a replenish batch, which
+// never notifies, keeps the first round's in the deck.
+func TestBatchFailingInALaterRoundStoresNothing(t *testing.T) {
+	for _, tc := range []struct {
+		trigger string
+		deck    int
+	}{
+		{suggest.TriggerScheduled, 0},
+		{suggest.TriggerManual, 0},
+		{suggest.TriggerReplenish, suggest.BatchSize - 1},
+	} {
+		t.Run(tc.trigger, func(t *testing.T) {
+			e := newEnv(t)
+			e.start(t)
+			e.twoRoundBatch(t, false)
+
+			b, _ := e.startBatch(t, tc.trigger)
+			job := e.waitJob(t, b.JobID)
+			if job.Status != jobs.StatusFailed || job.Error == nil || *job.Error != suggest.ReasonAIFailed {
+				t.Fatalf("batch job %s, error %+v, want failed %s", job.Status, job.Error, suggest.ReasonAIFailed)
+			}
+			if got := e.batchStatus(t, b.ID); got != suggest.BatchFailed {
+				t.Errorf("batch status = %s, want failed", got)
+			}
+			if got := e.deckNames(t); len(got) != tc.deck {
+				t.Errorf("deck = %v, want %d Side quests", got, tc.deck)
+			}
+			if rows := notifytest.Rows(t, e.st, notify.NewSuggestions); len(rows) != 0 {
+				t.Errorf("new_suggestions rows = %+v, want none", rows)
 			}
 		})
 	}
@@ -1021,7 +1102,7 @@ func TestBatchNeverStoresDishPassedWhileRunning(t *testing.T) {
 func TestLaterBatchNeverResuggestsRenamedPass(t *testing.T) {
 	e := newEnv(t) // runner not started: the replenish batch waits for the rename
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	dinnerSvc, err := dinners.NewService(e.st, e.grounder, e.runner, logger)
+	dinnerSvc, err := dinners.NewService(e.st, e.grounder, e.runner, func() {}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -1069,14 +1150,14 @@ func TestLaterBatchNeverResuggestsRenamedDrop(t *testing.T) {
 	e := newEnv(t)
 	ctx := t.Context()
 	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
-	dinnerSvc, err := dinners.NewService(e.st, e.grounder, e.runner, logger)
+	dinnerSvc, err := dinners.NewService(e.st, e.grounder, e.runner, func() {}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
 	fail := func(context.Context, string, skills.WeekRequest) (skills.Week, error) {
 		return skills.Week{}, errors.New("no draft in this test")
 	}
-	planSvc, err := plan.NewService(e.st, fail, e.runner, noCalendar{}, notifytest.New(t, e.st), &url.URL{Scheme: "https", Host: "meals.example.com"}, logger)
+	planSvc, err := plan.NewService(e.st, fail, e.runner, noCalendar{}, notifytest.New(t, e.st), func() {}, &url.URL{Scheme: "https", Host: "meals.example.com"}, logger)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -1299,7 +1380,7 @@ func TestBatchJobFailsWhenRecordingItsEndFails(t *testing.T) {
 		t.Errorf("batch status = %s with its job failed, want failed", got)
 	}
 	// Its Side quests stay in the deck, and the household was told of them.
-	if rows := notifytest.Rows(t, e.st, notify.NewSuggestions); len(rows) != 1 || rows[0].Key != "new_suggestions:"+b.ID || rows[0].Payload.Body != "Chili Verde" {
+	if rows := notifytest.Rows(t, e.st, notify.NewSuggestions); len(rows) != 1 || rows[0].Key != "new_suggestions:"+b.ID || rows[0].Payload.Title != "1 new Side quest is in" || rows[0].Payload.Body != "Chili Verde" {
 		t.Errorf("new_suggestions rows of a batch whose end was not recorded = %+v, want one naming Chili Verde", rows)
 	}
 }
@@ -1474,6 +1555,47 @@ func TestStartBatchRefusesUnknownTrigger(t *testing.T) {
 	}
 }
 
+// TestScheduledBatchNeedsItsWeek: a scheduled batch is started only by
+// StartScheduledBatch, for a Monday.
+func TestScheduledBatchNeedsItsWeek(t *testing.T) {
+	e := newEnv(t)
+	if _, err := e.svc.StartBatch(t.Context(), suggest.TriggerScheduled); err == nil {
+		t.Error("StartBatch started a scheduled batch with no week")
+	}
+	for _, week := range []store.LocalDate{{}, mustDate("2026-10-06")} {
+		if _, err := e.svc.StartScheduledBatch(t.Context(), week); err == nil {
+			t.Errorf("StartScheduledBatch(%q) accepted a week that is not a Monday", week)
+		}
+	}
+	if n := e.activeBatches(t); n != 0 {
+		t.Errorf("%d active batches, want none", n)
+	}
+}
+
+// TestScheduledBatchKeyedByItsWeekWhenRunLate: a scheduled batch's
+// new_suggestions is keyed by the week it was scheduled for, not the week
+// it runs in, so a batch caught up after its week ended still tells the
+// household of that week's Side quests and leaves the next week's key free.
+func TestScheduledBatchKeyedByItsWeekWhenRunLate(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.recipe(t, "Chili Verde")
+	e.reply(sideQuest("Chili Verde", "Your Beef Chili gone green.", "Beef Chili"))
+	// A week long past: the batch runs today, weeks later.
+	b, err := e.svc.StartScheduledBatch(t.Context(), mustDate("2026-01-05"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if job := e.waitJob(t, b.JobID); job.Status != jobs.StatusSucceeded {
+		t.Fatalf("batch job %s", job.Status)
+	}
+	rows := notifytest.Rows(t, e.st, notify.NewSuggestions)
+	if len(rows) != 1 || rows[0].Key != "new_suggestions:2026-W02" || rows[0].Payload.Week != "2026-01-05" ||
+		rows[0].Payload.Title != "1 new Side quest is in" {
+		t.Errorf("new_suggestions rows = %+v, want one keyed new_suggestions:2026-W02 for 2026-01-05", rows)
+	}
+}
+
 // noCalendar is a plan.Calendar for tests that never push.
 type noCalendar struct{}
 

migrations/queries/dinners.sql

@@ -181,3 +181,65 @@ WHERE grounding_status = 'pending'
 			AND json_extract(jobs.payload, '$.dinner_id') = dinners.id
 			AND json_extract(jobs.payload, '$.revision') = dinners.grounding_revision
 	);
+
+-- name: ListPhotoBackfillDinners :many
+-- The dinners a photo backfill grounds by name: unarchived, failed, with no
+-- photo and no pasted recipe_url (the household's own link is never
+-- replaced by a search), ordered by normalized name. A non-NULL id narrows
+-- the list to that dinner. Grounded, manual and pending dinners are never
+-- listed: they have a recipe, or a ground_dinner job grounding them.
+SELECT * FROM dinners
+WHERE status <> 'archived'
+	AND grounding_status = 'failed'
+	AND photo_id IS NULL
+	AND recipe_url IS NULL
+	AND id = COALESCE(sqlc.narg(id), id)
+ORDER BY normalized_name, id;
+
+-- name: GetActivePhotoBackfillJob :one
+-- The id of the full photo backfill job (no dinner_id) of kind queued or
+-- running. StartPhotoBackfill enqueues one only when there is none, so
+-- there is at most one. Returns sql.ErrNoRows when there is none.
+SELECT id
+FROM jobs
+WHERE kind = sqlc.arg(kind)
+	AND status IN ('queued', 'running')
+	AND json_extract(payload, '$.dinner_id') IS NULL
+ORDER BY id
+LIMIT 1;
+
+-- name: GroundFailedDinner :execrows
+-- Records a photo backfill's grounding of a dinner it listed, while the
+-- dinner is still unarchived, failed, photoless, without a recipe_url and at
+-- the grounding_revision it was listed at; a dinner grounded by hand,
+-- renamed or archived meanwhile is left as it is (0 rows). Like
+-- GroundPendingDinner it keeps a method, minutes_total or difficulty a
+-- member already set.
+UPDATE dinners
+SET recipe_id = sqlc.arg(recipe_id),
+	photo_id = sqlc.arg(photo_id),
+	method = COALESCE(method, sqlc.arg(method)),
+	minutes_total = COALESCE(minutes_total, sqlc.arg(minutes_total)),
+	difficulty = COALESCE(difficulty, sqlc.arg(difficulty)),
+	grounding_status = 'grounded',
+	grounding_error = NULL,
+	updated_at = sqlc.arg(updated_at)
+WHERE id = sqlc.arg(id)
+	AND status <> 'archived'
+	AND grounding_status = 'failed'
+	AND photo_id IS NULL
+	AND recipe_url IS NULL
+	AND grounding_revision = sqlc.arg(grounding_revision);
+
+-- name: RefailDinnerGrounding :execrows
+-- Records why a photo backfill could not ground a dinner it listed, under
+-- the same conditions as GroundFailedDinner (0 rows otherwise).
+UPDATE dinners
+SET grounding_error = sqlc.arg(grounding_error),
+	updated_at = sqlc.arg(updated_at)
+WHERE id = sqlc.arg(id)
+	AND status <> 'archived'
+	AND grounding_status = 'failed'
+	AND photo_id IS NULL
+	AND recipe_url IS NULL
+	AND grounding_revision = sqlc.arg(grounding_revision);

migrations/queries/notifications.sql

@@ -66,3 +66,28 @@ SELECT * FROM notification_prefs;
 UPDATE notification_prefs
 SET push = ?, chat = ?, updated_at = ?
 WHERE event = ?;
+
+-- name: HasNotificationSince :one
+-- Reports whether a notification was stored after since, or at all when
+-- since is NULL.
+SELECT EXISTS (
+	SELECT 1 FROM notification_outbox
+	WHERE CAST(sqlc.narg(since) AS TEXT) IS NULL OR created_at > CAST(sqlc.narg(since) AS TEXT)
+) AS found;
+
+-- name: ListRecentNotifications :many
+-- Returns the last lim distinct events stored, newest first: one row per
+-- event key, the last stored for it whatever its channel, so an event
+-- stored for push and Google Chat is one row. The last, because a channel
+-- switched on later can store the same event key again, and
+-- HasNotificationSince counts that row: an event is as new as its newest
+-- row, so marking it seen also covers that row.
+SELECT o.event_key, o.payload, o.created_at FROM notification_outbox o
+WHERE o.id = (
+	SELECT i.id FROM notification_outbox i
+	WHERE i.event_key = o.event_key
+	ORDER BY i.created_at DESC, i.id DESC
+	LIMIT 1
+)
+ORDER BY o.created_at DESC, o.event_key DESC
+LIMIT sqlc.arg(lim);

migrations/queries/schedule_runs.sql

@@ -0,0 +1,6 @@
+-- name: ClaimScheduleRun :execrows
+-- Claims one period of a schedule. The insert is the claim: 1 row means
+-- this caller owns the period, 0 rows means it was already claimed.
+INSERT INTO schedule_runs (id, schedule, period_key, created_at)
+VALUES (?, ?, ?, ?)
+ON CONFLICT (schedule, period_key) DO NOTHING;

migrations/queries/settings.sql

@@ -154,3 +154,11 @@ RETURNING *;
 UPDATE chat_settings
 SET last_test_at = ?, last_test_status = ?, updated_at = ?
 WHERE id = 1 AND webhook_url_ct = ?;
+
+-- name: MarkUpdatesSeen :execrows
+-- Moves updates_seen_at forward to seen_at; affects no row when it is
+-- already at or after seen_at, so it never moves back. It is not a settings
+-- edit: updated_by and updated_at are left as they are.
+UPDATE household_settings
+SET updates_seen_at = CAST(sqlc.arg(seen_at) AS TEXT)
+WHERE id = 1 AND (updates_seen_at IS NULL OR updates_seen_at < CAST(sqlc.arg(seen_at) AS TEXT));

web/src/App.test.tsx

@@ -5,7 +5,7 @@ import { createNetworkStatus } from './pwa/networkStatus.ts'
 import { mockViewport } from './test/matchMedia.ts'
 import { errorResponse, fakeLocation, jsonResponse, ME, request, stubFetch, stubFetchByPath } from './test/fetchStub.ts'
 import App, { routes } from './App.tsx'
-import { AI_SETTINGS, HOUSEHOLD_SETTINGS, RECIPE_SEARCH_SETTINGS, SETTINGS_API } from './test/ApiProviders.tsx'
+import { AI_SETTINGS, HOME, HOUSEHOLD_SETTINGS, RECIPE_SEARCH_SETTINGS, SETTINGS_API } from './test/ApiProviders.tsx'
 import { InDataRouter } from './test/dataRouter.tsx'
 import { dinnerBody } from './test/dinners.ts'
 import { defaultWeek } from './plan/week.ts'
@@ -30,6 +30,7 @@ function renderAppAt(path: string, location = fakeLocation(path)) {
 
 // The routes that render a built screen rather than a placeholder page.
 const SCREENS = {
+  '/': true,
   '/onboarding': true,
   '/plan': true,
   '/plan/shopping': true,
@@ -85,6 +86,16 @@ describe('App routes', () => {
     },
   )
 
+  it('/ renders the Home screen inside the shell', async () => {
+    mockViewport(390)
+    stubFetchByPath({ ...SIGNED_IN, '/api/v1/home': () => jsonResponse(200, HOME), '/api/v1/rotation-reviews': () => jsonResponse(200, { reviews: [] }) })
+    renderAt('/')
+    const heading = await screen.findByRole('heading', { level: 1, name: "Tonight's quest" })
+    expect(screen.getByRole('main')).toContainElement(heading)
+    expect(await screen.findByRole('heading', { name: 'Pizza night' })).toBeInTheDocument()
+    expect(screen.getByRole('navigation', { name: 'Primary' })).toBeInTheDocument()
+  })
+
   it('/settings renders the settings home inside the shell', async () => {
     mockViewport(390)
     stubFetchByPath({
@@ -262,12 +273,19 @@ describe('App bootstrap', () => {
 
   it('reports a /me failure with a retry instead of rendering the routes', async () => {
     mockViewport(390)
-    stubFetch(errorResponse(500, 'internal'), jsonResponse(200, ME), jsonResponse(200, HOUSEHOLD_SETTINGS))
+    const mes = [errorResponse(500, 'internal'), jsonResponse(200, ME)]
+    stubFetchByPath({
+      ...SIGNED_IN,
+      '/api/v1/me': () => mes.shift()!,
+      '/api/v1/home': () => jsonResponse(200, HOME),
+      '/api/v1/rotation-reviews': () => jsonResponse(200, { reviews: [] }),
+    })
     renderAt('/')
 
     expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: internal message')
     screen.getByRole('button', { name: 'Retry' }).click()
-    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+    expect(await screen.findByRole('heading', { level: 1, name: "Tonight's quest" })).toBeInTheDocument()
+    expect(await screen.findByRole('heading', { name: 'Pizza night' })).toBeInTheDocument()
   })
 })
 
@@ -282,9 +300,9 @@ describe('App offline bootstrap', () => {
   // visitOnline is an earlier online visit on this device: /me answers with a
   // member, then the app is closed.
   async function visitOnline() {
-    stubFetchByPath(SIGNED_IN)
+    stubFetchByPath({ ...SIGNED_IN, '/api/v1/home': () => jsonResponse(200, HOME), '/api/v1/rotation-reviews': () => jsonResponse(200, { reviews: [] }) })
     const { unmount } = renderAt('/')
-    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+    expect(await screen.findByRole('heading', { name: 'Pizza night' })).toBeInTheDocument()
     unmount()
   }
 
@@ -295,14 +313,16 @@ describe('App offline bootstrap', () => {
   })
 
   // A test that emits an offline event leaves TanStack Query's online
-  // manager, shared by every test, offline until an online event.
+  // manager, shared by every test, offline until an online event. The
+  // manager listens for it only while a query client is mounted, so the
+  // event goes out before cleanup unmounts the app.
   afterEach(() => {
-    cleanup()
     window.dispatchEvent(new Event('online'))
+    cleanup()
   })
 
   it.each([
-    ['/', 'Home'],
+    ['/', "Tonight's quest"],
     ['/settings/notifications', 'Notifications'],
   ])('an offline reload of %s after an online visit opens the saved page', async (path, title) => {
     await visitOnline()

web/src/App.tsx

@@ -5,6 +5,7 @@ import { ApiProvider, createQueryClient, type ApiClient } from './api/index.ts'
 import { AuthBootstrap } from './AuthBootstrap.tsx'
 import { DinnerDetailPage } from './dinners/DinnerDetailPage.tsx'
 import { DiscoverPage } from './discover/DiscoverPage.tsx'
+import { HomePage } from './home/HomePage.tsx'
 import { CookFromPantryPage } from './ideas/CookFromPantryPage.tsx'
 import { QuickDinnersPage } from './ideas/QuickDinnersPage.tsx'
 import { ONBOARDING_PATH, OnboardingGate } from './onboarding/OnboardingGate.tsx'
@@ -45,6 +46,7 @@ export const routes = [
 
 // The screens built so far; every other route shows its placeholder page.
 const screens: Partial<Record<(typeof routes)[number]['path'], ReactNode>> = {
+  '/': <HomePage />,
   '/plan': <PlanPage />,
   '/plan/shopping': <SupplyRunPage />,
   '/plan/shopping/archive': <SupplyArchivePage />,

web/src/dinners/DinnerDetailActions.test.tsx

@@ -52,6 +52,8 @@ function listed(is_favorite: boolean) {
     is_favorite,
     photo_url: null,
     grounding_status: 'grounded',
+    grounding_error: null,
+    photo_backfill_eligible: false,
   }
 }
 

web/src/dinners/api.ts

@@ -20,8 +20,12 @@ export type Difficulty = (typeof DIFFICULTIES)[number]
 export type GroundingStatus = (typeof GROUNDING_STATUSES)[number]
 
 // Regular is the part of a dinner the Regulars screens read. photo_id is
-// the stored photo's id, from photo_url. pending is true while an
-// optimistic add waits for the server; its id is not the server's.
+// the stored photo's id, from photo_url. grounding_error is why its
+// grounding failed, a reason code, set only while grounding_status is
+// failed. photo_backfill_eligible is whether a photo backfill (Search
+// again) searches for it: never for a dinner with a pasted recipe link.
+// pending is true while an optimistic add waits for the server;
+// its id is not the server's.
 export type Regular = {
   id: string
   name: string
@@ -31,6 +35,8 @@ export type Regular = {
   is_favorite: boolean
   photo_id: string | undefined
   grounding_status: GroundingStatus
+  grounding_error: string | null
+  photo_backfill_eligible: boolean
   pending?: true
 }
 
@@ -113,6 +119,9 @@ export function parseDinner(where: string, body: unknown): Regular {
     throw new Error(`${where}: response is not a dinner`)
   }
   if (typeof body.is_favorite !== 'boolean') throw new Error(`${where}: is_favorite is not a boolean`)
+  if (typeof body.photo_backfill_eligible !== 'boolean') {
+    throw new Error(`${where}: photo_backfill_eligible is not a boolean`)
+  }
   return {
     id: body.id,
     name: body.name,
@@ -122,6 +131,11 @@ export function parseDinner(where: string, body: unknown): Regular {
     is_favorite: body.is_favorite,
     photo_id: photoId(where, body.photo_url),
     grounding_status: oneOf(where, 'grounding_status', GROUNDING_STATUSES, body.grounding_status),
+    grounding_error: nullable(body.grounding_error, (v) => {
+      if (typeof v !== 'string') throw new Error(`${where}: grounding_error is not a string`)
+      return v
+    }),
+    photo_backfill_eligible: body.photo_backfill_eligible,
   }
 }
 
@@ -225,6 +239,8 @@ export function useAddRegular() {
         is_favorite: false,
         photo_id: undefined,
         grounding_status: 'pending',
+        grounding_error: null,
+        photo_backfill_eligible: false,
         pending: true,
       }
       await changeOptimistically(queryClient, (list) => [...list, optimistic])

web/src/home/HomePage.module.css

@@ -0,0 +1,193 @@
+/* Home, handoff mock 1g. */
+.page {
+  box-sizing: border-box;
+  max-width: 560px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding-top: 6px;
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  margin-bottom: 2px;
+}
+
+.date {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 28px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+/* The bell's 8 px grape unread dot sits on the 40 px face, which is
+   centred in the IconButton's 44 px hit box. */
+.bell {
+  position: relative;
+}
+
+.bell .bellIcon {
+  width: 19px;
+  height: 19px;
+}
+
+.dot {
+  position: absolute;
+  top: 10px;
+  right: 11px;
+  width: 8px;
+  height: 8px;
+  border-radius: var(--radius-pill);
+  background: var(--color-accent);
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  border-radius: 32px;
+  background: var(--color-surface);
+  overflow: hidden;
+}
+
+.photo {
+  height: 150px;
+}
+
+.cardFoot {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 2px 18px 16px;
+}
+
+.cardText {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.name {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+.meta {
+  font-family: var(--font-body);
+  font-size: 12px;
+  color: var(--color-neutral-700);
+}
+
+/* The dark "Recipe" pill: the mock's 38 px pill at the 44 px tap minimum. */
+.recipe {
+  flex: none;
+  min-height: 44px;
+  padding: 0 16px;
+  font-size: 13px;
+  text-decoration: none;
+}
+
+.tiles {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+}
+
+.tile {
+  box-sizing: border-box;
+  height: 104px;
+  padding: 14px;
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  border-radius: 26px;
+  text-decoration: none;
+}
+
+.quick {
+  background: var(--color-accent);
+  color: var(--on-accent);
+}
+
+.pantry {
+  background: var(--color-accent-2-300);
+  color: var(--color-accent-2-900);
+}
+
+.tileLabel {
+  font-family: var(--font-heading);
+  font-size: 16px;
+  line-height: 1.1;
+}
+
+.statuses {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.status {
+  box-sizing: border-box;
+  min-height: 44px;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px 14px;
+  border-radius: 20px;
+  background: var(--color-neutral-100);
+  color: var(--color-text);
+  text-decoration: none;
+}
+
+.status .statusIcon {
+  width: 18px;
+  height: 18px;
+  color: var(--color-accent-700);
+}
+
+.statusText {
+  flex: 1;
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.tile:focus-visible,
+.status:focus-visible {
+  outline: 3px solid var(--color-accent);
+  outline-offset: 2px;
+}
+
+.skeletonDate {
+  width: 96px;
+  height: 14px;
+  margin-bottom: 2px;
+}
+
+.skeletonCard {
+  height: 238px;
+  border-radius: 32px;
+}
+
+.skeletonStatus {
+  height: 44px;
+  border-radius: 20px;
+}

web/src/home/HomePage.test.tsx

@@ -0,0 +1,319 @@
+import { act, fireEvent, render, screen, within } from '@testing-library/react'
+import { createMemoryRouter, RouterProvider, useLocation } from 'react-router'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ApiProviders, HOME } from '../test/ApiProviders.tsx'
+import { declaredStyle } from '../test/cssRules.ts'
+import { errorResponse, jsonResponse, stubFetchByPath } from '../test/fetchStub.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { HOME_PATH } from './api.ts'
+import { HomePage } from './HomePage.tsx'
+import { ROTATION_REVIEWS_PATH } from './rotation.ts'
+
+// NOTHING_YET is the home of a household with no plan, no Side quests, no
+// Supply run and nothing unread.
+const NOTHING_YET = {
+  ...HOME,
+  tonight: null,
+  sideQuestCount: 0,
+  shoppingList: { weekStart: '2026-09-28', label: 'Week 40 · Sep 28 – Oct 4', ready: false, sentToChatAt: null },
+  recentUpdates: { unread: false },
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+})
+
+// Where shows the route a link went to.
+function Where() {
+  const location = useLocation()
+  return <p data-testid="where">{location.pathname + location.search}</p>
+}
+
+function renderHome(body: unknown) {
+  stubFetchByPath({ [HOME_PATH]: () => jsonResponse(200, body), [ROTATION_REVIEWS_PATH]: () => jsonResponse(200, { reviews: [] }) })
+  return renderRouter()
+}
+
+function renderRouter() {
+  const router = createMemoryRouter(
+    [
+      { path: '/', element: <HomePage /> },
+      { path: '*', element: <Where /> },
+    ],
+    { initialEntries: ['/'] },
+  )
+  render(
+    <ApiProviders>
+      <RouterProvider router={router} />
+    </ApiProviders>,
+  )
+}
+
+describe('HomePage', () => {
+  it('renders mock 1g from GET /api/v1/home', async () => {
+    renderHome(HOME)
+
+    expect(await screen.findByText('Friday, Oct 2')).toBeInTheDocument()
+    expect(screen.getByRole('heading', { level: 1, name: "Tonight's quest" })).toBeInTheDocument()
+
+    const tonight = screen.getByRole('region', { name: 'Tonight' })
+    expect(within(tonight).getByRole('heading', { name: 'Pizza night' })).toBeInTheDocument()
+    expect(within(tonight).getByText('Regular · 40 min')).toBeInTheDocument()
+    expect(within(tonight).getByRole('img', { name: 'Pizza night' })).toHaveAttribute('src', '/media/photos/p1-400.jpg')
+    expect(within(tonight).getByRole('link', { name: 'Recipe' })).toHaveAttribute('href', '/dinner/d1')
+
+    expect(screen.getByRole('link', { name: 'Quick dinner' })).toHaveAttribute('href', '/quick')
+    expect(screen.getByRole('link', { name: 'Cook from what I have' })).toHaveAttribute('href', '/cook-from-pantry')
+    expect(screen.getByRole('link', { name: '10 new side quests to swipe' })).toHaveAttribute('href', '/discover')
+    expect(screen.getByRole('link', { name: 'Shopping list ready · Oct 5–11' })).toHaveAttribute(
+      'href',
+      '/plan/shopping?week=2026-10-05',
+    )
+    expect(screen.queryByRole('heading', { name: 'No quest planned tonight' })).not.toBeInTheDocument()
+  })
+
+  it("reads Home again at the household's next local midnight, so a Home left open moves to the new day", async () => {
+    // setTimeout moves with real time, and the test jumps to midnight.
+    vi.useFakeTimers({ toFake: ['Date', 'setTimeout', 'clearTimeout'], shouldAdvanceTime: true })
+    // 23:58 on Friday Oct 2 in New York, the household's zone.
+    vi.setSystemTime(new Date('2026-10-03T03:58:00Z'))
+    const days = [HOME, { ...HOME, dateLabel: 'Saturday, Oct 3', tonight: null }]
+    let reads = 0
+    stubFetchByPath({
+      [HOME_PATH]: () => jsonResponse(200, days[Math.min(reads++, 1)]),
+      [ROTATION_REVIEWS_PATH]: () => jsonResponse(200, { reviews: [] }),
+    })
+    renderRouter()
+    expect(await screen.findByText('Friday, Oct 2')).toBeInTheDocument()
+    expect(reads).toBe(1)
+
+    // A minute before midnight Home is not read again.
+    await act(() => vi.advanceTimersByTimeAsync(60_000))
+    expect(reads).toBe(1)
+    // At midnight it is, and shows the new day.
+    await act(() => vi.advanceTimersByTimeAsync(60_000))
+    expect(await screen.findByText('Saturday, Oct 3')).toBeInTheDocument()
+    expect(reads).toBe(2)
+    expect(screen.getByRole('heading', { name: 'No quest planned tonight' })).toBeInTheDocument()
+  })
+
+  it('shows the grape unread dot on the bell when there are unread updates', async () => {
+    renderHome(HOME)
+
+    const bell = await screen.findByRole('button', { name: 'Recent updates, unread' })
+    const dot = within(bell).getByTestId('unread-dot')
+    expect(declaredStyle(dot).background).toBe('var(--color-accent)')
+    expect(declaredStyle(dot).width).toBe('8px')
+    expectMinHitArea(bell)
+  })
+
+  it('shows the bell without a dot when every update is seen', async () => {
+    renderHome(NOTHING_YET)
+
+    const bell = await screen.findByRole('button', { name: 'Recent updates' })
+    expect(within(bell).queryByTestId('unread-dot')).not.toBeInTheDocument()
+  })
+
+  it('labels a Side quest tonight "Side quest"', async () => {
+    renderHome({ ...HOME, tonight: { ...HOME.tonight, origin: 'side_quest', minutes_total: 30 } })
+    expect(await screen.findByText('Side quest · 30 min')).toBeInTheDocument()
+  })
+
+  it('shows only the origin when tonight has no minutes', async () => {
+    renderHome({ ...HOME, tonight: { ...HOME.tonight, minutes_total: null, photo: null } })
+    const tonight = await screen.findByRole('region', { name: 'Tonight' })
+    expect(within(tonight).getByText('Regular')).toBeInTheDocument()
+    // No photo: the striped placeholder, named for the dinner.
+    expect(within(tonight).getByRole('img', { name: 'Pizza night' })).toHaveTextContent('dish photo')
+  })
+
+  it('offers to plan the week when tonight has no plan, and hides the rows that do not apply', async () => {
+    renderHome(NOTHING_YET)
+
+    expect(await screen.findByRole('heading', { name: 'No quest planned tonight' })).toBeInTheDocument()
+    expect(screen.queryByRole('region', { name: 'Tonight' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: /side quests? to swipe/ })).not.toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: /Shopping list ready/ })).not.toBeInTheDocument()
+    expect(screen.queryByRole('list', { name: 'Status' })).not.toBeInTheDocument()
+    // The tiles stay.
+    expect(screen.getByRole('link', { name: 'Quick dinner' })).toBeInTheDocument()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Plan this week' }))
+    expect(await screen.findByTestId('where')).toHaveTextContent('/plan')
+  })
+
+  it('hides the Side quests row at zero and keeps a ready Supply run', async () => {
+    renderHome({ ...HOME, sideQuestCount: 0 })
+
+    expect(await screen.findByRole('link', { name: 'Shopping list ready · Oct 5–11' })).toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: /side quests? to swipe/ })).not.toBeInTheDocument()
+  })
+
+  it('hides the Supply run row when no list is ready', async () => {
+    renderHome({ ...HOME, shoppingList: NOTHING_YET.shoppingList })
+
+    expect(await screen.findByRole('link', { name: '10 new side quests to swipe' })).toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: /Shopping list ready/ })).not.toBeInTheDocument()
+  })
+
+  it('counts a single Side quest in the singular', async () => {
+    renderHome({ ...HOME, sideQuestCount: 1 })
+    expect(await screen.findByRole('link', { name: '1 new side quest to swipe' })).toBeInTheDocument()
+  })
+
+  it('shows a week spanning two months in full', async () => {
+    renderHome({ ...HOME, shoppingList: { ...HOME.shoppingList, weekStart: '2026-09-28', label: 'Week 40 · Sep 28 – Oct 4' } })
+    expect(await screen.findByRole('link', { name: 'Shopping list ready · Sep 28–Oct 4' })).toBeInTheDocument()
+  })
+
+  it.each([
+    ['Recipe', '/dinner/d1'],
+    ['Quick dinner', '/quick'],
+    ['Cook from what I have', '/cook-from-pantry'],
+    ['10 new side quests to swipe', '/discover'],
+    ['Shopping list ready · Oct 5–11', '/plan/shopping?week=2026-10-05'],
+  ])('%s goes to %s', async (name, to) => {
+    renderHome(HOME)
+
+    fireEvent.click(await screen.findByRole('link', { name }))
+    expect(await screen.findByTestId('where')).toHaveTextContent(to)
+  })
+
+  it('styles the card, tiles and rows as mock 1g with tap targets of at least 44 px', async () => {
+    renderHome(HOME)
+
+    const tonight = await screen.findByRole('region', { name: 'Tonight' })
+    expect(declaredStyle(tonight).borderRadius).toBe('32px')
+    expect(declaredStyle(within(tonight).getByRole('img')).height).toBe('150px')
+    expect(declaredStyle(within(tonight).getByRole('heading')).fontSize).toBe('22px')
+
+    const quick = screen.getByRole('link', { name: 'Quick dinner' })
+    expect(declaredStyle(quick).height).toBe('104px')
+    expect(declaredStyle(quick).background).toBe('var(--color-accent)')
+    expect(declaredStyle(quick).color).toBe('var(--on-accent)')
+    const pantry = screen.getByRole('link', { name: 'Cook from what I have' })
+    expect(declaredStyle(pantry).height).toBe('104px')
+    expect(declaredStyle(pantry).background).toBe('var(--color-accent-2-300)')
+
+    expect(declaredStyle(screen.getByText('Friday, Oct 2')).fontSize).toBe('12px')
+
+    expectMinHitArea(within(tonight).getByRole('link', { name: 'Recipe' }))
+    // The tiles are 104 px tall (above); the status rows fill the width at 44 px or more.
+    for (const row of within(screen.getByRole('list', { name: 'Status' })).getAllByRole('link')) {
+      expect(declaredStyle(row).minHeight).toBe('44px')
+    }
+  })
+
+  it('shows skeletons while the home loads', async () => {
+    let answer!: (response: Response) => void
+    vi.stubGlobal(
+      'fetch',
+      vi.fn<typeof fetch>(() => new Promise((resolve) => (answer = resolve))),
+    )
+    renderRouter()
+
+    expect(screen.getByTestId('skeleton-tonight')).toBeInTheDocument()
+    expect(screen.getByTestId('skeleton-date')).toBeInTheDocument()
+    expect(screen.getAllByTestId('skeleton-status')).toHaveLength(2)
+    expect(screen.getByRole('heading', { level: 1, name: "Tonight's quest" })).toBeInTheDocument()
+
+    answer(jsonResponse(200, HOME))
+    expect(await screen.findByText('Friday, Oct 2')).toBeInTheDocument()
+    expect(screen.queryByTestId('skeleton-tonight')).not.toBeInTheDocument()
+    expect(screen.queryByTestId('skeleton-status')).not.toBeInTheDocument()
+  })
+
+  it('reports a failure with Retry, and no made-up content', async () => {
+    const homes = [errorResponse(500, 'internal'), jsonResponse(200, HOME)]
+    stubFetchByPath({
+      [HOME_PATH]: () => homes.shift()!,
+      [ROTATION_REVIEWS_PATH]: () => jsonResponse(200, { reviews: [] }),
+    })
+    renderRouter()
+
+    expect(await screen.findByRole('alert')).toHaveTextContent("Couldn't load tonight's quest. internal message")
+    expect(screen.queryByRole('region', { name: 'Tonight' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('heading', { name: 'No quest planned tonight' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('list', { name: 'Status' })).not.toBeInTheDocument()
+
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+    expect(await screen.findByRole('heading', { name: 'Pizza night' })).toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('reports a home it cannot read rather than guessing', async () => {
+    renderHome({ ...HOME, tonight: { ...HOME.tonight, origin: 'leftovers' } })
+    expect(await screen.findByRole('alert')).toHaveTextContent('origin "leftovers" is not one of regular, side_quest')
+  })
+
+  it.each([0, -1, 2.5])('reports tonight with minutes_total %s rather than showing it', async (minutes) => {
+    renderHome({ ...HOME, tonight: { ...HOME.tonight, minutes_total: minutes } })
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      `tonight's minutes_total ${minutes} is not a positive whole number`,
+    )
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+    expect(screen.queryByRole('region', { name: 'Tonight' })).not.toBeInTheDocument()
+    expect(screen.queryByText(/min$/)).not.toBeInTheDocument()
+  })
+
+  it('reports tonight without a minutes_total rather than showing it as unknown', async () => {
+    const { minutes_total: _, ...tonight } = HOME.tonight
+    renderHome({ ...HOME, tonight })
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('tonight has no minutes_total')
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+    expect(screen.queryByRole('region', { name: 'Tonight' })).not.toBeInTheDocument()
+    expect(screen.queryByText('Regular')).not.toBeInTheDocument()
+  })
+
+  it.each([
+    ['a missing', undefined],
+    ['an empty', ''],
+  ])('reports a ready Supply run with %s label rather than showing it', async (_, label) => {
+    renderHome({ ...HOME, shoppingList: { ...HOME.shoppingList, label } })
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('the ready shoppingList has no label')
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+    expect(screen.queryByRole('link', { name: /Shopping list ready/ })).not.toBeInTheDocument()
+    expect(screen.queryByRole('list', { name: 'Status' })).not.toBeInTheDocument()
+  })
+
+  it('reports a ready Supply run whose label is not its week rather than showing it', async () => {
+    renderHome({ ...HOME, shoppingList: { ...HOME.shoppingList, label: 'Week 40 · Sep 28 – Oct 4' } })
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      'shoppingList label "Week 40 · Sep 28 – Oct 4" is not the week of 2026-10-05',
+    )
+    expect(screen.queryByRole('link', { name: /Shopping list ready/ })).not.toBeInTheDocument()
+  })
+
+  it.each([
+    ['a missing', undefined],
+    ['an empty', ''],
+  ])('reports an unready Supply run with %s label rather than showing the home', async (_, label) => {
+    renderHome({ ...HOME, shoppingList: { ...NOTHING_YET.shoppingList, label } })
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('the unready shoppingList has no label')
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+    expect(screen.queryByRole('list', { name: 'Status' })).not.toBeInTheDocument()
+  })
+
+  it('reports an unready Supply run whose label is not its week rather than showing the home', async () => {
+    renderHome({ ...HOME, shoppingList: { ...NOTHING_YET.shoppingList, label: 'Week 41 · Oct 5 – 11' } })
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      'shoppingList label "Week 41 · Oct 5 – 11" is not the week of 2026-09-28',
+    )
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+    expect(screen.queryByRole('list', { name: 'Status' })).not.toBeInTheDocument()
+  })
+
+  it('reports a Supply run whose weekStart is not a date rather than showing it', async () => {
+    renderHome({ ...HOME, shoppingList: { ...HOME.shoppingList, weekStart: 'Oct 5' } })
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('not a YYYY-MM-DD date')
+    expect(screen.queryByRole('list', { name: 'Status' })).not.toBeInTheDocument()
+  })
+})

web/src/home/HomePage.tsx

@@ -0,0 +1,158 @@
+import { Bell, ChevronRight, Compass, Search, ShoppingCart, Zap, type LucideIcon } from 'lucide-react'
+import { useState } from 'react'
+import { Link, useNavigate } from 'react-router'
+import { duration } from '../plan/PlanPage.tsx'
+import { supplyRunScreen } from '../shopping/api.ts'
+import buttonStyles from '../ui/Button.module.css'
+import { EmptyState } from '../ui/EmptyState.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import { Photo } from '../ui/Photo.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { useHome, type Home, type Origin, type Tonight } from './api.ts'
+import styles from './HomePage.module.css'
+import { RotationCheck } from './RotationCheck.tsx'
+import { UpdatesSheet } from './UpdatesSheet.tsx'
+
+const ORIGIN_LABEL: Record<Origin, string> = { regular: 'Regular', side_quest: 'Side quest' }
+
+// meta is the Tonight card's "Regular · 40 min" line, the time only when
+// the recipe says it.
+function meta({ origin, minutes_total }: Tonight): string {
+  return minutes_total === null ? ORIGIN_LABEL[origin] : `${ORIGIN_LABEL[origin]} · ${duration(minutes_total)}`
+}
+
+// TonightCard is the dinner planned for today: its washed photo, name and
+// meta line, and the dark Recipe pill to its recipe.
+function TonightCard({ tonight }: { tonight: Tonight }) {
+  return (
+    <section aria-label="Tonight" className={styles.card}>
+      <Photo id={tonight.photo_id} name={tonight.name} inset="10px" sizes="400px" className={styles.photo} />
+      <div className={styles.cardFoot}>
+        <div className={styles.cardText}>
+          <h2 className={styles.name}>{tonight.name}</h2>
+          <span className={styles.meta}>{meta(tonight)}</span>
+        </div>
+        <Link to={`/dinner/${encodeURIComponent(tonight.id)}`} className={[buttonStyles.button, buttonStyles.dark, styles.recipe].join(' ')}>
+          Recipe
+        </Link>
+      </div>
+    </section>
+  )
+}
+
+// NoPlan stands in for the Tonight card when today has no plan.
+function NoPlan() {
+  const navigate = useNavigate()
+  return (
+    <div className={styles.card}>
+      <EmptyState title="No quest planned tonight" action={{ label: 'Plan this week', onClick: () => void navigate('/plan') }}>
+        Draft this week's dinners and tonight's quest shows up here.
+      </EmptyState>
+    </div>
+  )
+}
+
+// StatusRow is one neutral row under the tiles: a grape-700 icon, its line
+// and a chevron, linking to the screen it is about.
+function StatusRow({ to, icon, children }: { to: string; icon: LucideIcon; children: string }) {
+  return (
+    <li>
+      <Link to={to} className={styles.status}>
+        <Icon icon={icon} className={styles.statusIcon} />
+        <span className={styles.statusText}>{children}</span>
+        <Icon icon={ChevronRight} />
+      </Link>
+    </li>
+  )
+}
+
+// StatusRows are the rows that apply: Side quests waiting in the deck, and
+// a Supply run ready. With neither, there are no rows.
+function StatusRows({ home }: { home: Home }) {
+  const count = home.sideQuestCount
+  const list = home.shoppingList
+  if (count === 0 && !list.ready) return null
+  return (
+    <ul aria-label="Status" className={styles.statuses}>
+      {count > 0 && (
+        <StatusRow to="/discover" icon={Compass}>
+          {`${count} new side ${count === 1 ? 'quest' : 'quests'} to swipe`}
+        </StatusRow>
+      )}
+      {list.ready && (
+        <StatusRow to={supplyRunScreen(list.weekStart)} icon={ShoppingCart}>
+          {`Shopping list ready · ${list.dates}`}
+        </StatusRow>
+      )}
+    </ul>
+  )
+}
+
+// Tiles are the two shortcuts, Quick dinner and Cook from what I have.
+function Tiles() {
+  return (
+    <div className={styles.tiles}>
+      <Link to="/quick" className={[styles.tile, styles.quick].join(' ')}>
+        <Icon icon={Zap} size="nav" />
+        <span className={styles.tileLabel}>Quick dinner</span>
+      </Link>
+      <Link to="/cook-from-pantry" className={[styles.tile, styles.pantry].join(' ')}>
+        <Icon icon={Search} size="nav" />
+        <span className={styles.tileLabel}>Cook from what I have</span>
+      </Link>
+    </div>
+  )
+}
+
+// HomePage is mock 1g, Home: today's date over "Tonight's quest" and the
+// Recent updates bell, the Tonight card (or the way to plan the week), the
+// Quick dinner and Cook from what I have tiles, and the status rows, all
+// from GET /api/v1/home. Above the tiles is the Rotation check, "Keep it in
+// rotation?", while a tried dinner waits for the household's answer.
+//
+// The bell carries a grape dot while there are unread updates and opens the
+// Recent updates sheet, which marks them seen.
+export function HomePage() {
+  const home = useHome()
+  const data = home.data
+  const [updatesOpen, setUpdatesOpen] = useState(false)
+  return (
+    <div className={styles.page} aria-busy={home.isPending}>
+      <header className={styles.header}>
+        <div>
+          {data !== undefined ? (
+            <p className={styles.date}>{data.dateLabel}</p>
+          ) : (
+            home.isPending && <Skeleton data-testid="skeleton-date" className={styles.skeletonDate} />
+          )}
+          <h1 className={styles.title}>Tonight's quest</h1>
+        </div>
+        <IconButton
+          label={data?.unread ? 'Recent updates, unread' : 'Recent updates'}
+          className={styles.bell}
+          onClick={() => setUpdatesOpen(true)}
+        >
+          <Icon icon={Bell} className={styles.bellIcon} />
+          {data?.unread && <span data-testid="unread-dot" className={styles.dot} />}
+        </IconButton>
+      </header>
+      {home.isPending && <Skeleton data-testid="skeleton-tonight" className={styles.skeletonCard} />}
+      {home.isError && (
+        <ErrorBanner onRetry={() => void home.refetch()}>Couldn't load tonight's quest. {home.error.message}</ErrorBanner>
+      )}
+      {data !== undefined && (data.tonight === null ? <NoPlan /> : <TonightCard tonight={data.tonight} />)}
+      <RotationCheck />
+      <Tiles />
+      {home.isPending && (
+        <div className={styles.statuses} aria-hidden="true">
+          <Skeleton data-testid="skeleton-status" className={styles.skeletonStatus} />
+          <Skeleton data-testid="skeleton-status" className={styles.skeletonStatus} />
+        </div>
+      )}
+      {data !== undefined && <StatusRows home={data} />}
+      <UpdatesSheet open={updatesOpen} onClose={() => setUpdatesOpen(false)} />
+    </div>
+  )
+}

web/src/home/RotationCheck.module.css

@@ -0,0 +1,79 @@
+/* The Rotation check on Home: "Keep it in rotation?" above the tiles. */
+.card {
+  display: flex;
+  flex-direction: column;
+  border-radius: 32px;
+  background: var(--color-surface);
+  overflow: hidden;
+}
+
+.photo {
+  height: 120px;
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 4px 18px 12px;
+}
+
+.kicker {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.question {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+.actions {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+  margin-top: 6px;
+}
+
+/* "We didn't make it": a text link at the 44 px tap minimum. */
+.notMade {
+  align-self: center;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 4px;
+  border: 0;
+  background: transparent;
+  color: var(--color-accent-700);
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.notMade:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.notMade:focus-visible {
+  outline: 3px solid var(--color-accent);
+  outline-offset: 2px;
+}
+
+.confirmation {
+  margin: 0;
+  padding: 12px 14px;
+  border-radius: 20px;
+  background: var(--color-accent-2-300);
+  color: var(--color-accent-2-900);
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+}

web/src/home/RotationCheck.test.tsx

@@ -0,0 +1,320 @@
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { createMemoryRouter, RouterProvider } from 'react-router'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { clickPath, openNotification, parsePushPayload, type ClickWindow } from '../push/notification.ts'
+import { QueryClientProvider } from '@tanstack/react-query'
+import { ApiProvider, createApiClient, createQueryClient, createVerifiedSession, ME_PATH } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { HOME } from '../test/ApiProviders.tsx'
+import { errorResponse, fakeLocation, jsonResponse, ME } from '../test/fetchStub.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { HOME_PATH } from './api.ts'
+import { HomePage } from './HomePage.tsx'
+import { rotationReviewPath, ROTATION_REVIEWS_PATH } from './rotation.ts'
+
+// SHAKSHUKA and RAMEN are pending Rotation checks, oldest first, as GET
+// /api/v1/rotation-reviews sends them.
+const SHAKSHUKA = { dinner: { id: 'd7', name: 'Shakshuka', photo: '/media/photos/p7-400.jpg' }, plan_date: '2026-10-01' }
+const RAMEN = { dinner: { id: 'd8', name: 'Miso ramen', photo: null }, plan_date: '2026-10-02' }
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  Reflect.deleteProperty(navigator, 'serviceWorker')
+})
+
+type Deferred = { resolve: (response: Response) => void; path: string; body: unknown }
+
+// stubApi answers Home's reads like the server: the pending Rotation checks
+// are reviews, and each POST /api/v1/dinners/{id}/rotation-review waits in
+// decisions until the test answers it; a 200 answer takes the check off the
+// server's list, as the server does.
+function stubApi(reviews: (typeof SHAKSHUKA | typeof RAMEN)[]) {
+  const server = [...reviews]
+  const decisions: Deferred[] = []
+  const fetchMock = vi.fn<typeof fetch>((input, init) => {
+    const path = String(input)
+    if (path === ME_PATH) return Promise.resolve(jsonResponse(200, ME))
+    if (path === HOME_PATH) return Promise.resolve(jsonResponse(200, HOME))
+    if (path === ROTATION_REVIEWS_PATH) return Promise.resolve(jsonResponse(200, { reviews: server }))
+    const review = server.find((r) => rotationReviewPath(r.dinner.id) === path)
+    if (init?.method === 'POST' && review !== undefined) {
+      expect(new Headers(init.headers).get('X-MealQuest-CSRF')).toBe(ME.csrfToken)
+      const body: unknown = JSON.parse(String(init.body))
+      return new Promise<Response>((resolve) =>
+        decisions.push({
+          path,
+          body,
+          resolve: (response) => {
+            if (response.ok) server.splice(server.indexOf(review), 1)
+            resolve(response)
+          },
+        }),
+      )
+    }
+    throw new Error(`unexpected fetch: ${init?.method ?? 'GET'} ${path}`)
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return { fetchMock, decisions, server }
+}
+
+// decided is the server's answer to a decision on review.
+function decided(review: typeof SHAKSHUKA | typeof RAMEN, decision: string, dinnerStatus: string) {
+  return jsonResponse(200, {
+    dinner: review.dinner,
+    plan_date: review.plan_date,
+    decision,
+    dinner_status: dinnerStatus,
+    decided_at: '2026-10-02T13:00:00Z',
+    updated_by: 'sub-1',
+  })
+}
+
+// renderHome loads /me (for the CSRF token an answer needs) and renders Home
+// at path.
+async function renderHome(path = '/') {
+  const api = createApiClient(fakeLocation(path), createNetworkStatus(window), createVerifiedSession(localStorage))
+  await api.loadMe()
+  const router = createMemoryRouter([{ path: '/', element: <HomePage /> }], { initialEntries: [path] })
+  render(
+    <ApiProvider client={api}>
+      <QueryClientProvider client={createQueryClient()}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>
+    </ApiProvider>,
+  )
+}
+
+const card = () => screen.findByRole('region', { name: 'Keep it in rotation?' })
+const posts = (fetchMock: ReturnType<typeof stubApi>['fetchMock']) =>
+  fetchMock.mock.calls.filter(([, init]) => init?.method === 'POST')
+
+describe('RotationCheck', () => {
+  it('shows no card when nothing waits for an answer', async () => {
+    const { fetchMock } = stubApi([])
+    await renderHome()
+
+    expect(await screen.findByRole('heading', { name: 'Pizza night' })).toBeInTheDocument()
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledWith(ROTATION_REVIEWS_PATH, expect.anything()))
+    expect(screen.queryByRole('region', { name: 'Keep it in rotation?' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('status')).not.toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'Quick dinner' })).toBeInTheDocument()
+  })
+
+  it('asks about the oldest pending check above the tiles, and decides nothing by itself', async () => {
+    const { fetchMock } = stubApi([SHAKSHUKA, RAMEN])
+    await renderHome()
+
+    const check = await card()
+    expect(within(check).getByText('Last night: Shakshuka')).toBeInTheDocument()
+    expect(within(check).getByRole('heading', { level: 2, name: 'Keep it in rotation?' })).toBeInTheDocument()
+    expect(within(check).getByRole('img', { name: 'Shakshuka' })).toHaveAttribute('src', '/media/photos/p7-400.jpg')
+    expect(screen.queryByText('Last night: Miso ramen')).not.toBeInTheDocument()
+
+    const keep = within(check).getByRole('button', { name: 'Keep it' })
+    const drop = within(check).getByRole('button', { name: 'Not for us' })
+    const notMade = within(check).getByRole('button', { name: "We didn't make it" })
+    expect(keep.className).toMatch(/primary/)
+    expect(drop.className).toMatch(/outline/)
+    expect(notMade.className).toMatch(/notMade/)
+    for (const button of [keep, drop, notMade]) expectMinHitArea(button)
+
+    const tiles = screen.getByRole('link', { name: 'Quick dinner' })
+    expect(check.compareDocumentPosition(tiles) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+    expect(screen.getByRole('region', { name: 'Tonight' }).compareDocumentPosition(check) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+
+    // The card waits for the household: nothing is sent unasked.
+    await act(() => new Promise((resolve) => setTimeout(resolve, 50)))
+    expect(posts(fetchMock)).toHaveLength(0)
+    expect(await card()).toBeInTheDocument()
+  })
+
+  it.each([
+    ['Keep it', 'keep', 'regular', 'Added to your Regulars'],
+    ['Not for us', 'drop', 'archived', "Got it — we won't suggest it again"],
+    ["We didn't make it", 'not_made', 'quest_log', 'Back in your Quest log'],
+  ])('"%s" sends %s at once and confirms "%s"', async (label, decision, status, confirmation) => {
+    const { fetchMock, decisions } = stubApi([SHAKSHUKA])
+    await renderHome()
+
+    fireEvent.click(within(await card()).getByRole('button', { name: label }))
+
+    // Applied before the server answers.
+    expect(await screen.findByRole('status')).toHaveTextContent(confirmation)
+    expect(screen.queryByRole('region', { name: 'Keep it in rotation?' })).not.toBeInTheDocument()
+    await waitFor(() => expect(decisions).toHaveLength(1))
+    expect(decisions[0]).toMatchObject({ path: '/api/v1/dinners/d7/rotation-review', body: { decision } })
+    expect(posts(fetchMock)).toHaveLength(1)
+
+    act(() => decisions[0]!.resolve(decided(SHAKSHUKA, decision, status)))
+    // Rotation checks are read again once saved; none is left.
+    await waitFor(() =>
+      expect(fetchMock.mock.calls.filter(([path]) => path === ROTATION_REVIEWS_PATH).length).toBeGreaterThanOrEqual(2),
+    )
+    expect(screen.getByRole('status')).toHaveTextContent(confirmation)
+    expect(screen.queryByRole('region', { name: 'Keep it in rotation?' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('reveals the next pending check at once, its answers locked until the first is saved', async () => {
+    const { decisions } = stubApi([SHAKSHUKA, RAMEN])
+    await renderHome()
+
+    fireEvent.click(within(await card()).getByRole('button', { name: 'Keep it' }))
+
+    expect(await screen.findByText('Last night: Miso ramen')).toBeInTheDocument()
+    const next = await card()
+    expect(within(next).getByRole('img', { name: 'Miso ramen' })).toHaveTextContent('dish photo')
+    expect(screen.getByRole('status')).toHaveTextContent('Added to your Regulars')
+    for (const button of within(next).getAllByRole('button')) expect(button).toBeDisabled()
+
+    await waitFor(() => expect(decisions).toHaveLength(1))
+    act(() => decisions[0]!.resolve(decided(SHAKSHUKA, 'keep', 'regular')))
+    await waitFor(() => expect(within(next).getByRole('button', { name: 'Not for us' })).toBeEnabled())
+
+    fireEvent.click(within(next).getByRole('button', { name: 'Not for us' }))
+    expect(await screen.findByRole('status')).toHaveTextContent("Got it — we won't suggest it again")
+    await waitFor(() => expect(decisions).toHaveLength(2))
+    expect(decisions[1]).toMatchObject({ path: '/api/v1/dinners/d8/rotation-review', body: { decision: 'drop' } })
+    act(() => decisions[1]!.resolve(decided(RAMEN, 'drop', 'archived')))
+    await waitFor(() => expect(screen.queryByRole('region', { name: 'Keep it in rotation?' })).not.toBeInTheDocument())
+    expect(screen.queryByText(/Last night:/)).not.toBeInTheDocument()
+  })
+
+  it('puts the check back with an ErrorBanner when the answer fails', async () => {
+    const { decisions } = stubApi([SHAKSHUKA, RAMEN])
+    await renderHome()
+
+    fireEvent.click(within(await card()).getByRole('button', { name: 'Keep it' }))
+    expect(await screen.findByText('Last night: Miso ramen')).toBeInTheDocument()
+    await waitFor(() => expect(decisions).toHaveLength(1))
+
+    act(() => decisions[0]!.resolve(errorResponse(500, 'internal')))
+
+    expect(await screen.findByRole('alert')).toHaveTextContent("Couldn't save that answer. internal message")
+    const check = await card()
+    expect(within(check).getByText('Last night: Shakshuka')).toBeInTheDocument()
+    expect(screen.queryByRole('status')).not.toBeInTheDocument()
+    expect(within(check).getByRole('button', { name: 'Keep it' })).toBeEnabled()
+  })
+
+  it('reports an answer that is not that check decided that way, and shows what the server has', async () => {
+    const { decisions } = stubApi([SHAKSHUKA])
+    await renderHome()
+
+    fireEvent.click(within(await card()).getByRole('button', { name: 'Keep it' }))
+    await waitFor(() => expect(decisions).toHaveLength(1))
+    act(() => decisions[0]!.resolve(decided(SHAKSHUKA, 'drop', 'archived')))
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('response is not the Rotation check decided keep')
+    expect(screen.queryByRole('status')).not.toBeInTheDocument()
+    // The server closed the check, so the list read again has none.
+    await waitFor(() => expect(screen.queryByRole('region', { name: 'Keep it in rotation?' })).not.toBeInTheDocument())
+  })
+
+  it('reports Rotation checks it cannot load, with Retry', async () => {
+    const answers = [errorResponse(500, 'internal'), jsonResponse(200, { reviews: [SHAKSHUKA] })]
+    vi.stubGlobal(
+      'fetch',
+      vi.fn<typeof fetch>((input) =>
+        Promise.resolve(
+          String(input) === ME_PATH
+            ? jsonResponse(200, ME)
+            : String(input) === HOME_PATH
+              ? jsonResponse(200, HOME)
+              : answers.shift()!,
+        ),
+      ),
+    )
+    await renderHome()
+
+    expect(await screen.findByRole('alert')).toHaveTextContent("Couldn't load the Rotation check. internal message")
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+    expect(within(await card()).getByText('Last night: Shakshuka')).toBeInTheDocument()
+  })
+
+  it('keeps a card already shown, with an ErrorBanner beside it, when reading the checks again fails', async () => {
+    // navigator.serviceWorker is where the worker's postMessage to this
+    // window arrives; a notification tap there reads the checks again.
+    const container = new EventTarget()
+    Object.defineProperty(navigator, 'serviceWorker', { configurable: true, value: container })
+    const answers = [jsonResponse(200, { reviews: [SHAKSHUKA] }), errorResponse(500, 'internal')]
+    vi.stubGlobal(
+      'fetch',
+      vi.fn<typeof fetch>((input) =>
+        Promise.resolve(
+          String(input) === ME_PATH
+            ? jsonResponse(200, ME)
+            : String(input) === HOME_PATH
+              ? jsonResponse(200, HOME)
+              : answers.shift()!,
+        ),
+      ),
+    )
+    await renderHome()
+    expect(within(await card()).getByText('Last night: Shakshuka')).toBeInTheDocument()
+
+    const origin = 'https://mealquest.test'
+    const win = {
+      url: `${origin}/`,
+      focused: true,
+      focus: vi.fn(async () => {}),
+      navigate: vi.fn(async () => {}),
+      postMessage: (message) => container.dispatchEvent(new MessageEvent('message', { data: message })),
+    } satisfies ClickWindow
+    await act(() =>
+      openNotification({ url: '/' }, { matchAll: async () => [win], openWindow: vi.fn(async () => null) }, origin),
+    )
+
+    expect(await screen.findByRole('alert')).toHaveTextContent("Couldn't load the Rotation check. internal message")
+    const shown = screen.getByRole('region', { name: 'Keep it in rotation?' })
+    expect(within(shown).getByText('Last night: Shakshuka')).toBeInTheDocument()
+    expect(within(shown).getByRole('button', { name: 'Keep it' })).toBeEnabled()
+  })
+
+  it('opens Home with the card from a rotation_review push notification', async () => {
+    stubApi([SHAKSHUKA])
+    const origin = 'https://mealquest.test'
+    const { notice } = parsePushPayload(
+      JSON.stringify({ event: 'rotation_review', title: 'Keep it in rotation?', body: 'How was Shakshuka?', url: '/' }),
+      origin,
+    )
+    const path = clickPath({ url: notice.url }, origin)
+    expect(path).toBe('/')
+
+    await renderHome(path)
+    expect(within(await card()).getByText('Last night: Shakshuka')).toBeInTheDocument()
+  })
+
+  it('shows the card when a rotation_review notification focuses Home already open, without a remount', async () => {
+    // navigator.serviceWorker is where the worker's postMessage to this
+    // window arrives.
+    const container = new EventTarget()
+    Object.defineProperty(navigator, 'serviceWorker', { configurable: true, value: container })
+    const { fetchMock, server } = stubApi([])
+    const reads = () => fetchMock.mock.calls.filter(([path]) => path === ROTATION_REVIEWS_PATH).length
+    await renderHome('/')
+    const home = await screen.findByRole('heading', { name: 'Pizza night' })
+    await waitFor(() => expect(reads()).toBe(1))
+    expect(screen.queryByRole('region', { name: 'Keep it in rotation?' })).not.toBeInTheDocument()
+
+    // Within the cached list's staleTime the Rotation check comes due and
+    // its notification is tapped while Home is open at /.
+    server.push(SHAKSHUKA)
+    const origin = 'https://mealquest.test'
+    const win = {
+      url: `${origin}/`,
+      focused: true,
+      focus: vi.fn(async () => {}),
+      navigate: vi.fn(async () => {}),
+      postMessage: (message) => container.dispatchEvent(new MessageEvent('message', { data: message })),
+    } satisfies ClickWindow
+    await act(() =>
+      openNotification({ url: '/' }, { matchAll: async () => [win], openWindow: vi.fn(async () => null) }, origin),
+    )
+
+    expect(win.navigate).not.toHaveBeenCalled()
+    expect(within(await card()).getByText('Last night: Shakshuka')).toBeInTheDocument()
+    expect(reads()).toBe(2)
+    expect(screen.getByRole('heading', { name: 'Pizza night' })).toBe(home)
+  })
+})

web/src/home/RotationCheck.tsx

@@ -0,0 +1,79 @@
+import { Button } from '../ui/Button.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Photo } from '../ui/Photo.tsx'
+import { useDecideRotationReview, useRotationReviews, type Decision, type RotationReview } from './rotation.ts'
+import styles from './RotationCheck.module.css'
+
+// CONFIRMATION is what Home says once the household has answered.
+const CONFIRMATION: Record<Decision, string> = {
+  keep: 'Added to your Regulars',
+  drop: "Got it — we won't suggest it again",
+  not_made: 'Back in your Quest log',
+}
+
+type RotationCardProps = { review: RotationReview; disabled: boolean; onDecide: (decision: Decision) => void }
+
+// RotationCard asks "Keep it in rotation?" about a tried dinner: its washed
+// photo, "Last night: {dinner}", and the three answers.
+function RotationCard({ review, disabled, onDecide }: RotationCardProps) {
+  const { dinner } = review
+  return (
+    <section aria-label="Keep it in rotation?" className={styles.card}>
+      <Photo id={dinner.photo_id} name={dinner.name} inset="10px" sizes="400px" className={styles.photo} />
+      <div className={styles.body}>
+        <p className={styles.kicker}>Last night: {dinner.name}</p>
+        <h2 className={styles.question}>Keep it in rotation?</h2>
+        <div className={styles.actions}>
+          <Button disabled={disabled} onClick={() => onDecide('keep')}>
+            Keep it
+          </Button>
+          <Button variant="outline" disabled={disabled} onClick={() => onDecide('drop')}>
+            Not for us
+          </Button>
+        </div>
+        <button type="button" className={styles.notMade} disabled={disabled} onClick={() => onDecide('not_made')}>
+          We didn't make it
+        </button>
+      </div>
+    </section>
+  )
+}
+
+// RotationCheck is the Rotation check on Home: the card for the oldest
+// pending check (GET /api/v1/rotation-reviews), which stays until the
+// household answers it — nothing is decided for them. An answer is applied
+// at once: Home confirms it and shows the next pending check, if any, while
+// the answer is saved; the answers are locked until it settles. A failed
+// answer puts its check back with an ErrorBanner. A failed read shows an
+// ErrorBanner, beside the checks last read: a card already shown stays
+// until it is answered.
+export function RotationCheck() {
+  const reviews = useRotationReviews()
+  const decide = useDecideRotationReview()
+  const deciding = decide.isPending ? decide.variables.review.dinner.id : null
+  const next = reviews.data?.find((review) => review.dinner.id !== deciding)
+  const answered = decide.isPending || decide.isSuccess ? decide.variables : undefined
+  return (
+    <>
+      {answered !== undefined && (
+        <p role="status" className={styles.confirmation}>
+          {CONFIRMATION[answered.decision]}
+        </p>
+      )}
+      {reviews.isError && (
+        <ErrorBanner onRetry={() => void reviews.refetch()}>
+          Couldn't load the Rotation check. {reviews.error.message}
+        </ErrorBanner>
+      )}
+      {decide.isError && <ErrorBanner>Couldn't save that answer. {decide.error.message}</ErrorBanner>}
+      {next !== undefined && (
+        <RotationCard
+          key={next.dinner.id}
+          review={next}
+          disabled={decide.isPending}
+          onDecide={(decision) => decide.mutate({ review: next, decision })}
+        />
+      )}
+    </>
+  )
+}

web/src/home/UpdatesSheet.module.css

@@ -0,0 +1,49 @@
+/* The Recent updates sheet the Home bell opens. */
+.sheet {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  max-width: 560px;
+  margin: 0 auto;
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+}
+
+.rows {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+.icon {
+  color: var(--color-accent-700);
+}
+
+.time {
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+  white-space: nowrap;
+}
+
+.skeletonRow {
+  height: 56px;
+  border-radius: var(--radius-md);
+}
+
+.empty {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--color-neutral-700);
+}

web/src/home/UpdatesSheet.test.tsx

@@ -0,0 +1,383 @@
+import { QueryClientProvider } from '@tanstack/react-query'
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { createMemoryRouter, RouterProvider, useLocation } from 'react-router'
+import { afterEach, describe, expect, it, vi, type Mock } from 'vitest'
+import { ApiProvider, createApiClient, createQueryClient, createVerifiedSession } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { HOME } from '../test/ApiProviders.tsx'
+import { errorResponse, fakeLocation, jsonResponse, ME } from '../test/fetchStub.ts'
+import { HOME_KEY, HOME_PATH, UPDATES_PATH, UPDATES_SEEN_PATH } from './api.ts'
+import { ROTATION_REVIEWS_PATH } from './rotation.ts'
+import { HomePage } from './HomePage.tsx'
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+// minutesAgo is the stored form of the instant n minutes before now.
+function minutesAgo(n: number): string {
+  return new Date(Date.now() - n * 60_000).toISOString()
+}
+
+// UPDATES are a GET /api/v1/updates body, newest first: the week drafted
+// five minutes ago, new Side quests three hours ago and the Supply run two
+// days ago.
+const UPDATES = {
+  updates: [
+    {
+      type: 'plan_ready',
+      title: 'Your week is drafted',
+      body: 'Take a look at the Draft board.',
+      url: '/plan?week=2026-10-12',
+      created_at: minutesAgo(5),
+    },
+    { type: 'new_suggestions', title: '5 new Side quests', body: '', url: '/discover', created_at: minutesAgo(3 * 60) },
+    {
+      type: 'list_ready',
+      title: 'Supply run ready',
+      body: 'Week 41 · Oct 5 – 11',
+      url: '/plan/shopping?week=2026-10-05',
+      created_at: minutesAgo(2 * 24 * 60),
+    },
+  ],
+}
+
+type Responder = (init: RequestInit | undefined) => Response | Promise<Response>
+
+// stubServer answers "METHOD path" requests from responders, with /me; any
+// other request fails the test. Home is unread until the updates are marked
+// seen, as the server answers.
+function stubServer(responders: Record<string, Responder> = {}) {
+  let seen = false
+  const all: Record<string, Responder> = {
+    'GET /api/v1/me': () => jsonResponse(200, ME),
+    [`GET ${HOME_PATH}`]: () => jsonResponse(200, { ...HOME, recentUpdates: { unread: !seen } }),
+    [`GET ${UPDATES_PATH}`]: () => jsonResponse(200, UPDATES),
+    [`GET ${ROTATION_REVIEWS_PATH}`]: () => jsonResponse(200, { reviews: [] }),
+    [`POST ${UPDATES_SEEN_PATH}`]: () => {
+      seen = true
+      return new Response(null, { status: 204 })
+    },
+    ...responders,
+  }
+  const fetchMock = vi.fn<typeof fetch>((input, init) => {
+    const key = `${init?.method ?? 'GET'} ${String(input)}`
+    const respond = Object.hasOwn(all, key) ? all[key] : undefined
+    if (respond === undefined) throw new Error(`unexpected fetch: ${key}`)
+    return Promise.resolve(respond(init))
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+// posts lists the bodies of the POST /updates/seen requests sent, each of
+// which must carry the CSRF token.
+function posts(fetchMock: Mock<typeof fetch>) {
+  return fetchMock.mock.calls
+    .filter(([input, init]) => init?.method === 'POST' && String(input) === UPDATES_SEEN_PATH)
+    .map(([, init]) => {
+      expect(new Headers(init?.headers).get('X-MealQuest-CSRF')).toBe(ME.csrfToken)
+      return String(init?.body)
+    })
+}
+
+function homeReads(fetchMock: Mock<typeof fetch>) {
+  return fetchMock.mock.calls.filter(([input, init]) => String(input) === HOME_PATH && (init?.method ?? 'GET') === 'GET')
+    .length
+}
+
+function updatesReads(fetchMock: Mock<typeof fetch>) {
+  return fetchMock.mock.calls.filter(
+    ([input, init]) => String(input) === UPDATES_PATH && (init?.method ?? 'GET') === 'GET',
+  ).length
+}
+
+// Where shows the route a row went to.
+function Where() {
+  const location = useLocation()
+  return <p data-testid="where">{location.pathname + location.search}</p>
+}
+
+// renderHome loads /me (for the CSRF token the POST needs) and renders Home,
+// answering its query client.
+async function renderHome() {
+  const api = createApiClient(fakeLocation('/'), createNetworkStatus(window), createVerifiedSession(localStorage))
+  await api.loadMe()
+  const router = createMemoryRouter(
+    [
+      { path: '/', element: <HomePage /> },
+      { path: '*', element: <Where /> },
+    ],
+    { initialEntries: ['/'] },
+  )
+  const queryClient = createQueryClient()
+  render(
+    <ApiProvider client={api}>
+      <QueryClientProvider client={queryClient}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>
+    </ApiProvider>,
+  )
+  return queryClient
+}
+
+// openSheet taps the unread bell and answers the open sheet.
+async function openSheet() {
+  fireEvent.click(await screen.findByRole('button', { name: 'Recent updates, unread' }))
+  return screen.getByRole('dialog', { name: 'Recent updates' })
+}
+
+async function rows(sheet: HTMLElement) {
+  return within(await within(sheet).findByRole('list', { name: 'Recent updates' })).getAllByRole('listitem')
+}
+
+describe('Recent updates sheet', () => {
+  it('lists the updates newest first with how long ago each came', async () => {
+    stubServer()
+    await renderHome()
+    const listed = await rows(await openSheet())
+
+    expect(listed).toHaveLength(3)
+    expect(listed[0]).toHaveTextContent('Your week is drafted')
+    expect(listed[0]).toHaveTextContent('Take a look at the Draft board.')
+    expect(listed[0]).toHaveTextContent('5 min ago')
+    expect(listed[1]).toHaveTextContent('5 new Side quests')
+    expect(listed[1]).toHaveTextContent('3 hr ago')
+    expect(listed[2]).toHaveTextContent('Supply run ready')
+    expect(listed[2]).toHaveTextContent('2 days ago')
+    expect(within(listed[0]!).getByText('5 min ago')).toHaveAttribute('dateTime', UPDATES.updates[0]!.created_at)
+  })
+
+  it('marks the updates seen through the newest, and the grape dot clears and stays cleared', async () => {
+    const fetchMock = stubServer()
+    await renderHome()
+    expect(await screen.findByTestId('unread-dot')).toBeInTheDocument()
+    await openSheet()
+
+    await waitFor(() => expect(posts(fetchMock)).toEqual([JSON.stringify({ through: UPDATES.updates[0]!.created_at })]))
+    expect(screen.queryByTestId('unread-dot')).not.toBeInTheDocument()
+    // Home is read again once the mark is saved, and the server says
+    // nothing is unread: the dot does not come back.
+    await waitFor(() => expect(homeReads(fetchMock)).toBe(2))
+    fireEvent.keyDown(screen.getByRole('dialog'), { key: 'Escape' })
+    expect(await screen.findByRole('button', { name: 'Recent updates' })).toBeInTheDocument()
+    expect(screen.queryByTestId('unread-dot')).not.toBeInTheDocument()
+  })
+
+  it('reads the updates afresh on each opening, so one stored since the last opening is listed and marked seen', async () => {
+    // The server holds the stored events, newest first, and says Home is
+    // unread while the newest is after the time marked seen.
+    const stored = [...UPDATES.updates]
+    let seenThrough = ''
+    const fetchMock = stubServer({
+      [`GET ${HOME_PATH}`]: () => jsonResponse(200, { ...HOME, recentUpdates: { unread: stored[0]!.created_at > seenThrough } }),
+      [`GET ${UPDATES_PATH}`]: () => jsonResponse(200, { updates: stored }),
+      [`POST ${UPDATES_SEEN_PATH}`]: (init) => {
+        seenThrough = (JSON.parse(String(init?.body)) as { through: string }).through
+        return new Response(null, { status: 204 })
+      },
+    })
+    const queryClient = await renderHome()
+    await rows(await openSheet())
+    await waitFor(() => expect(posts(fetchMock)).toHaveLength(1))
+    await waitFor(() => expect(homeReads(fetchMock)).toBe(2))
+    fireEvent.keyDown(screen.getByRole('dialog'), { key: 'Escape' })
+
+    // A new event is stored a moment later, well within the query client's
+    // staleTime, and Home is read again, as on coming back to it.
+    const reminder = {
+      type: 'day_of_reminder',
+      title: 'Tacos tonight',
+      body: 'Dinner at 6:00.',
+      url: '/plan',
+      created_at: new Date().toISOString(),
+    }
+    stored.unshift(reminder)
+    await queryClient.invalidateQueries({ queryKey: HOME_KEY })
+    expect(await screen.findByTestId('unread-dot')).toBeInTheDocument()
+
+    const listed = await rows(await openSheet())
+    expect(listed).toHaveLength(4)
+    expect(listed[0]).toHaveTextContent('Tacos tonight')
+    await waitFor(() =>
+      expect(posts(fetchMock)).toEqual([
+        JSON.stringify({ through: UPDATES.updates[0]!.created_at }),
+        JSON.stringify({ through: reminder.created_at }),
+      ]),
+    )
+    await waitFor(() => expect(homeReads(fetchMock)).toBe(4))
+    expect(screen.queryByTestId('unread-dot')).not.toBeInTheDocument()
+  })
+
+  it('on an immediate reopen waits for that opening’s read, and marks the newer event seen, not the list held from before', async () => {
+    const stored = [...UPDATES.updates]
+    let reads = 0
+    let answer: (() => void) | undefined
+    const fetchMock = stubServer({
+      [`GET ${UPDATES_PATH}`]: () => {
+        const body = { updates: [...stored] }
+        reads++
+        // Every reading after the first is held until the test answers it.
+        if (reads === 1) return jsonResponse(200, body)
+        return new Promise<Response>((resolve) => (answer = () => resolve(jsonResponse(200, body))))
+      },
+    })
+    await renderHome()
+    await rows(await openSheet())
+    await waitFor(() => expect(posts(fetchMock)).toHaveLength(1))
+
+    // Closed and opened again at once, before any cache-collection timer
+    // could run, with a new event stored in between.
+    fireEvent.keyDown(screen.getByRole('dialog'), { key: 'Escape' })
+    const reminder = {
+      type: 'day_of_reminder',
+      title: 'Tacos tonight',
+      body: 'Dinner at 6:00.',
+      url: '/plan',
+      created_at: new Date().toISOString(),
+    }
+    stored.unshift(reminder)
+    fireEvent.click(screen.getByRole('button', { name: /^Recent updates/ }))
+    const sheet = screen.getByRole('dialog', { name: 'Recent updates' })
+
+    // The list held from the first opening is neither shown nor marked
+    // seen while this opening's read is in flight.
+    await waitFor(() => expect(updatesReads(fetchMock)).toBe(2))
+    expect(within(sheet).getByLabelText('Updates loading')).toBeInTheDocument()
+    expect(within(sheet).queryByRole('list')).not.toBeInTheDocument()
+    expect(posts(fetchMock)).toHaveLength(1)
+
+    answer!()
+    const listed = await rows(sheet)
+    expect(listed).toHaveLength(4)
+    expect(listed[0]).toHaveTextContent('Tacos tonight')
+    await waitFor(() =>
+      expect(posts(fetchMock)).toEqual([
+        JSON.stringify({ through: UPDATES.updates[0]!.created_at }),
+        JSON.stringify({ through: reminder.created_at }),
+      ]),
+    )
+  })
+
+  it('closing the sheet while its first read is in flight cancels that read, and a reopen reads afresh', async () => {
+    const stored = [...UPDATES.updates]
+    let firstAborted = false
+    let answerFirst: (() => void) | undefined
+    let reads = 0
+    const fetchMock = stubServer({
+      [`GET ${UPDATES_PATH}`]: (init) => {
+        const body = { updates: [...stored] }
+        reads++
+        if (reads > 1) return jsonResponse(200, body)
+        // The first reading is held open, and fails as fetch does if it is
+        // aborted.
+        return new Promise<Response>((resolve, reject) => {
+          answerFirst = () => resolve(jsonResponse(200, body))
+          init?.signal?.addEventListener('abort', () => {
+            firstAborted = true
+            reject(init.signal!.reason as Error)
+          })
+        })
+      },
+    })
+    await renderHome()
+    await openSheet()
+    await waitFor(() => expect(updatesReads(fetchMock)).toBe(1))
+
+    // Closed before the first read answers, a new event stored, and opened
+    // again at once.
+    fireEvent.keyDown(screen.getByRole('dialog'), { key: 'Escape' })
+    const reminder = {
+      type: 'day_of_reminder',
+      title: 'Tacos tonight',
+      body: 'Dinner at 6:00.',
+      url: '/plan',
+      created_at: new Date().toISOString(),
+    }
+    stored.unshift(reminder)
+    fireEvent.click(screen.getByRole('button', { name: /^Recent updates/ }))
+    const sheet = screen.getByRole('dialog', { name: 'Recent updates' })
+
+    // The first read was cancelled, and the reopen sent its own.
+    await waitFor(() => expect(updatesReads(fetchMock)).toBe(2))
+    expect(firstAborted).toBe(true)
+    // Answering the cancelled read changes nothing.
+    answerFirst!()
+
+    const listed = await rows(sheet)
+    expect(listed).toHaveLength(4)
+    expect(listed[0]).toHaveTextContent('Tacos tonight')
+    await waitFor(() => expect(posts(fetchMock)).toEqual([JSON.stringify({ through: reminder.created_at })]))
+  })
+
+  it.each([
+    [0, '/plan?week=2026-10-12'],
+    [1, '/discover'],
+    [2, '/plan/shopping?week=2026-10-05'],
+  ])('row %i goes to %s and closes the sheet', async (i, to) => {
+    stubServer()
+    await renderHome()
+    const listed = await rows(await openSheet())
+
+    fireEvent.click(within(listed[i]!).getByRole('button'))
+    expect(await screen.findByTestId('where')).toHaveTextContent(to)
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('says there are no updates yet, and marks nothing seen', async () => {
+    const fetchMock = stubServer({ [`GET ${UPDATES_PATH}`]: () => jsonResponse(200, { updates: [] }) })
+    await renderHome()
+    const sheet = await openSheet()
+
+    expect(await within(sheet).findByText(/No updates yet/)).toBeInTheDocument()
+    expect(within(sheet).queryByRole('list')).not.toBeInTheDocument()
+    expect(posts(fetchMock)).toEqual([])
+  })
+
+  it('puts the dot back and says so when marking the updates seen fails', async () => {
+    let refuse!: (response: Response) => void
+    const fetchMock = stubServer({
+      [`POST ${UPDATES_SEEN_PATH}`]: () => new Promise<Response>((resolve) => (refuse = resolve)),
+    })
+    await renderHome()
+    const sheet = await openSheet()
+
+    await waitFor(() => expect(posts(fetchMock)).toHaveLength(1))
+    // Cleared at once, while the mark is in flight.
+    expect(screen.queryByTestId('unread-dot')).not.toBeInTheDocument()
+
+    refuse(errorResponse(500, 'internal'))
+    expect(await within(sheet).findByRole('alert')).toHaveTextContent(
+      "Couldn't mark your updates as seen. internal message",
+    )
+    expect(screen.getByTestId('unread-dot')).toBeInTheDocument()
+    // The updates are still listed.
+    expect(within(sheet).getByRole('list', { name: 'Recent updates' })).toBeInTheDocument()
+  })
+
+  it('reports updates it cannot load, with Retry', async () => {
+    let fail = true
+    stubServer({ [`GET ${UPDATES_PATH}`]: () => (fail ? errorResponse(500, 'internal') : jsonResponse(200, UPDATES)) })
+    await renderHome()
+    const sheet = await openSheet()
+
+    expect(await within(sheet).findByRole('alert')).toHaveTextContent("Couldn't load your updates. internal message")
+    fail = false
+    fireEvent.click(within(sheet).getByRole('button', { name: 'Retry' }))
+    expect(await within(sheet).findByRole('list', { name: 'Recent updates' })).toBeInTheDocument()
+  })
+
+  it('reports an update that would open another site rather than listing it', async () => {
+    const fetchMock = stubServer({
+      [`GET ${UPDATES_PATH}`]: () => jsonResponse(200, { updates: [{ ...UPDATES.updates[0], url: '//evil.example/plan' }] }),
+    })
+    await renderHome()
+    const sheet = await openSheet()
+
+    expect(await within(sheet).findByRole('alert')).toHaveTextContent(
+      'update url "//evil.example/plan" is not a path on this app',
+    )
+    expect(within(sheet).queryByRole('list')).not.toBeInTheDocument()
+    expect(posts(fetchMock)).toEqual([])
+  })
+})

web/src/home/UpdatesSheet.tsx

@@ -0,0 +1,117 @@
+import { CalendarDays, ChefHat, Compass, Repeat, ShoppingCart, type LucideIcon } from 'lucide-react'
+import { useEffect, useId, useState } from 'react'
+import { useNavigate } from 'react-router'
+import { ago } from '../plan/PlanPage.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { ListRow } from '../ui/ListRow.tsx'
+import { Sheet } from '../ui/Sheet.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { useMarkUpdatesSeen, useUpdates, type Update, type UpdateType } from './api.ts'
+import styles from './UpdatesSheet.module.css'
+
+const ICONS: Record<UpdateType, LucideIcon> = {
+  plan_ready: CalendarDays,
+  list_ready: ShoppingCart,
+  day_of_reminder: ChefHat,
+  new_suggestions: Compass,
+  rotation_review: Repeat,
+}
+
+// UpdateRow is one update: its icon, title and body, and how long ago it
+// came. A tap opens its url.
+function UpdateRow({ update, now, onOpen }: { update: Update; now: Date; onOpen: (url: string) => void }) {
+  return (
+    <li>
+      <ListRow
+        leading={<Icon icon={ICONS[update.type]} className={styles.icon} />}
+        title={update.title}
+        meta={update.body === '' ? undefined : update.body}
+        trailing={
+          <time dateTime={update.created_at} className={styles.time}>
+            {ago(new Date(update.created_at), now)}
+          </time>
+        }
+        onClick={() => onOpen(update.url)}
+      />
+    </li>
+  )
+}
+
+// Updates lists the Recent updates, newest first, and marks them seen
+// through the newest once they are shown, so the bell's dot clears.
+function Updates({ onOpen }: { onOpen: (url: string) => void }) {
+  const updates = useUpdates()
+  const markSeen = useMarkUpdatesSeen()
+  const { mutate } = markSeen
+  // fresh says this opening's read has come back; until then a list still
+  // held from an earlier opening is neither shown nor marked seen.
+  const fresh = updates.isSuccess && updates.isFetchedAfterMount
+  const newest = fresh ? updates.data[0]?.created_at : undefined
+  // The instant the relative times count from, fixed while the sheet is
+  // open.
+  const [now] = useState(() => new Date())
+
+  useEffect(() => {
+    if (newest !== undefined) mutate(newest)
+  }, [newest, mutate])
+
+  if (updates.isError) {
+    return (
+      <ErrorBanner onRetry={() => void updates.refetch()}>Couldn't load your updates. {updates.error.message}</ErrorBanner>
+    )
+  }
+  if (!fresh) {
+    return (
+      <div aria-busy="true" aria-label="Updates loading" className={styles.rows}>
+        {Array.from({ length: 3 }, (_, i) => (
+          <Skeleton key={i} className={styles.skeletonRow} />
+        ))}
+      </div>
+    )
+  }
+  if (updates.data.length === 0) {
+    return <p className={styles.empty}>No updates yet. Plans, Supply runs and new Side quests show up here.</p>
+  }
+  return (
+    <>
+      {markSeen.isError && newest !== undefined && (
+        <ErrorBanner onRetry={() => mutate(newest)}>
+          Couldn't mark your updates as seen. {markSeen.error.message}
+        </ErrorBanner>
+      )}
+      <ul aria-label="Recent updates" className={styles.rows}>
+        {updates.data.map((update, i) => (
+          <UpdateRow key={`${i} ${update.created_at}`} update={update} now={now} onOpen={onOpen} />
+        ))}
+      </ul>
+    </>
+  )
+}
+
+export type UpdatesSheetProps = {
+  open: boolean
+  onClose: () => void
+}
+
+// UpdatesSheet is the Recent updates sheet the Home bell opens: the last
+// ten notification events with how long ago each came, each opening the
+// screen it is about. Opening it marks them seen.
+export function UpdatesSheet({ open, onClose }: UpdatesSheetProps) {
+  const titleId = useId()
+  const navigate = useNavigate()
+  const openUpdate = (url: string) => {
+    onClose()
+    void navigate(url)
+  }
+  return (
+    <Sheet open={open} onClose={onClose} aria-labelledby={titleId}>
+      <div className={styles.sheet}>
+        <h2 id={titleId} className={styles.title}>
+          Recent updates
+        </h2>
+        <Updates onOpen={openUpdate} />
+      </div>
+    </Sheet>
+  )
+}

web/src/home/api.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import { HOME } from '../test/ApiProviders.tsx'
+import { parseHome, parseUpdates } from './api.ts'
+
+const origin = 'https://mealquest.example'
+const where = 'GET /api/v1/updates'
+
+// body is a GET /api/v1/updates body holding one update that opens url.
+function body(url: string) {
+  return {
+    updates: [{ type: 'plan_ready', title: 'Your week is drafted', body: '', url, created_at: '2026-10-10T16:00:00.000Z' }],
+  }
+}
+
+describe('parseUpdates', () => {
+  it('keeps a same-origin path with its query and fragment, as parsed', () => {
+    expect(parseUpdates(where, body('/plan/shopping?week=2026-10-05#tuesday'), origin)[0]!.url).toBe(
+      '/plan/shopping?week=2026-10-05#tuesday',
+    )
+    expect(parseUpdates(where, body('/plan/../discover'), origin)[0]!.url).toBe('/discover')
+  })
+
+  // Each of these would open another site, or run script, once parsed: URL
+  // parsing strips tabs and newlines and reads a backslash as a slash.
+  it.each([
+    ['a tab', '/\t/evil.example/x'],
+    ['a newline', '/\n/evil.example/x'],
+    ['a carriage return', '/\r/evil.example/x'],
+    ['a backslash', '/\\evil.example/x'],
+    ['dot segments', '/..//evil.example/x'],
+    ['a protocol-relative URL', '//evil.example/x'],
+    ['an absolute URL', 'https://evil.example/x'],
+    ['javascript:', 'javascript:alert(1)'],
+    ['a relative path', 'plan'],
+  ])('refuses an update url with %s', (_, url) => {
+    expect(() => parseUpdates(where, body(url), origin)).toThrow(
+      `${where}: update url ${JSON.stringify(url)} is not a path on this app`,
+    )
+  })
+})
+
+describe('parseHome', () => {
+  it("keeps the household's zone, and refuses one that is not an IANA zone", () => {
+    expect(parseHome('GET /api/v1/home', HOME).timezone).toBe('America/New_York')
+    expect(() => parseHome('GET /api/v1/home', { ...HOME, timezone: 'Mars/Olympus' })).toThrow(
+      'GET /api/v1/home: timezone "Mars/Olympus" is not an IANA zone',
+    )
+    expect(() => parseHome('GET /api/v1/home', { ...HOME, timezone: undefined })).toThrow(
+      'GET /api/v1/home: timezone undefined is not an IANA zone',
+    )
+  })
+})

web/src/home/api.ts

@@ -0,0 +1,230 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useEffect } from 'react'
+import { useApi } from '../api/index.ts'
+import { isRecord } from '../api/errors.ts'
+import { oneOf, photoId } from '../dinners/api.ts'
+import { untilLocalMidnight, weekLabel } from '../plan/week.ts'
+import { appPath } from '../push/notification.ts'
+
+export const HOME_PATH = '/api/v1/home'
+export const HOME_KEY = ['home'] as const
+export const UPDATES_PATH = '/api/v1/updates'
+export const UPDATES_SEEN_PATH = '/api/v1/updates/seen'
+export const UPDATES_KEY = ['updates'] as const
+
+export const ORIGINS = ['regular', 'side_quest'] as const
+export type Origin = (typeof ORIGINS)[number]
+
+// Tonight is the dinner planned for today: photo_id is its stored photo's
+// id, from photo, and minutes_total its minutes from prep to table, a
+// positive whole number, or null when the recipe does not say.
+export type Tonight = { id: string; name: string; photo_id: string | undefined; origin: Origin; minutes_total: number | null }
+
+// ShoppingListStatus is the Supply run Home points at: next week's once it
+// has one, otherwise this week's, ready when that week has a list.
+// weekStart is the week's Monday, YYYY-MM-DD, and dates the week as the
+// status row shows it, "Oct 5–11" (the API's label is the long "Week 41 ·
+// Oct 5 – 11").
+export type ShoppingListStatus = { weekStart: string; dates: string; ready: boolean }
+
+// Home is GET /api/v1/home: dateLabel is today, household-local, "Friday,
+// Oct 2"; timezone is the household's IANA zone, whose midnight starts the
+// next day; tonight is null when today has no plan; sideQuestCount is how
+// many Side quests wait in the deck; unread says the Recent updates hold
+// something not yet seen.
+export type Home = {
+  dateLabel: string
+  timezone: string
+  tonight: Tonight | null
+  sideQuestCount: number
+  shoppingList: ShoppingListStatus
+  unread: boolean
+}
+
+function parseTonight(where: string, body: unknown): Tonight | null {
+  if (body === null) return null
+  if (!isRecord(body) || typeof body.id !== 'string' || typeof body.name !== 'string') {
+    throw new Error(`${where}: tonight is not a dinner`)
+  }
+  if (!('minutes_total' in body)) throw new Error(`${where}: tonight has no minutes_total`)
+  const minutes = body.minutes_total
+  if (minutes !== null && (!Number.isInteger(minutes) || (minutes as number) <= 0)) {
+    throw new Error(`${where}: tonight's minutes_total ${String(minutes)} is not a positive whole number`)
+  }
+  return {
+    id: body.id,
+    name: body.name,
+    photo_id: photoId(where, body.photo),
+    origin: oneOf(where, 'origin', ORIGINS, body.origin),
+    minutes_total: minutes as number | null,
+  }
+}
+
+// parseShoppingList checks the shoppingList of a GET /api/v1/home body. The
+// list, ready or not, must carry the API's label for its week, which must be
+// the label weekStart has, since the status row shows dates from weekStart.
+function parseShoppingList(where: string, list: unknown): ShoppingListStatus {
+  if (!isRecord(list) || typeof list.weekStart !== 'string' || typeof list.ready !== 'boolean') {
+    throw new Error(`${where}: shoppingList is not a week's Supply run status`)
+  }
+  const week = weekLabel(list.weekStart)
+  if (typeof list.label !== 'string' || list.label === '') {
+    throw new Error(`${where}: the ${list.ready ? 'ready' : 'unready'} shoppingList has no label`)
+  }
+  if (list.label !== `${week.week} · ${week.dates}`) {
+    throw new Error(`${where}: shoppingList label "${list.label}" is not the week of ${list.weekStart}`)
+  }
+  return { weekStart: list.weekStart, dates: week.dates.replace(' – ', '–'), ready: list.ready }
+}
+
+// parseHome checks a GET /api/v1/home body.
+export function parseHome(where: string, body: unknown): Home {
+  if (!isRecord(body) || typeof body.dateLabel !== 'string') throw new Error(`${where}: response is not the home`)
+  if (typeof body.timezone !== 'string' || !isZone(body.timezone)) {
+    throw new Error(`${where}: timezone ${JSON.stringify(body.timezone)} is not an IANA zone`)
+  }
+  if (!Number.isInteger(body.sideQuestCount) || (body.sideQuestCount as number) < 0) {
+    throw new Error(`${where}: sideQuestCount is not a count`)
+  }
+  const updates = body.recentUpdates
+  if (!isRecord(updates) || typeof updates.unread !== 'boolean') throw new Error(`${where}: recentUpdates has no unread flag`)
+  return {
+    dateLabel: body.dateLabel,
+    timezone: body.timezone,
+    tonight: parseTonight(where, body.tonight),
+    sideQuestCount: body.sideQuestCount as number,
+    shoppingList: parseShoppingList(where, body.shoppingList),
+    unread: updates.unread,
+  }
+}
+
+// isZone says whether zone is an IANA zone this browser knows.
+function isZone(zone: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: zone })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// useHome is the Home screen's summary (GET /api/v1/home). Home is read
+// again at the household's next local midnight, counted from each read, so
+// a Home left open does not keep yesterday's date and dinner.
+export function useHome() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  const home = useQuery({
+    queryKey: HOME_KEY,
+    queryFn: async () => parseHome(`GET ${HOME_PATH}`, await apiFetch<unknown>(HOME_PATH)),
+  })
+  const zone = home.data?.timezone
+  const readAt = home.dataUpdatedAt
+  useEffect(() => {
+    if (zone === undefined) return
+    const timer = setTimeout(
+      () => void queryClient.invalidateQueries({ queryKey: HOME_KEY }),
+      untilLocalMidnight(zone, new Date()),
+    )
+    return () => clearTimeout(timer)
+  }, [queryClient, zone, readAt])
+  return home
+}
+
+export const UPDATE_TYPES = ['plan_ready', 'list_ready', 'day_of_reminder', 'new_suggestions', 'rotation_review'] as const
+export type UpdateType = (typeof UPDATE_TYPES)[number]
+
+// Update is one of the Recent updates: a notification event, whatever
+// channels it went to. url is the same-origin path it opens; created_at is
+// when it was stored, the UTC RFC 3339 instant POST /api/v1/updates/seen
+// takes back.
+export type Update = { type: UpdateType; title: string; body: string; url: string; created_at: string }
+
+// parseUpdate checks one update. Its url must stay on origin once parsed, as
+// the server only ever stores a path on the app's own origin; url is that
+// path as parsed.
+function parseUpdate(where: string, body: unknown, origin: string): Update {
+  if (
+    !isRecord(body) ||
+    typeof body.title !== 'string' ||
+    typeof body.body !== 'string' ||
+    typeof body.url !== 'string' ||
+    typeof body.created_at !== 'string'
+  ) {
+    throw new Error(`${where}: an update is not a notification event`)
+  }
+  const url = appPath(body.url, origin)
+  if (url === null) throw new Error(`${where}: update url ${JSON.stringify(body.url)} is not a path on this app`)
+  if (Number.isNaN(Date.parse(body.created_at))) {
+    throw new Error(`${where}: update created_at "${body.created_at}" is not a time`)
+  }
+  return {
+    type: oneOf(where, 'type', UPDATE_TYPES, body.type),
+    title: body.title,
+    body: body.body,
+    url,
+    created_at: body.created_at,
+  }
+}
+
+// parseUpdates checks a GET /api/v1/updates body, from the app at origin:
+// the updates, newest first.
+export function parseUpdates(where: string, body: unknown, origin: string): Update[] {
+  if (!isRecord(body) || !Array.isArray(body.updates)) throw new Error(`${where}: response is not the updates`)
+  return body.updates.map((update) => parseUpdate(where, update, origin))
+}
+
+// useUpdates is the Recent updates (GET /api/v1/updates): the last ten
+// notification events, newest first. Each opening of the sheet reads it
+// afresh (refetchOnMount 'always'), whatever the query client still holds;
+// the sheet shows, and marks seen, only the list that opening read. Closing
+// the sheet aborts a read still in flight, so a reopen sends its own rather
+// than adopt one sent before it.
+export function useUpdates() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: UPDATES_KEY,
+    queryFn: async ({ signal }) =>
+      parseUpdates(`GET ${UPDATES_PATH}`, await apiFetch<unknown>(UPDATES_PATH, { signal }), window.location.origin),
+    refetchOnMount: 'always',
+  })
+}
+
+const MARK_SEEN_KEY = ['updates', 'seen'] as const
+
+// useMarkUpdatesSeen records that the household has seen its updates
+// through the created_at of the newest one shown (POST
+// /api/v1/updates/seen). The bell's unread dot clears at once, and a Home
+// read in flight is stopped so it cannot bring it back; if the server
+// refuses, the dot is put back as it was before the first of the marks in
+// flight. Once the last mark in flight settles Home is read again, so the
+// dot shows only for an event stored since.
+export function useMarkUpdatesSeen() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  // alone says whether this is the only mark in flight; each counts itself
+  // until it has settled.
+  const alone = () => queryClient.isMutating({ mutationKey: MARK_SEEN_KEY }) === 1
+  return useMutation({
+    mutationKey: MARK_SEEN_KEY,
+    mutationFn: async (through: string) => {
+      await apiFetch<unknown>(UPDATES_SEEN_PATH, { method: 'POST', body: { through } })
+    },
+    onMutate: async () => {
+      // A mark sent while another is in flight would snapshot that one's
+      // optimistic answer, so only the first snapshots.
+      const unread = alone() ? queryClient.getQueryData<Home>(HOME_KEY)?.unread : undefined
+      await queryClient.cancelQueries({ queryKey: HOME_KEY })
+      queryClient.setQueryData<Home>(HOME_KEY, (home) => home && { ...home, unread: false })
+      return { unread }
+    },
+    onError: (_error, _through, context) => {
+      if (context?.unread === undefined || !alone()) return
+      const { unread } = context
+      queryClient.setQueryData<Home>(HOME_KEY, (home) => home && { ...home, unread })
+    },
+    onSettled: () => {
+      if (alone()) void queryClient.invalidateQueries({ queryKey: HOME_KEY })
+    },
+  })
+}

web/src/home/rotation.ts

@@ -0,0 +1,107 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useEffect } from 'react'
+import { useApi } from '../api/index.ts'
+import { isRecord } from '../api/errors.ts'
+import { photoId } from '../dinners/api.ts'
+import { isNotificationOpened } from '../push/notification.ts'
+
+export const ROTATION_REVIEWS_PATH = '/api/v1/rotation-reviews'
+export const ROTATION_REVIEWS_KEY = ['rotation-reviews'] as const
+const DINNERS_KEY = ['dinners'] as const
+
+// rotationReviewPath is where the household answers "Keep it in rotation?"
+// for a tried dinner.
+export function rotationReviewPath(dinnerId: string): string {
+  return `/api/v1/dinners/${encodeURIComponent(dinnerId)}/rotation-review`
+}
+
+// Rotation check answers: keep makes the tried dinner a Regular, drop ("Not
+// for us") archives it so it is never suggested again, and not_made ("We
+// didn't make it") returns it to the Quest log. Keep is the only way a tried
+// dinner becomes a Regular; nothing decides one automatically.
+export const DECISIONS = ['keep', 'drop', 'not_made'] as const
+export type Decision = (typeof DECISIONS)[number]
+
+// RotationReview is a pending Rotation check: the dinner tried, photo_id its
+// stored photo's id, and the household-local plan date, YYYY-MM-DD, it was
+// planned on.
+export type RotationReview = { dinner: { id: string; name: string; photo_id: string | undefined }; plan_date: string }
+
+function parseReview(where: string, body: unknown): RotationReview {
+  if (!isRecord(body) || typeof body.plan_date !== 'string') throw new Error(`${where}: a review is not a Rotation check`)
+  const dinner = body.dinner
+  if (!isRecord(dinner) || typeof dinner.id !== 'string' || typeof dinner.name !== 'string') {
+    throw new Error(`${where}: a Rotation check has no dinner`)
+  }
+  return { dinner: { id: dinner.id, name: dinner.name, photo_id: photoId(where, dinner.photo) }, plan_date: body.plan_date }
+}
+
+// parseRotationReviews checks a GET /api/v1/rotation-reviews body: the
+// pending Rotation checks, oldest plan date first.
+export function parseRotationReviews(where: string, body: unknown): RotationReview[] {
+  if (!isRecord(body) || !Array.isArray(body.reviews)) throw new Error(`${where}: response is not the Rotation checks`)
+  return body.reviews.map((review) => parseReview(where, review))
+}
+
+// useRotationReviews is the pending Rotation checks (GET
+// /api/v1/rotation-reviews), oldest plan date first. Each mount of Home
+// reads them afresh, and so does a notification tap that focuses Home
+// already open (the service worker's NotificationOpened), so Home opened
+// from a rotation_review notification shows the check it is about.
+export function useRotationReviews() {
+  const { apiFetch } = useApi()
+  const query = useQuery({
+    queryKey: ROTATION_REVIEWS_KEY,
+    queryFn: async () =>
+      parseRotationReviews(`GET ${ROTATION_REVIEWS_PATH}`, await apiFetch<unknown>(ROTATION_REVIEWS_PATH)),
+    refetchOnMount: 'always',
+  })
+  const { refetch } = query
+  useEffect(() => {
+    // Without a service worker there are no notifications to tap.
+    if (!('serviceWorker' in navigator)) return
+    const container = navigator.serviceWorker
+    const onMessage = (event: MessageEvent<unknown>) => {
+      if (isNotificationOpened(event.data)) void refetch()
+    }
+    container.addEventListener('message', onMessage)
+    return () => container.removeEventListener('message', onMessage)
+  }, [refetch])
+  return query
+}
+
+// useDecideRotationReview answers "Keep it in rotation?" for a pending
+// Rotation check (POST /api/v1/dinners/{id}/rotation-review). The answer
+// must be that dinner, decided that way.
+//
+// Home leaves the check out while its answer is pending (the mutation's
+// variables say which), so the next one shows at once; a read in flight is
+// stopped so it cannot bring the check back meanwhile. Once saved, the check
+// leaves the cached list; once failed, it is shown again as the list has it.
+// Either way the Rotation checks and the dinners lists (the Regulars and the
+// Quest log the answer moved it to) are read again.
+export function useDecideRotationReview() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation<void, Error, { review: RotationReview; decision: Decision }>({
+    mutationFn: async ({ review, decision }) => {
+      const path = rotationReviewPath(review.dinner.id)
+      const body = await apiFetch<unknown>(path, { method: 'POST', body: { decision } })
+      if (!isRecord(body) || !isRecord(body.dinner) || body.dinner.id !== review.dinner.id || body.decision !== decision) {
+        throw new Error(`POST ${path}: response is not the Rotation check decided ${decision}`)
+      }
+    },
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: ROTATION_REVIEWS_KEY })
+    },
+    onSuccess: (_data, { review }) => {
+      queryClient.setQueryData<RotationReview[]>(ROTATION_REVIEWS_KEY, (reviews) =>
+        reviews?.filter((r) => r.dinner.id !== review.dinner.id),
+      )
+    },
+    onSettled: () => {
+      void queryClient.invalidateQueries({ queryKey: ROTATION_REVIEWS_KEY })
+      void queryClient.invalidateQueries({ queryKey: DINNERS_KEY })
+    },
+  })
+}

web/src/ideas/CookFromPantryPage.test.tsx

@@ -33,7 +33,9 @@ function idea(name: string, summary: string, minutes: number | null = 30) {
 
 // The ideas of mock 1i.
 const CURRY = idea('Coconut chicken curry', 'Uses all 5 · missing: 1 lime')
-const BOWLS = idea('Garlic spinach rice bowls', 'Uses 4 of 5 · nothing missing', 25)
+// BOWLS's source is withheld, as the server sends one whose link could
+// carry a secret: the card shows all the same.
+const BOWLS = { ...idea('Garlic spinach rice bowls', 'Uses 4 of 5 · nothing missing', 25), source_url: null, site_name: null }
 const ONE_PAN = idea('One-pan chicken & rice', 'Uses 3 of 5 · missing: onion')
 
 type JobBody = { status: string; result: unknown; error: string | null }

web/src/ideas/QuickDinnersPage.test.tsx

@@ -30,7 +30,9 @@ function idea(name: string, method: string, minutes: number | null, difficulty:
 
 // The ideas of mock 1j, and more for later pages and the Crock pot tab.
 const ORZO = idea('Lemon garlic shrimp orzo', 'stovetop', 25, 'medium')
-const QUESADILLAS = idea('Chicken quesadillas', 'stovetop', 20, 'easy')
+// QUESADILLAS's source is withheld, as the server sends one whose link
+// could carry a secret: the card shows all the same.
+const QUESADILLAS = { ...idea('Chicken quesadillas', 'stovetop', 20, 'easy'), source_url: null, site_name: null }
 const BROCCOLI = idea('Beef & broccoli', 'stovetop', 30, 'easy')
 const GNOCCHI = idea('Pesto gnocchi & peas', 'stovetop', 15, 'easy')
 const CHILI = idea('Crock pot chili', 'crockpot', 360, 'easy')