Revalidate the draft pool on save, refuse duplicate swaps, refresh the Quest log after a draft

Feature 14 integration fix (Maestro 857e4c33-e250-46ec-b5ea-7dd4f3b719d9).

- F14-01: storeDraft re-reads the draft pool (ListDraftPool, the same
  eligibility rule draft_week was given) inside the save transaction. A
  day whose dinner was archived, moved to tried, or planned on another
  current or later week while draft_week ran fails the job with the new
  retryable reason pool_changed and stores nothing.
- F14-02: Swap refuses a dinner already on another day of the week inside
  the write transaction; the API answers 409 dinner_already_planned.
- F14-03: a finished draft invalidates the Quest log query, as the swap
  path does, so the tablet strip and desktop panel drop dinners it planned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cmd/server/main.go

@@ -23,10 +23,12 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"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/plan"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
 	"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/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
 )
 
@@ -106,6 +108,15 @@ func run(cfg config.Config, logger *slog.Logger) error {
 	if err != nil {
 		return err
 	}
+	suggestSvc, err := suggest.NewService(db, grounder, sideQuests(ai, guard), runner, logger)
+	if err != nil {
+		return err
+	}
+
+	planSvc, err := plan.NewService(db, weekDrafter(ai, guard), runner, logger)
+	if err != nil {
+		return err
+	}
 
 	sessions, err := auth.NewSessionManager(db, cfg.SessionIdle, cfg.SessionMax)
 	if err != nil {
@@ -123,7 +134,7 @@ func run(cfg config.Config, logger *slog.Logger) error {
 		return err
 	}
 
-	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, search, ai, dinnerSvc, runner, photos, frontend.Assets())
+	router, err := server.NewRouter(logger, version, cfg.TrustedProxy, authFlow, sessions, settings, search, ai, dinnerSvc, suggestSvc, planSvc, runner, photos, frontend.Assets())
 	if err != nil {
 		return err
 	}
@@ -247,7 +258,9 @@ func newJobRunner(db *store.Store, logger *slog.Logger) (*jobs.Runner, *jobKinds
 
 // registerJobKinds registers the framework's job kinds on runner. A feature
 // service registers its own kinds when it is built, before the runner
-// starts (dinners.NewService registers dinners.KindGroundDinner).
+// starts (dinners.NewService registers dinners.KindGroundDinner and
+// suggest.NewService suggest.KindSuggestionBatch, plan.NewService
+// plan.KindDraftWeek).
 func registerJobKinds(runner *jobs.Runner) (*jobKinds, error) {
 	builtins, err := jobs.RegisterBuiltins(runner)
 	if err != nil {
@@ -268,6 +281,30 @@ func normalizer(ai *aisettings.Service, guard *harness.Guard) recipes.Normalizer
 	}
 }
 
+// sideQuests runs suggest_side_quests with the AI settings current at each
+// run, sharing guard.
+func sideQuests(ai *aisettings.Service, guard *harness.Guard) suggest.Suggester {
+	return func(ctx context.Context, scope string, in skills.SideQuestsRequest) (skills.SideQuests, error) {
+		cfg, err := ai.HarnessConfig(ctx, guard)
+		if err != nil {
+			return skills.SideQuests{}, err
+		}
+		return skills.SuggestSideQuests(ctx, cfg, scope, in)
+	}
+}
+
+// weekDrafter runs draft_week with the AI settings current at each run,
+// sharing guard.
+func weekDrafter(ai *aisettings.Service, guard *harness.Guard) plan.Drafter {
+	return func(ctx context.Context, scope string, in skills.WeekRequest) (skills.Week, error) {
+		cfg, err := ai.HarnessConfig(ctx, guard)
+		if err != nil {
+			return skills.Week{}, err
+		}
+		return skills.DraftWeek(ctx, cfg, scope, in)
+	}
+}
+
 // logListening logs the startup line. Only the public URL's origin is logged
 // so no credential-bearing URL component can reach the log.
 func logListening(logger *slog.Logger, cfg config.Config) {

docs/ARCHITECTURE.md

@@ -96,12 +96,12 @@ Columns ending in `_ct` hold AES-256-GCM ciphertext (via `secretbox`).
 | `recipe_ingredients` | recipe_id, position, raw_text, name, qty, unit, note. |
 | `recipe_steps` | recipe_id, position, text. |
 | `photos` | source_url, local_path, width, height, sha256, fetched_at. |
-| `dinners` | The meal record and its lifecycle: name, normalized_name, status (`suggested` / `quest_log` / `tried` / `regular` / `archived`), origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, recipe_url (a pasted recipe link awaiting grounding), photo_id, grounding_status (`pending` / `grounded` / `failed` / `manual`), grounding_error (why grounding failed), grounding_revision (raised when a pending dinner is renamed, so only the latest `ground_dinner` job may write it), updated_by. |
+| `dinners` | The meal record and its lifecycle: name, normalized_name, status (`suggested` / `quest_log` / `tried` / `regular` / `archived`), origin, method, minutes_total, difficulty, cuisine, is_favorite, recipe_id, recipe_url (a pasted recipe link awaiting grounding), photo_id, grounding_status (`pending` / `grounded` / `failed` / `manual`), grounding_error (why grounding failed), grounding_revision (raised whenever a dinner is renamed, so only the latest `ground_dinner` job may write it and no candidate offered before the rename grounds it), updated_by. |
 | `suggestion_batches` | trigger, status, ai_run_id. |
-| `suggestions` | dinner_id, batch_id, reason, cited_regular_ids (JSON), status, decided_at. |
-| `week_plans` | week_start (unique), status (`draft` / `synced` / `changed`), ai_note, ai_run_id, calendar_synced_at. |
+| `suggestions` | dinner_id, batch_id, name (the name the dish was suggested under, kept whatever its dinner is later renamed, so a Pass stays an immutable record every later batch dedupes against), reason, cited_regular_ids (JSON), status, decided_at. |
+| `week_plans` | week_start (unique), status (`draft` / `synced` / `changed`), ai_note, ai_run_id, calendar_synced_at, revision (raised by every swap and stored draft). |
 | `plan_days` | plan_id, date (unique per plan), dinner_id, is_new, calendar_event_id. |
-| `rotation_reviews` | dinner_id + plan_date (unique), status, decision (`keep` / `drop` / `not_made`), decided_at, updated_by. |
+| `rotation_reviews` | dinner_id + plan_date (unique), status, decision (`keep` / `drop` / `not_made`), name (set only by a drop: the dinner's name when dropped, kept whatever it is later renamed, so a drop stays among the passed names), decided_at, updated_by. |
 | `shopping_lists` | week_start (unique), plan_id, title, status (`current` / `archived`), sent_to_chat_at, frozen_at. |
 | `shopping_groups` / `shopping_items` | One group per dinner/day; item name, qty, needed (bool), position. |
 | `ai_settings` | One row: provider, base_url, model, temperature, system_prompt, api_key_ct, api_key_last4, key_verified_at. |
@@ -127,7 +127,7 @@ suggested (deck) ──Try it──▶ quest_log ──planned date passes──
     │                            └──────── explicit decision ─────┤
     │                                                             ├──▶ regular
     │                                                             └──▶ archived
-    └──Pass──▶ archived (name kept for dedupe)
+    └──Pass──▶ archived (suggested name kept for dedupe)
 ```
 
 From `tried`, an explicit decision moves the dinner to `regular`, to
@@ -194,7 +194,9 @@ automatic** (D-021).
   `GET /api/v1/dinners?status=regular|quest_log` returns
   `{dinners: [...]}` ordered by normalized name, each with `photo_url`
   (`/media/photos/{photo_id}-400.jpg`, or null) and `grounding_status`;
-  any other status is 400. `PATCH /api/v1/dinners/{id}` edits `name`
+  any other status is 400. The Quest log (`quest_log`) is the dinners
+  accepted and not yet scheduled: one on the plan for the household's
+  current week (by its timezone) or a later week is left out. `PATCH /api/v1/dinners/{id}` edits `name`
   (deduplicated against the other unarchived dinners), `method`
   (`stovetop` / `oven` / `crockpot` / `grill` / `other`), `minutes_total`
   (1–1440) and `difficulty` (`easy` / `medium` / `hard`); invalid values
@@ -209,13 +211,15 @@ automatic** (D-021).
   and `grounding_job_id` null. The job grounds the dinner's
   `recipe_url` directly with `GroundURL`, else its name with `Ground`
   (see Recipe grounding), and sets grounding_status `grounded` with the
-  recipe's recipe_id, photo_id, method, minutes_total and difficulty, or
+  recipe's recipe_id, photo_id, method, minutes_total and difficulty,
+  clearing the pasted `recipe_url` (the recipe replaces it), or
   `failed` with `grounding_error` — also the job's failure code — one of
   `no_recipe_found`, `recipe_unusable` (the pasted link), `search_not_configured`,
   `search_failed`, `ai_failed`, `interrupted` (the server stopped) or
   `grounding_error`. Each job carries the dinner's `grounding_revision`
-  from when it was enqueued; renaming a `pending` dinner clears its
-  `recipe_url`, raises the revision and enqueues a job for the new name.
+  from when it was enqueued; renaming a dinner raises the revision, and
+  renaming a `pending` one enqueues a job for the new name, clearing its
+  `recipe_url` when the normalized name changes.
   A job for a dinner archived, no longer `pending` or at another revision
   does no work, and a job only writes a dinner still unarchived, `pending`
   and at its revision, so a fix-up made meanwhile wins and an earlier job
@@ -233,10 +237,19 @@ automatic** (D-021).
   searches for the dinner's name and returns `{candidates: [{candidate_id,
   title, site_name, photo_url, minutes}]}`, at most 3, ranked as `Ground`
   ranks them; it fetches pages but downloads no photo and runs no model,
-  so `photo_url` is set only for a page already stored, and `candidate_id`
-  is the page's URL. `POST /api/v1/dinners/{id}/ground` takes exactly one
-  of `{candidate_id}`, `{recipe_url}` (both grounded with `GroundURL`,
-  setting `grounded`) or `{manual: {ingredients[], steps[], minutes,
+  so `photo_url` is set only for a page already stored. `candidate_id` is
+  an opaque id the server resolves to the page it last offered that dinner
+  (kept in memory, so a restart means fetching the candidates again) at
+  the `grounding_revision` it was searched at, so a candidate offered
+  before any rename is refused even if the name is changed back; the
+  page's URL, which may carry a token, is never returned or cached. An
+  unknown dinner is 404, recipe search not set up 409 `not_configured` and
+  a search failure 502 `search_failed`; any other failure, such as a
+  stored recipe that cannot be read, is 500, logged with a fixed reason
+  and the dinner id only — never a candidate's URL or dependency error
+  text.
+  `POST /api/v1/dinners/{id}/ground` takes exactly one of `{candidate_id}`,
+  `{recipe_url}` (both grounded with `GroundURL`, setting `grounded`) or `{manual: {ingredients[], steps[], minutes,
   method}}` (1–100 ingredient lines, up to 100 steps, each non-blank and at
   most 500 characters; minutes 1–1440). A manual recipe is stored as typed
   — no model runs — as a `recipes` row whose source_url is
@@ -260,6 +273,125 @@ automatic** (D-021).
   dinner, is 500, logged with a fixed reason and the dinner id only —
   never the link, which can carry a personal token, or dependency error
   text.
+- Side quest suggestions (`suggest.Service`). `POST
+  /api/v1/suggestions/batches` creates a `manual` batch and enqueues its
+  `suggestion_batch` job, answering 202 `{batch_id, job_id, trigger,
+  status}` without waiting; while a batch is `pending` or `running` it
+  answers 202 with that batch instead, so at most one runs at a time (the
+  check, the batch and its job share one write transaction). The job reads the
+  household context, the deck's names and every declined name, runs
+  `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`,
+  `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
+  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
+  not retried, and the next start fails the job as interrupted. Recording
+  the batch's end is bounded the same way (one attempt, 5 seconds, made
+  even during shutdown), so a busy writer cannot hold a stopping worker;
+  a batch whose end timed out is left `running` with its job. Each time a
+  batch is started, before the active batch is selected, every batch
+  still `pending` or `running` with no job queued or running (the process
+  stopped, or recording its end failed) is set `failed`, so it does not
+  block the next.
+  `GET /api/v1/suggestions/deck` returns `{suggestions: [{id, dinner_id,
+  name, photo_url, difficulty, method, minutes_total, cuisine, reason,
+  cited_regular_ids, status, dinner_status, decided_at, created_at}],
+  active_batch, failed_batch}`: the `pending` suggestions whose dinner is
+  still `suggested`, oldest first; the batch `pending` or `running`
+  (`{batch_id, job_id, trigger, status}`, or null); and the newest batch
+  when it `failed` (same shape, or null; a later batch, done or under
+  way, supersedes the failure), read in one snapshot, so a client that
+  did not start the batch can follow its job and learns of a failure it
+  was not following. At most one of the two is set. `POST /api/v1/suggestions/{id}/accept` (Try it) sets the
+  suggestion `accepted` and moves its dinner to `quest_log`; `POST
+  /api/v1/suggestions/{id}/decline` (Pass) sets it `declined` and archives
+  the dinner; every later batch, and the household context's passed list,
+  reads the suggestion's own name as declined, so renaming the archived
+  dinner changes nothing. Both record
+  the session's subject as the dinner's `updated_by` and answer 200
+  `{suggestion, replenish_job_id}`. Repeating a decision changes nothing
+  and answers 200; the opposite decision is 409 `suggestion_decided`, a
+  suggestion whose dinner left the deck some other way 409
+  `dinner_not_suggested`, and an unknown id 404. A decision that leaves
+  fewer than 5 in the deck starts a `replenish` batch, or joins the batch
+  already pending or running, and returns that batch's job id either way
+  (`replenish_job_id` is null when the deck keeps 5 or more). The batch and its job are written in
+  the decision's own transaction, so a decision is never recorded without
+  the replenish it calls for; when they cannot be written, neither is the
+  decision, and a retry decides again.
+- Weekly plans (`plan.Service`). `{weekStart}` is a household-local Monday
+  (`YYYY-MM-DD`); any other value is 400 `invalid_week`. `GET
+  /api/v1/plans/{weekStart}` returns `{id, week_start, week_label, status,
+  ai_note, calendar_synced_at, updated_at, days}`, or 404 when the week has
+  no plan; `days` are the seven days Monday first, each `{date, dinner: {id,
+  name, photo, minutes, method, origin}, is_new, start_by}`. `is_new` means
+  the dinner was planned from the Quest log; `start_by` is the household's
+  dinner time on that date minus `minutes_total`, computed on read, for a
+  crock-pot dinner with known minutes, else null. `POST
+  /api/v1/plans/{weekStart}/draft` takes `{confirm?}` and answers 202
+  `{jobId}` for a `draft_week` job, or for the one already queued or
+  running for the week, so a week has at most one draft in flight. A
+  confirmed draft while the week's job was asked for without confirm is
+  409 `draft_running` and enqueues nothing. The job runs the `draft_week` skill on every Regular
+  and every Quest log dinner no other plan for the current or a later week
+  has, with the household context and last week's dinners, and stores the
+  week: a new plan is `draft`; a redraft keeps each day's
+  `calendar_event_id`, and a `synced` or `changed` plan becomes `changed`.
+  Drafting over a `synced` or `changed` plan needs `{"confirm": true}`, else
+  409 `confirm_required`; a plan synced while an unconfirmed draft runs is
+  left as it is and the job fails `confirm_required`. The job reads the
+  plan's revision before draft_week runs; if the plan was edited (a swap,
+  or another draft stored) by the time the draft is stored, the plan is
+  left as it is and the job fails `plan_changed`. The pool is read again
+  in the same transaction that stores the draft; if a dinner the draft
+  planned has left it meanwhile (archived, `tried`, or a Quest log dinner
+  stored on another current or later week's plan, as by a draft of
+  another week), nothing is stored and the job fails `pool_changed`,
+  which drafting again resolves. A pool under seven
+  dinners fails the job `not_enough_dinners`, draft_week failing
+  `ai_failed`. `PUT /api/v1/plans/{weekStart}/days/{date}` takes
+  `{dinner_id}`, a Regular or Quest log dinner, swaps the day, recomputes
+  `is_new`, moves a `synced` plan to `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). `MarkTried(date)`, which the
+  `rotation_check` schedule calls for the household-local day just past,
+  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
+  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
+  the dinner a Regular, `drop` ("Not for us") archives it and `not_made`
+  ("We didn't make it") returns it to the Quest log; its origin is kept.
+  The check is closed with `decided_at` and the session's `updated_by`,
+  and the answer is `{dinner, plan_date, decision, dinner_status,
+  decided_at, updated_by}`. Any other decision is 400 `invalid_decision`,
+  an unknown dinner or a dinner never checked 404 `not_found`, a dinner
+  whose checks are all decided (including a second decision) 409
+  `no_pending_review`, and one no longer tried 409 `dinner_not_tried`.
+  Keep is the only path from tried to Regular. A drop records the
+  dinner's name on the check (`rotation_reviews.name`), and that name
+  joins the passed names (`ListPassedNames`) the Side quest dedupe and
+  household context use, so it is never suggested again, even after the
+  dinner is renamed.
 - `/health` — liveness.
 - Everything else serves the embedded PWA with SPA fallback.
 
@@ -322,6 +454,18 @@ automatic** (D-021).
   dinner when the token-set (Jaccard) similarity of their words is at least
   0.85. A `Deduper` over the Regulars, Quest log, pending suggestions and
   passed names rejects a suggestion that repeats any of them.
+- **Side quest suggestions** (`skills.SuggestSideQuests`, skill
+  `suggest_side_quests` v1): asks for twice the Side quests needed, at the
+  household temperature, with the household context plus the pending Side
+  quests. Malformed replies (bad JSON, a missing field, a bad enum, an
+  empty name) get the one repair turn. Well-formed Side quests that break a
+  rule are dropped, not repaired, and listed in `Dropped` with the rule:
+  one that repeats a Regular, Quest log dinner, pending Side quest, any
+  passed name (the whole history, not only the 60 in the context) or an
+  earlier Side quest of the batch; one citing no Regular or a name that is
+  not a Regular; and one whose reason is over 180 characters or names none
+  of its cited Regulars. Cited names are rewritten as the household writes
+  them. Grounding each survivor in a recipe is the caller's next step.
 
 ## Recipe grounding
 
@@ -517,11 +661,11 @@ Regular has a name `harness.Similar` to it — the PWA's copy of the name
 rules in `web/src/dinners/names.ts` folds letters with
 `web/src/dinners/letterFolds.json`, which `gen_folds.py` writes from the
 same table as the server's, and runs the same cases,
-`internal/ai/harness/testdata/dedupe_cases.json`, as the server's) and
+`web/src/dinners/testdata/dedupe_cases.json`, as the server's) and
 notifications (`/onboarding/notifications`: what MealQuest notifies about,
-the iOS install hint, "Turn on notifications" and "Maybe later"). Either
-button sends `PATCH /api/v1/settings/household` with
-`{"onboarding_completed": true}`; the server sets `onboarding_completed_at`
+the iOS install hint, "Turn on notifications" and "Maybe later"). "Maybe
+later", and "Turn on notifications" once notifications are enabled, send
+`PATCH /api/v1/settings/household` with `{"onboarding_completed": true}`; the server sets `onboarding_completed_at`
 to the time of that update (keeping the first time if it is already set;
 the field itself is read-only and `false` is refused) and the app goes Home.
 Completing needs at least three Regulars (`household.MinRegulars`); with
@@ -530,8 +674,10 @@ fewer the server answers 400 `invalid_settings` naming
 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. Offline on the saved pages the
-settings cannot be read (the service worker never caches `/api/v1/settings`),
+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
+saved pages the settings cannot be read (the service worker never caches `/api/v1/settings`),
 so the saved pages open as they are.
 
 Regular dinners (`/settings/regulars`) lists the Regulars from

internal/ai/harness/context.go

@@ -15,8 +15,8 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
 )
 
-// PassedLimit is how many of the most recently passed Side quests the
-// household context holds.
+// PassedLimit is how many of the most recently passed names (Side quests
+// passed and dinners a Rotation check dropped) the household context holds.
 const PassedLimit = 60
 
 // PlanWeeks is how many ISO weeks of plans, ending with the current week,
@@ -34,8 +34,8 @@ type HouseholdContext struct {
 	Regulars []RegularDinner
 	// QuestLog holds the Quest log dinner names, in name order.
 	QuestLog []string
-	// Passed holds the names of the most recently passed Side quests,
-	// oldest first.
+	// Passed holds the most recently passed names, oldest first: Side
+	// quests passed and dinners a Rotation check dropped ("Not for us").
 	Passed []string
 	// Plans are the planned dinners of the last PlanWeeks weeks, oldest
 	// first.
@@ -137,7 +137,7 @@ func readContext(ctx context.Context, st *store.Store, now time.Time) (h Househo
 		h.QuestLog = append(h.QuestLog, d.Name)
 	}
 
-	passed, err := q.ListRecentDeclinedNames(ctx, PassedLimit)
+	passed, err := q.ListRecentPassedNames(ctx, PassedLimit)
 	if err != nil {
 		return h, fmt.Errorf("read passed Side quests: %w", err)
 	}

internal/ai/harness/context_test.go

@@ -82,9 +82,9 @@ func (s *seeder) pass(name, decidedAt string) {
 	batch := s.id("batch")
 	s.exec(`INSERT INTO suggestion_batches (id, trigger, status, created_at, updated_at)
 		VALUES (?, 'manual', 'done', ?, ?)`, batch, decidedAt, decidedAt)
-	s.exec(`INSERT INTO suggestions (id, dinner_id, batch_id, reason, cited_regular_ids, status,
-		decided_at, created_at, updated_at) VALUES (?, ?, ?, 'why', '[]', 'declined', ?, ?, ?)`,
-		s.id("suggestion"), s.dinner(name, "archived", "", "", 0, false), batch, decidedAt, decidedAt, decidedAt)
+	s.exec(`INSERT INTO suggestions (id, dinner_id, batch_id, name, reason, cited_regular_ids, status,
+		decided_at, created_at, updated_at) VALUES (?, ?, ?, ?, 'why', '[]', 'declined', ?, ?, ?)`,
+		s.id("suggestion"), s.dinner(name, "archived", "", "", 0, false), batch, name, decidedAt, decidedAt, decidedAt)
 }
 
 // plan inserts the week plan starting weekStart with one dinner per date;

internal/ai/harness/dedupe_test.go

@@ -8,11 +8,11 @@ import (
 	"unicode/utf8"
 )
 
-// TestSharedDedupeCases runs testdata/dedupe_cases.json, which the PWA's
-// copy of Normalize and Similar (web/src/dinners/names.ts) runs too, so the
-// two cannot drift apart on these names.
+// TestSharedDedupeCases runs web/src/dinners/testdata/dedupe_cases.json,
+// which the PWA's copy of Normalize and Similar (web/src/dinners/names.ts)
+// runs too, so the two cannot drift apart on these names.
 func TestSharedDedupeCases(t *testing.T) {
-	raw, err := os.ReadFile("testdata/dedupe_cases.json")
+	raw, err := os.ReadFile("../../../web/src/dinners/testdata/dedupe_cases.json")
 	if err != nil {
 		t.Fatal(err)
 	}

internal/ai/skills/draft_week.go

@@ -0,0 +1,328 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+	// Aliased: the package tests name a fixture household.
+	hh "code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/household"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// NoteLimit is the most characters a drafted week's note may have.
+const NoteLimit = 160
+
+// WeekLength is how many dinners a drafted week holds, one a day from
+// Monday to Sunday.
+const WeekLength = 7
+
+// Candidate kinds: a Regular or a Quest log dinner.
+const (
+	KindRegular  = "regular"
+	KindQuestLog = "quest_log"
+)
+
+// WeekRequest is what draft_week reads.
+type WeekRequest struct {
+	// Context is the household context (see harness.BuildContext).
+	Context harness.HouseholdContext
+	// WeekStart is the Monday of the week to draft, household-local.
+	WeekStart store.LocalDate
+	// Pool holds the dinners the week may be drafted from. It must hold at
+	// least WeekLength dinners, each once.
+	Pool []Candidate
+	// LastWeek holds the IDs of the dinners planned in the week before
+	// WeekStart. They need not be in Pool.
+	LastWeek []string
+	// DinnerTime is the household's dinner time, "HH:MM", from which a
+	// crock-pot dinner's StartBy is computed.
+	DinnerTime string
+}
+
+// Candidate is one dinner of the pool.
+type Candidate struct {
+	ID   string
+	Name string
+	// Kind is KindRegular or KindQuestLog.
+	Kind string
+	// Method is one of stovetop, oven, crockpot, grill and other, or ""
+	// when unknown.
+	Method string
+	// Minutes from prep to table, or 0 when unknown.
+	Minutes int
+}
+
+// NotEnoughDinnersError is a pool too small to fill a week. DraftWeek
+// returns it before any LLM call.
+type NotEnoughDinnersError struct {
+	// Pool is how many dinners the pool holds.
+	Pool int
+}
+
+func (e *NotEnoughDinnersError) Error() string {
+	return fmt.Sprintf("not enough dinners: the pool holds %d, a week needs %d", e.Pool, WeekLength)
+}
+
+// Week is draft_week's output.
+type Week struct {
+	// Days are the week's dinners, Monday to Sunday.
+	Days []WeekDay `json:"days"`
+	// Note is a short word on the week, at most NoteLimit characters. It
+	// may be empty.
+	Note string `json:"note"`
+	// Warnings say what the draft did that the rules discourage but allow,
+	// such as repeating last week's dinners. It is never part of the
+	// model's reply.
+	Warnings []string `json:"-"`
+}
+
+// WeekDay is one day's dinner.
+type WeekDay struct {
+	// Date is the household-local date, YYYY-MM-DD.
+	Date string `json:"date"`
+	// DinnerID is the ID of a dinner of the pool.
+	DinnerID string `json:"dinner_id"`
+	// IsNew is true for a Quest log dinner. It is computed from the pool,
+	// never part of the model's reply.
+	IsNew bool `json:"-"`
+	// StartBy is when a crock-pot dinner must start to be ready at the
+	// household's dinner time; it is zero for any other dinner and for a
+	// crock-pot dinner whose minutes are unknown. It is computed, never
+	// part of the model's reply.
+	StartBy time.Time `json:"-"`
+}
+
+// DraftWeek runs draft_week v1 on in and returns a week of seven dinners
+// from the pool, one a day from Monday to Sunday, none twice. A pool of
+// fewer than WeekLength dinners fails with *NotEnoughDinnersError before
+// any LLM call, and any other invalid request fails before it too. scope
+// names the week (see harness.Run).
+func DraftWeek(ctx context.Context, cfg harness.Config, scope string, in WeekRequest) (Week, error) {
+	s, err := newDraftWeek(in)
+	if err != nil {
+		return Week{}, err
+	}
+	return harness.Run(ctx, cfg, s, scope, in)
+}
+
+// draftWeek is the skill. It holds its input, the week's dates and the
+// pool by ID because validation and post-processing compare the output
+// with them.
+type draftWeek struct {
+	in    WeekRequest
+	dates [WeekLength]store.LocalDate
+	pool  map[string]Candidate
+	zone  *time.Location
+}
+
+var _ harness.Skill[WeekRequest, Week] = draftWeek{}
+
+// newDraftWeek checks in and returns the skill for it.
+func newDraftWeek(in WeekRequest) (draftWeek, error) {
+	pool := map[string]Candidate{}
+	for i, c := range in.Pool {
+		if err := c.check(); err != nil {
+			return draftWeek{}, fmt.Errorf("draft_week: pool dinner %d: %w", i+1, err)
+		}
+		if _, dup := pool[c.ID]; dup {
+			return draftWeek{}, fmt.Errorf("draft_week: pool dinner %d: id %q is in the pool twice", i+1, c.ID)
+		}
+		pool[c.ID] = c
+	}
+	if len(pool) < WeekLength {
+		return draftWeek{}, &NotEnoughDinnersError{Pool: len(pool)}
+	}
+	dates, err := hh.WeekDays(in.WeekStart)
+	if err != nil {
+		return draftWeek{}, fmt.Errorf("draft_week: %w", err)
+	}
+	zone, err := hh.LoadZone(in.Context.Timezone)
+	if err != nil {
+		return draftWeek{}, fmt.Errorf("draft_week: %w", err)
+	}
+	// The dinner time is checked here so a bad one fails before the LLM
+	// call rather than in PostProcess.
+	if _, err := hh.LocalTime(zone, in.WeekStart, in.DinnerTime); err != nil {
+		return draftWeek{}, fmt.Errorf("draft_week: dinner time: %w", err)
+	}
+	return draftWeek{in: in, dates: dates, pool: pool, zone: zone}, nil
+}
+
+// check reports a candidate the pool cannot hold.
+func (c Candidate) check() error {
+	switch {
+	case strings.TrimSpace(c.ID) == "" || strings.ContainsAny(c.ID, "\r\n"):
+		return fmt.Errorf("id %q is empty or has a line break", c.ID)
+	case strings.TrimSpace(c.Name) == "":
+		return fmt.Errorf("%s has an empty name", c.ID)
+	case c.Kind != KindRegular && c.Kind != KindQuestLog:
+		return fmt.Errorf("%s kind %q is not %s or %s", c.ID, c.Kind, KindRegular, KindQuestLog)
+	case c.Method != "" && !slices.Contains(methods, c.Method):
+		return fmt.Errorf("%s method %q is not one of %s", c.ID, c.Method, strings.Join(methods, ", "))
+	case c.Minutes < 0:
+		return fmt.Errorf("%s minutes %d is negative", c.ID, c.Minutes)
+	}
+	return nil
+}
+
+func (draftWeek) Name() string { return "draft_week" }
+
+func (draftWeek) Version() int { return 1 }
+
+func (draftWeek) Timeout() time.Duration { return harness.DefaultTimeout }
+
+// weekPrompt is the template data of draft_week.v1.tmpl.
+type weekPrompt struct {
+	// Days are the week's dates, Monday to Sunday, e.g. "Mon 2026-10-12".
+	Days []string
+}
+
+func (s draftWeek) PromptInput(in WeekRequest) (harness.PromptInput, error) {
+	var days []string
+	for _, d := range s.dates {
+		y, m, day := d.Date()
+		days = append(days, time.Date(y, m, day, 0, 0, 0, 0, time.UTC).Format("Mon")+" "+d.String())
+	}
+	var pool []string
+	for _, c := range in.Pool {
+		pool = append(pool, c.line(slices.Contains(in.LastWeek, c.ID)))
+	}
+	sections := append(in.Context.Sections(), harness.ContextSection{Title: "Candidate pool", Lines: pool})
+	return harness.PromptInput{Data: weekPrompt{Days: days}, Context: sections}, nil
+}
+
+// line renders c as `id "ID": Name (Regular, method, N min, planned last
+// week)`, leaving out what is unknown.
+func (c Candidate) line(lastWeek bool) string {
+	attrs := []string{"Regular"}
+	if c.Kind == KindQuestLog {
+		attrs = []string{"Quest log"}
+	}
+	if c.Method != "" {
+		attrs = append(attrs, c.Method)
+	}
+	if c.Minutes > 0 {
+		attrs = append(attrs, fmt.Sprintf("%d min", c.Minutes))
+	}
+	if lastWeek {
+		attrs = append(attrs, "planned last week")
+	}
+	return fmt.Sprintf("id %q: %s (%s)", c.ID, oneLine(c.Name), strings.Join(attrs, ", "))
+}
+
+func (draftWeek) Schema() llm.JSONSchema {
+	return llm.JSONSchema{Name: "draft_week", Schema: json.RawMessage(`{
+		"type": "object",
+		"properties": {
+			"days": {
+				"type": "array",
+				"items": {
+					"type": "object",
+					"properties": {
+						"date": {"type": "string"},
+						"dinner_id": {"type": "string"}
+					},
+					"required": ["date", "dinner_id"],
+					"additionalProperties": false
+				}
+			},
+			"note": {"type": "string"}
+		},
+		"required": ["days", "note"],
+		"additionalProperties": false
+	}`)}
+}
+
+// UnmarshalJSON decodes a day, requiring each of its fields as the schema
+// does.
+func (d *WeekDay) UnmarshalJSON(data []byte) error {
+	if err := requireFields(data, nil, "date", "dinner_id"); err != nil {
+		return fmt.Errorf("day %s", err)
+	}
+	type plain WeekDay
+	return json.Unmarshal(data, (*plain)(d))
+}
+
+// UnmarshalJSON decodes the output, requiring each of its fields as the
+// schema does.
+func (w *Week) UnmarshalJSON(data []byte) error {
+	if err := requireFields(data, nil, "days", "note"); err != nil {
+		return fmt.Errorf("output %s", err)
+	}
+	type plain Week
+	return json.Unmarshal(data, (*plain)(w))
+}
+
+// Validate finds every broken rule: a week that is not exactly the seven
+// dates Monday to Sunday in order, a dinner not in the pool or planned
+// twice, or a note over NoteLimit characters.
+func (s draftWeek) Validate(out Week) []string {
+	var problems []string
+	if n := len(out.Days); n != WeekLength {
+		problems = append(problems, fmt.Sprintf("days has %d entries; give exactly %d, one for each date from %s to %s",
+			n, WeekLength, s.dates[0], s.dates[WeekLength-1]))
+	}
+	first := map[string]int{} // dinner ID -> first day planning it
+	for i, d := range out.Days {
+		if i < WeekLength && d.Date != s.dates[i].String() {
+			problems = append(problems, fmt.Sprintf("day %d date %q is not %s; give the dates %s to %s in order",
+				i+1, d.Date, s.dates[i], s.dates[0], s.dates[WeekLength-1]))
+		}
+		c, ok := s.pool[d.DinnerID]
+		if !ok {
+			problems = append(problems, fmt.Sprintf("day %d dinner_id %q is not in the candidate pool; use only ids from it", i+1, d.DinnerID))
+			continue
+		}
+		if j, dup := first[d.DinnerID]; dup {
+			problems = append(problems, fmt.Sprintf("day %d dinner_id %q (%s) is also on day %d; plan each dinner at most once",
+				i+1, d.DinnerID, oneLine(c.Name), j+1))
+			continue
+		}
+		first[d.DinnerID] = i
+	}
+	if n := utf8.RuneCountInString(out.Note); n > NoteLimit {
+		problems = append(problems, fmt.Sprintf("note has %d characters; keep it to at most %d", n, NoteLimit))
+	}
+	return problems
+}
+
+// PostProcess tidies the note, marks each Quest log dinner new, computes
+// each crock-pot dinner's StartBy, and warns when the week repeats more of
+// last week's dinners than the pool made necessary.
+func (s draftWeek) PostProcess(out Week) (Week, error) {
+	result := Week{Note: oneLine(out.Note)}
+	var repeats []string
+	for i, d := range out.Days {
+		c := s.pool[d.DinnerID]
+		day := WeekDay{Date: d.Date, DinnerID: d.DinnerID, IsNew: c.Kind == KindQuestLog}
+		if c.Method == "crockpot" && c.Minutes > 0 {
+			dinner, err := hh.LocalTime(s.zone, s.dates[i], s.in.DinnerTime)
+			if err != nil {
+				return Week{}, err
+			}
+			day.StartBy = dinner.Add(-time.Duration(c.Minutes) * time.Minute)
+		}
+		if slices.Contains(s.in.LastWeek, d.DinnerID) {
+			repeats = append(repeats, oneLine(c.Name))
+		}
+		result.Days = append(result.Days, day)
+	}
+	fresh := 0
+	for id := range s.pool {
+		if !slices.Contains(s.in.LastWeek, id) {
+			fresh++
+		}
+	}
+	if allowed := max(0, WeekLength-fresh); len(repeats) > allowed {
+		result.Warnings = append(result.Warnings, fmt.Sprintf("repeats %d of last week's dinners (%s) though the pool needed at most %d",
+			len(repeats), strings.Join(repeats, ", "), allowed))
+	}
+	return result, nil
+}

internal/ai/skills/draft_week_test.go

@@ -0,0 +1,324 @@
+package skills
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+)
+
+// weekOf asks for the week of Monday 2026-10-12 from a pool of eight, two
+// of them planned last week.
+var weekOf = WeekRequest{
+	Context: harness.HouseholdContext{
+		Today:    date(2026, 10, 8),
+		Timezone: "America/New_York",
+		Regulars: []harness.RegularDinner{
+			{Name: "Beef Chili", Cuisine: "Tex-Mex", Method: "crockpot", Minutes: 240},
+			{Name: "Chicken Fajitas", Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30, Favorite: true},
+		},
+		QuestLog: []string{"Pad Thai"},
+		Passed:   []string{},
+		Plans: []harness.PlannedDinner{
+			{Date: date(2026, 10, 5), Name: "Chicken Fajitas"},
+			{Date: date(2026, 10, 6), Name: "Fish Tacos"},
+		},
+	},
+	WeekStart: date(2026, 10, 12),
+	Pool: []Candidate{
+		{ID: "chili", Name: "Beef Chili", Kind: KindRegular, Method: "crockpot", Minutes: 240},
+		{ID: "fajitas", Name: "Chicken Fajitas", Kind: KindRegular, Method: "stovetop", Minutes: 30},
+		{ID: "bolognese", Name: "Spaghetti Bolognese", Kind: KindRegular, Method: "stovetop", Minutes: 45},
+		{ID: "salmon", Name: "Sheet Pan Salmon", Kind: KindRegular, Method: "oven"},
+		{ID: "tacos", Name: "Fish Tacos", Kind: KindRegular, Minutes: 25},
+		{ID: "padthai", Name: "Pad Thai", Kind: KindQuestLog, Method: "stovetop", Minutes: 35},
+		{ID: "roast", Name: "Pot Roast", Kind: KindRegular, Method: "crockpot"},
+		{ID: "shawarma", Name: "Chicken Shawarma Bowls", Kind: KindQuestLog, Method: "oven", Minutes: 40},
+	},
+	LastWeek:   []string{"fajitas", "tacos", "gone"},
+	DinnerTime: "17:30",
+}
+
+// weekDates are the dates of weekOf, Monday to Sunday.
+var weekDates = []string{"2026-10-12", "2026-10-13", "2026-10-14", "2026-10-15", "2026-10-16", "2026-10-17", "2026-10-18"}
+
+// week renders a reply planning ids on dates, in order.
+func week(note string, dates []string, ids ...string) string {
+	var days []string
+	for i, id := range ids {
+		days = append(days, fmt.Sprintf(`{"date":%q,"dinner_id":%q}`, dates[i], id))
+	}
+	return fmt.Sprintf(`{"days":[%s],"note":%q}`, strings.Join(days, ","), note)
+}
+
+// clean plans no dinner of last week.
+var clean = []string{"chili", "padthai", "bolognese", "salmon", "shawarma", "roast", "fajitas"}
+
+// wantWeek is the output for a reply planning ids on weekDates with note.
+func wantWeek(note string, ids ...string) Week {
+	newYork, err := time.LoadLocation("America/New_York")
+	if err != nil {
+		panic(err)
+	}
+	out := Week{Note: note}
+	for i, id := range ids {
+		day := WeekDay{Date: weekDates[i], DinnerID: id, IsNew: id == "padthai" || id == "shawarma"}
+		if id == "chili" {
+			y, m, d := date(2026, 10, 12+i).Date()
+			day.StartBy = time.Date(y, m, d, 13, 30, 0, 0, newYork)
+		}
+		out.Days = append(out.Days, day)
+	}
+	return out
+}
+
+// draft runs DraftWeek on in with f and checks f was called exactly calls
+// times, each at the household temperature with the draft_week schema.
+func draft(t *testing.T, f *llm.Fake, in WeekRequest, calls int) (Week, []llm.Request, error) {
+	t.Helper()
+	out, err := DraftWeek(context.Background(), testConfig(t, f), "2026-W42", in)
+	reqs := f.Requests()
+	if len(reqs) != calls {
+		t.Fatalf("Generate called %d times, want %d", len(reqs), calls)
+	}
+	if g, _, _ := f.Remaining(); g != 0 {
+		t.Fatalf("%d scripted Generate results unused", g)
+	}
+	for i, req := range reqs {
+		if req.Temperature == nil || *req.Temperature != 0.7 {
+			t.Fatalf("request %d temperature = %v, want 0.7", i+1, req.Temperature)
+		}
+		if req.Schema == nil || req.Schema.Name != "draft_week" {
+			t.Fatalf("request %d schema = %v, want draft_week", i+1, req.Schema)
+		}
+	}
+	return out, reqs, err
+}
+
+func assertWeek(t *testing.T, got, want Week) {
+	t.Helper()
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("output = %+v\nwant     %+v", got, want)
+	}
+}
+
+func TestDraftWeekValid(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(week("  A cosy week,\nwith Pad Thai midweek. ", weekDates, clean...)))
+	out, reqs, err := draft(t, &f, weekOf, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertWeek(t, out, wantWeek("A cosy week, with Pad Thai midweek.", clean...))
+	if !out.Days[0].StartBy.Equal(time.Date(2026, 10, 12, 17, 30, 0, 0, time.UTC)) {
+		t.Errorf("Beef Chili StartBy = %v, want 13:30 EDT", out.Days[0].StartBy)
+	}
+
+	system, user := reqs[0].System, reqs[0].Messages[0].Content
+	golden(t, "draft_week_valid.system.golden", system)
+	golden(t, "draft_week_valid.user.golden", user)
+	for _, part := range []string{
+		"## Household context",
+		"### Candidate pool",
+		`- id "chili": Beef Chili (Regular, crockpot, 240 min)`,
+		`- id "fajitas": Chicken Fajitas (Regular, stovetop, 30 min, planned last week)`,
+		`- id "salmon": Sheet Pan Salmon (Regular, oven)`,
+		`- id "tacos": Fish Tacos (Regular, 25 min, planned last week)`,
+		`- id "padthai": Pad Thai (Quest log, stovetop, 35 min)`,
+		"## Output contract",
+		`"dinner_id"`,
+	} {
+		if !strings.Contains(system, part) {
+			t.Errorf("system prompt lacks %q", part)
+		}
+	}
+	if strings.Index(system, "### Candidate pool") > strings.Index(system, "## Output contract") {
+		t.Error("the output contract is not after the candidate pool")
+	}
+	want := "Draft the week of Mon 2026-10-12, Tue 2026-10-13, Wed 2026-10-14, Thu 2026-10-15, Fri 2026-10-16, Sat 2026-10-17, Sun 2026-10-18."
+	if user != want {
+		t.Errorf("user message = %q, want %q", user, want)
+	}
+}
+
+// repaired checks a first reply is repaired once, quoting it and the
+// problems wanted.
+func repaired(t *testing.T, first string, want ...string) {
+	t.Helper()
+	var f llm.Fake
+	f.QueueGenerate(reply(first), reply(week("Fixed.", weekDates, clean...)))
+	out, reqs, err := draft(t, &f, weekOf, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertWeek(t, out, wantWeek("Fixed.", clean...))
+	repair := reqs[1].Messages
+	if len(repair) != 3 || repair[1].Content != first {
+		t.Fatalf("repair turn does not quote the first reply: %+v", repair)
+	}
+	for _, w := range want {
+		if !strings.Contains(repair[2].Content, w) {
+			t.Fatalf("repair message = %q, want it to contain %q", repair[2].Content, w)
+		}
+	}
+}
+
+func TestDraftWeekUnknownIDRepaired(t *testing.T) {
+	ids := slices.Clone(clean)
+	ids[2] = "lasagna"
+	repaired(t, week("A week.", weekDates, ids...),
+		`day 3 dinner_id "lasagna" is not in the candidate pool; use only ids from it`)
+}
+
+func TestDraftWeekDuplicateRepaired(t *testing.T) {
+	ids := slices.Clone(clean)
+	ids[5] = "chili"
+	repaired(t, week("A week.", weekDates, ids...),
+		`day 6 dinner_id "chili" (Beef Chili) is also on day 1; plan each dinner at most once`)
+}
+
+func TestDraftWeekWrongDatesTwiceFails(t *testing.T) {
+	sundayFirst := append([]string{"2026-10-11"}, weekDates[:6]...)
+	var f llm.Fake
+	f.QueueGenerate(reply(week("A week.", sundayFirst, clean...)), reply(week("A week.", sundayFirst, clean...)))
+	out, _, err := draft(t, &f, weekOf, 2)
+	var bad *harness.BadOutputError
+	if !errors.As(err, &bad) || !errors.Is(err, llm.ErrBadOutput) {
+		t.Fatalf("err = %v, want a BadOutputError", err)
+	}
+	if !slices.Contains(bad.Repair, `day 1 date "2026-10-11" is not 2026-10-12; give the dates 2026-10-12 to 2026-10-18 in order`) {
+		t.Fatalf("repair problems = %q", bad.Repair)
+	}
+	if out.Days != nil {
+		t.Fatalf("output = %+v, want none", out)
+	}
+}
+
+func TestDraftWeekNotEnoughDinners(t *testing.T) {
+	small := weekOf
+	small.Pool = slices.Clone(weekOf.Pool[:6])
+	var f llm.Fake
+	_, _, err := draft(t, &f, small, 0)
+	var short *NotEnoughDinnersError
+	if !errors.As(err, &short) || short.Pool != 6 {
+		t.Fatalf("err = %v, want a NotEnoughDinnersError for a pool of 6", err)
+	}
+	if err.Error() != "not enough dinners: the pool holds 6, a week needs 7" {
+		t.Fatalf("err = %q", err)
+	}
+}
+
+func TestDraftWeekLastWeekRepeats(t *testing.T) {
+	// The pool has six dinners not planned last week, so the week needs one
+	// of last week's two and may plan it without a warning.
+	one := []string{"chili", "padthai", "bolognese", "salmon", "shawarma", "roast", "fajitas"}
+	both := []string{"chili", "padthai", "bolognese", "tacos", "shawarma", "roast", "fajitas"}
+	for name, tc := range map[string]struct {
+		ids  []string
+		warn []string
+	}{
+		"needed repeat":  {one, nil},
+		"avoidable both": {both, []string{"repeats 2 of last week's dinners (Fish Tacos, Chicken Fajitas) though the pool needed at most 1"}},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var f llm.Fake
+			f.QueueGenerate(reply(week("A week.", weekDates, tc.ids...)))
+			out, _, err := draft(t, &f, weekOf, 1)
+			if err != nil {
+				t.Fatal(err)
+			}
+			want := wantWeek("A week.", tc.ids...)
+			want.Warnings = tc.warn
+			assertWeek(t, out, want)
+		})
+	}
+}
+
+func TestWeekValidate(t *testing.T) {
+	s, err := newDraftWeek(weekOf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	reply := func(note string, ids ...string) Week {
+		var w Week
+		if err := w.UnmarshalJSON([]byte(week(note, weekDates, ids...))); err != nil {
+			t.Fatal(err)
+		}
+		return w
+	}
+	if p := s.Validate(reply(strings.Repeat("é", NoteLimit), clean...)); len(p) != 0 {
+		t.Fatalf("valid output has problems: %q", p)
+	}
+	for name, tc := range map[string]struct {
+		out  Week
+		want []string
+	}{
+		"empty": {Week{}, []string{"days has 0 entries; give exactly 7, one for each date from 2026-10-12 to 2026-10-18"}},
+		"six days": {reply("", clean[:6]...), []string{
+			"days has 6 entries; give exactly 7, one for each date from 2026-10-12 to 2026-10-18",
+		}},
+		"eight days": {
+			Week{Days: append(reply("", clean...).Days, WeekDay{Date: "2026-10-19", DinnerID: "tacos"})},
+			[]string{"days has 8 entries; give exactly 7, one for each date from 2026-10-12 to 2026-10-18"},
+		},
+		"long note": {reply(strings.Repeat("a", NoteLimit+1), clean...), []string{"note has 161 characters; keep it to at most 160"}},
+		"dates out of order": {
+			Week{Days: []WeekDay{
+				{weekDates[1], "chili", false, time.Time{}}, {weekDates[0], "padthai", false, time.Time{}},
+				{weekDates[2], "bolognese", false, time.Time{}}, {weekDates[3], "salmon", false, time.Time{}},
+				{weekDates[4], "shawarma", false, time.Time{}}, {weekDates[5], "roast", false, time.Time{}},
+				{weekDates[6], "fajitas", false, time.Time{}},
+			}},
+			[]string{
+				`day 1 date "2026-10-13" is not 2026-10-12; give the dates 2026-10-12 to 2026-10-18 in order`,
+				`day 2 date "2026-10-12" is not 2026-10-13; give the dates 2026-10-12 to 2026-10-18 in order`,
+			},
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if got := s.Validate(tc.out); !slices.Equal(got, tc.want) {
+				t.Fatalf("problems =\n%s\nwant\n%s", strings.Join(got, "\n"), strings.Join(tc.want, "\n"))
+			}
+		})
+	}
+}
+
+func TestDraftWeekRequestRejected(t *testing.T) {
+	with := func(change func(*WeekRequest)) WeekRequest {
+		in := weekOf
+		in.Pool = slices.Clone(weekOf.Pool)
+		change(&in)
+		return in
+	}
+	for name, tc := range map[string]struct {
+		in   WeekRequest
+		want string
+	}{
+		"not a Monday": {with(func(in *WeekRequest) { in.WeekStart = date(2026, 10, 13) }),
+			"draft_week: household: week start 2026-10-13 is a Tuesday, want Monday"},
+		"bad kind": {with(func(in *WeekRequest) { in.Pool[0].Kind = "suggestion" }),
+			`draft_week: pool dinner 1: chili kind "suggestion" is not regular or quest_log`},
+		"bad method": {with(func(in *WeekRequest) { in.Pool[1].Method = "air fryer" }),
+			`draft_week: pool dinner 2: fajitas method "air fryer" is not one of stovetop, oven, crockpot, grill, other`},
+		"empty id": {with(func(in *WeekRequest) { in.Pool[2].ID = " " }),
+			`draft_week: pool dinner 3: id " " is empty or has a line break`},
+		"id twice": {with(func(in *WeekRequest) { in.Pool[3].ID = "chili" }),
+			`draft_week: pool dinner 4: id "chili" is in the pool twice`},
+		"bad dinner time": {with(func(in *WeekRequest) { in.DinnerTime = "5:30pm" }),
+			`draft_week: dinner time: household: invalid time "5:30pm": want HH:MM`},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var f llm.Fake
+			if _, _, err := draft(t, &f, tc.in, 0); err == nil || err.Error() != tc.want {
+				t.Fatalf("err = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}

internal/ai/skills/prompts/checksums.txt

@@ -3,3 +3,5 @@
 # version, rename its template to match and add a line for the new version.
 echo v1 ab5d7884f5c7a2261c06b0c9353bb9597070c001420bd4cbb6ec6272c093fdce
 normalize_recipe v1 7174e5479fc020f3b2b39953d85411381aea26defb9943145e7864c5b752d7ee
+suggest_side_quests v1 bd54d7bf9aea0980059a346e5f40ff4c866b80ef9bb9f74e7cbd413be0911c8a
+draft_week v1 e637419690d9532bab53cb8ca01b73a079ecfe8e3022522c05188d18e9740f32

internal/ai/skills/prompts/draft_week.v1.tmpl

@@ -0,0 +1,21 @@
+{{/* draft_week drafts the household's weekly plan: one dinner a day, Monday to Sunday, from a candidate pool. */}}
+{{define "instructions" -}}
+You draft the household's dinner plan for one week, Monday to Sunday: one dinner for each day, chosen from the candidate pool in the household context.
+
+Rules:
+- Give exactly 7 days, one for each date of the week, in order from Monday to Sunday, each date written as YYYY-MM-DD.
+- Use only dinners from the candidate pool, each by its id exactly as the pool writes it.
+- Plan each dinner at most once in the week.
+- Avoid the dinners marked "planned last week" whenever the pool has enough others.
+- Mix the week: vary cuisines and methods, put quick dinners (a crockpot or 30 minutes or less) on weeknights, and include a Quest log dinner when the pool has one.
+
+Give:
+- days: the 7 days, each with date and dinner_id.
+- note: one sentence of at most 160 characters about the week.
+
+One valid day, for a pool with a dinner whose id is "d1" (an example only, not about this household):
+{"date": "2026-01-05", "dinner_id": "d1"}
+{{- end}}
+{{define "user" -}}
+Draft the week of {{range $i, $d := .Days}}{{if $i}}, {{end}}{{$d}}{{end}}.
+{{- end}}

internal/ai/skills/prompts/suggest_side_quests.v1.tmpl

@@ -0,0 +1,22 @@
+{{/* suggest_side_quests drafts Side quests: new dinners for the household to try, each based on its Regulars. */}}
+{{define "instructions" -}}
+You suggest Side quests: new dinners for the household to try, based on the dinners it already makes.
+
+Every Side quest must be a dinner the household has not had: never one of its Regulars, its Quest log, its pending Side quests or the dinners it has passed, and never one of those under another name. Base every Side quest on one or more of the household's Regulars, such as a familiar protein in a new cuisine or familiar flavours cooked a new way. Prefer the favorite Regulars, and vary the cuisines across the batch.
+
+Give for each Side quest:
+- name: the dinner's usual name, as a recipe site would title it.
+- cuisine: its cuisine, e.g. "Thai" or "Tex-Mex".
+- method: how it is mainly cooked: "stovetop", "oven", "crockpot" (slow cooker or crock pot), "grill" or "other".
+- est_minutes: your estimate of the whole minutes from starting prep to the table.
+- difficulty: "easy", "medium" or "hard" for a home cook.
+- reason: one sentence of at most 180 characters saying why the household would like it. It must name at least one of the Regulars in cited_regulars.
+- cited_regulars: the Regulars the reason relies on, at least one, each written exactly as its name appears in the Regulars list of the household context, without the details in parentheses. Cite only Regulars from that list.
+- search_query: a web search query that finds a recipe for this dinner.
+
+One valid Side quest, for a household with a Regular named "Chicken Fajitas" (an example only, not about this household):
+{"name": "Chicken Shawarma Bowls", "cuisine": "Middle Eastern", "method": "oven", "est_minutes": 40, "difficulty": "easy", "reason": "Spiced roast chicken and crisp toppings, like your Chicken Fajitas with a Middle Eastern twist.", "cited_regulars": ["Chicken Fajitas"], "search_query": "chicken shawarma bowls recipe"}
+{{- end}}
+{{define "user" -}}
+Suggest {{.Count}} Side quests.
+{{- end}}

internal/ai/skills/suggest_side_quests.go

@@ -0,0 +1,421 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/harness"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
+)
+
+// ReasonLimit is the most characters a Side quest's reason, its "Why
+// this?", may have.
+const ReasonLimit = 180
+
+// SideQuestsRequest is what suggest_side_quests reads.
+type SideQuestsRequest struct {
+	// Context is the household context (see harness.BuildContext). It must
+	// hold at least one Regular, since every Side quest cites one.
+	Context harness.HouseholdContext
+	// Needed is how many Side quests the caller wants to keep. The skill
+	// asks the model for twice as many, since validation and grounding
+	// drop some. It must be positive.
+	Needed int
+	// Pending holds the names of the Side quests not yet tried or passed.
+	Pending []string
+	// Declined holds every passed name — each passed Side quest and each
+	// dinner a Rotation check dropped — not only the recent ones Context
+	// holds.
+	Declined []string
+}
+
+// SideQuest is one suggested new dinner. Method, EstMinutes and Difficulty
+// are the model's estimates until the dinner is grounded in a recipe.
+type SideQuest struct {
+	Name    string `json:"name"`
+	Cuisine string `json:"cuisine"`
+	// Method is one of stovetop, oven, crockpot, grill and other.
+	Method     string `json:"method"`
+	EstMinutes int    `json:"est_minutes"`
+	// Difficulty is easy, medium or hard.
+	Difficulty string `json:"difficulty"`
+	// Reason is the "Why this?": at most ReasonLimit characters, naming at
+	// least one of CitedRegulars.
+	Reason string `json:"reason"`
+	// CitedRegulars are names of the household's Regulars, as the
+	// household writes them.
+	CitedRegulars []string `json:"cited_regulars"`
+	// SearchQuery is a web search query that finds a recipe for the dinner.
+	SearchQuery string `json:"search_query"`
+}
+
+// SideQuests is suggest_side_quests' output.
+type SideQuests struct {
+	// Suggestions are the Side quests that passed every rule, in the
+	// model's order. There may be more or fewer than Needed.
+	Suggestions []SideQuest `json:"suggestions"`
+	// Dropped are the Side quests the model gave that broke a rule, in the
+	// model's order. It is never part of the model's reply.
+	Dropped []DroppedSideQuest `json:"-"`
+}
+
+// DroppedSideQuest is a Side quest dropped by PostProcess.
+type DroppedSideQuest struct {
+	Name string
+	// Why says which rule it broke.
+	Why string
+}
+
+// SuggestSideQuests runs suggest_side_quests v1 on in and returns the Side
+// quests that cite only real Regulars, give a short reason naming one of
+// them, and repeat no Regular, Quest log dinner, pending or passed Side
+// quest, nor each other. The rest are in Dropped. scope names the batch
+// (see harness.Run).
+func SuggestSideQuests(ctx context.Context, cfg harness.Config, scope string, in SideQuestsRequest) (SideQuests, error) {
+	return harness.Run(ctx, cfg, suggestSideQuests{in: in}, scope, in)
+}
+
+// suggestSideQuests is the skill. It holds its input because validation
+// and post-processing compare the output with it.
+type suggestSideQuests struct {
+	in SideQuestsRequest
+}
+
+var _ harness.Skill[SideQuestsRequest, SideQuests] = suggestSideQuests{}
+
+func (suggestSideQuests) Name() string { return "suggest_side_quests" }
+
+func (suggestSideQuests) Version() int { return 1 }
+
+func (suggestSideQuests) Timeout() time.Duration { return harness.DefaultTimeout }
+
+// sideQuestsPrompt is the template data of suggest_side_quests.v1.tmpl.
+type sideQuestsPrompt struct {
+	// Count is how many Side quests to ask for.
+	Count int
+}
+
+// requested is how many Side quests the model is asked for.
+func (s suggestSideQuests) requested() int { return 2 * s.in.Needed }
+
+func (suggestSideQuests) PromptInput(in SideQuestsRequest) (harness.PromptInput, error) {
+	if in.Needed <= 0 {
+		return harness.PromptInput{}, fmt.Errorf("%d Side quests needed; the number must be positive", in.Needed)
+	}
+	if len(in.Context.Regulars) == 0 {
+		return harness.PromptInput{}, errors.New("household has no Regulars for Side quests to be based on")
+	}
+	sections := append(in.Context.Sections(), harness.ContextSection{Title: "Pending Side quests", Lines: in.Pending})
+	return harness.PromptInput{Data: sideQuestsPrompt{Count: suggestSideQuests{in: in}.requested()}, Context: sections}, nil
+}
+
+func (suggestSideQuests) Schema() llm.JSONSchema {
+	return llm.JSONSchema{Name: "suggest_side_quests", Schema: json.RawMessage(`{
+		"type": "object",
+		"properties": {
+			"suggestions": {
+				"type": "array",
+				"items": {
+					"type": "object",
+					"properties": {
+						"name": {"type": "string"},
+						"cuisine": {"type": "string"},
+						"method": {"type": "string", "enum": ["stovetop", "oven", "crockpot", "grill", "other"]},
+						"est_minutes": {"type": "integer"},
+						"difficulty": {"type": "string", "enum": ["easy", "medium", "hard"]},
+						"reason": {"type": "string"},
+						"cited_regulars": {"type": "array", "items": {"type": "string"}},
+						"search_query": {"type": "string"}
+					},
+					"required": ["name", "cuisine", "method", "est_minutes", "difficulty", "reason", "cited_regulars", "search_query"],
+					"additionalProperties": false
+				}
+			}
+		},
+		"required": ["suggestions"],
+		"additionalProperties": false
+	}`)}
+}
+
+// UnmarshalJSON decodes a Side quest, requiring each of its fields as the
+// schema does: encoding/json would otherwise read a missing or null one as
+// empty.
+func (q *SideQuest) UnmarshalJSON(data []byte) error {
+	if err := requireFields(data, nil, "name", "cuisine", "method", "est_minutes", "difficulty", "reason", "cited_regulars", "search_query"); err != nil {
+		return fmt.Errorf("suggestion %s", err)
+	}
+	type plain SideQuest
+	return json.Unmarshal(data, (*plain)(q))
+}
+
+// UnmarshalJSON decodes the output, requiring its one field as the schema
+// does.
+func (out *SideQuests) UnmarshalJSON(data []byte) error {
+	if err := requireFields(data, nil, "suggestions"); err != nil {
+		return fmt.Errorf("output %s", err)
+	}
+	type plain SideQuests
+	return json.Unmarshal(data, (*plain)(out))
+}
+
+// Validate finds what makes the reply unusable as a whole: a wrong number
+// of Side quests or one that is malformed. A well-formed Side quest that
+// breaks a rule is dropped by PostProcess instead.
+func (s suggestSideQuests) Validate(out SideQuests) []string {
+	var problems []string
+	switch n := len(out.Suggestions); {
+	case n == 0 && len(out.Dropped) == 0:
+		problems = append(problems, fmt.Sprintf("suggestions is empty; give %d Side quests", s.requested()))
+	case n > s.requested():
+		problems = append(problems, fmt.Sprintf("suggestions has %d entries; give at most %d Side quests", n, s.requested()))
+	}
+	for i, q := range out.Suggestions {
+		for _, f := range []struct{ field, value string }{
+			{"name", q.Name}, {"cuisine", q.Cuisine}, {"reason", q.Reason}, {"search_query", q.SearchQuery},
+		} {
+			if strings.TrimSpace(f.value) == "" {
+				problems = append(problems, fmt.Sprintf("suggestion %d has an empty %s; give one", i+1, f.field))
+			}
+		}
+		if strings.TrimSpace(q.Name) != "" && harness.Normalize(q.Name) == "" {
+			problems = append(problems, fmt.Sprintf("suggestion %d name %q has only filler words; name the dish", i+1, q.Name))
+		}
+		if !slices.Contains(methods, q.Method) {
+			problems = append(problems, fmt.Sprintf("suggestion %d method %q is not one of %s", i+1, q.Method, strings.Join(methods, ", ")))
+		}
+		if q.EstMinutes <= 0 {
+			problems = append(problems, fmt.Sprintf("suggestion %d est_minutes %d is not positive; give the minutes from prep to table", i+1, q.EstMinutes))
+		}
+		if !slices.Contains(difficulties, q.Difficulty) {
+			problems = append(problems, fmt.Sprintf("suggestion %d difficulty %q is not one of %s", i+1, q.Difficulty, strings.Join(difficulties, ", ")))
+		}
+	}
+	return problems
+}
+
+// PostProcess tidies every Side quest's text, writes its cited Regulars as
+// the household does, and moves each one that breaks a rule to Dropped
+// (see drop).
+func (s suggestSideQuests) PostProcess(out SideQuests) (SideQuests, error) {
+	regulars := regularNames{exact: map[string][]string{}, normalized: map[string][]string{}}
+	var names []string
+	for _, r := range s.in.Context.Regulars {
+		regulars.add(r.Name)
+		names = append(names, r.Name)
+	}
+	regulars.all = names
+	known := harness.NewDeduper(harness.DedupeSources{
+		Regulars: names,
+		QuestLog: s.in.Context.QuestLog,
+		Pending:  s.in.Pending,
+		Declined: s.in.Declined,
+	})
+	result := SideQuests{Suggestions: []SideQuest{}}
+	for _, q := range out.Suggestions {
+		q = SideQuest{
+			Name:          oneLine(q.Name),
+			Cuisine:       oneLine(q.Cuisine),
+			Method:        q.Method,
+			EstMinutes:    q.EstMinutes,
+			Difficulty:    q.Difficulty,
+			Reason:        oneLine(q.Reason),
+			CitedRegulars: q.CitedRegulars,
+			SearchQuery:   oneLine(q.SearchQuery),
+		}
+		cited, why := drop(q, regulars, known, result.Suggestions)
+		if why != "" {
+			result.Dropped = append(result.Dropped, DroppedSideQuest{Name: q.Name, Why: why})
+			continue
+		}
+		q.CitedRegulars = cited
+		result.Suggestions = append(result.Suggestions, q)
+	}
+	return result, nil
+}
+
+// regularNames finds the Regular a cited name means. Names need not be
+// unique, even ignoring case, so each key holds every Regular with it.
+type regularNames struct {
+	// exact is keyed by the name in lower case on one line.
+	exact map[string][]string
+	// normalized is keyed by harness.Normalize of the name.
+	normalized map[string][]string
+	// all holds every Regular's name, in the household's order.
+	all []string
+}
+
+func exactName(name string) string { return strings.ToLower(oneLine(name)) }
+
+func (r regularNames) add(name string) {
+	r.exact[exactName(name)] = append(r.exact[exactName(name)], name)
+	if n := harness.Normalize(name); n != "" {
+		r.normalized[n] = append(r.normalized[n], name)
+	}
+}
+
+// find returns the one Regular cited means, or "" and why there is none.
+// A Regular named exactly cited, ignoring case and spacing, comes first;
+// failing that, cited may name a Regular by its normalized name.
+func (r regularNames) find(cited string) (string, string) {
+	matches := r.exact[exactName(cited)]
+	if len(matches) == 0 {
+		matches = r.normalized[harness.Normalize(cited)]
+	}
+	switch len(matches) {
+	case 0:
+		return "", fmt.Sprintf("cites %q, which is not a Regular", cited)
+	case 1:
+		return matches[0], ""
+	default:
+		return "", fmt.Sprintf("cites %q, which could be any of the Regulars %q", cited, matches)
+	}
+}
+
+// drop returns why q must be dropped, or "" and its cited Regulars as the
+// household writes them when it may be kept. q is dropped when it repeats
+// a known dinner or a Side quest already kept, cites no Regular or one
+// regulars finds no single Regular for, or has a reason over ReasonLimit
+// characters or naming none of its cited Regulars.
+func drop(q SideQuest, regulars regularNames, known *harness.Deduper, kept []SideQuest) ([]string, string) {
+	if known.IsDuplicate(q.Name) {
+		return nil, "repeats a Regular, Quest log dinner, pending or passed Side quest"
+	}
+	for _, k := range kept {
+		if harness.Similar(q.Name, k.Name) {
+			return nil, fmt.Sprintf("repeats the Side quest %q in the same batch", k.Name)
+		}
+	}
+	if len(q.CitedRegulars) == 0 {
+		return nil, "cites no Regular"
+	}
+	var cited []string
+	for _, c := range q.CitedRegulars {
+		name, why := regulars.find(c)
+		if why != "" {
+			return nil, why
+		}
+		cited = append(cited, name)
+	}
+	if n := utf8.RuneCountInString(q.Reason); n > ReasonLimit {
+		return nil, fmt.Sprintf("reason has %d characters, over %d", n, ReasonLimit)
+	}
+	named := regulars.named(q.Reason)
+	if !slices.ContainsFunc(cited, func(name string) bool { return slices.Contains(named, name) }) {
+		return nil, "reason names none of its cited Regulars"
+	}
+	return cited, ""
+}
+
+// named returns the Regulars text names, by one rule. A mention of a
+// Regular is a place where text spells its name, ignoring case and spacing,
+// with no letter, mark or digit just outside it: the start or end of text,
+// white space, punctuation or a symbol must border it, so "Beef
+// Chili-inspired" and "Beef Chili's" mention "Beef Chili" while "Beef
+// Chilis" does not, nor does "Cafe" with a combining accent after it
+// mention "Cafe". Punctuation at either end of the name, with any spacing
+// beside it, is optional, and a mention takes in as much of it as text
+// spells, spaced in any way, with the border still holding after it: "Easy
+// Beef Chili!" is mentioned by "Easy Beef Chili." too, by "Easy Beef Chili
+// !" with its "!", and by "Easy Beef Chili!x" without its "!", and "Beef
+// Chili!!" by "Beef Chili!" with one "!". A
+// combining mark is part of its letter, never punctuation. A mention names
+// its Regular unless a mention of a different Regular covers the same text
+// or more, so "Your Easy Beef Chili." names "Easy Beef Chili" and not "Beef
+// Chili", and text that two Regulars spell alike names neither there.
+func (r regularNames) named(text string) []string {
+	type mention struct {
+		name       string
+		start, end int
+	}
+	text = exactName(text)
+	bordered := func(start, end int) bool {
+		before, _ := utf8.DecodeLastRuneInString(text[:start])
+		after, _ := utf8.DecodeRuneInString(text[end:])
+		return (start == 0 || !isWord(before)) && (end == len(text) || !isWord(after))
+	}
+	var mentions []mention
+	for _, name := range r.all {
+		full := exactName(name)
+		core := strings.TrimFunc(full, isOuter)
+		if core == "" {
+			continue
+		}
+		lead := full[:len(full)-len(strings.TrimLeftFunc(full, isOuter))]
+		trail := full[len(lead)+len(core):]
+		for at := 0; ; {
+			i := strings.Index(text[at:], core)
+			if i < 0 {
+				break
+			}
+			start, end := at+i, at+i+len(core)
+			at = start + 1
+			if !bordered(start, end) {
+				continue
+			}
+			start = spelledBefore(text, start, lead, func(s int) bool { return bordered(s, end) })
+			end = spelledAfter(text, end, trail, func(e int) bool { return bordered(start, e) })
+			mentions = append(mentions, mention{name, start, end})
+		}
+	}
+	var names []string
+	for _, m := range mentions {
+		covered := slices.ContainsFunc(mentions, func(o mention) bool {
+			return o.name != m.name && o.start <= m.start && o.end >= m.end
+		})
+		if !covered && !slices.Contains(names, m.name) {
+			names = append(names, m.name)
+		}
+	}
+	return names
+}
+
+// spelledAfter returns where the longest start of outer that text spells
+// from at ends, ignoring spacing, among those after which bordered holds,
+// or at when there are none.
+func spelledAfter(text string, at int, outer string, bordered func(int) bool) int {
+	end := at
+	for _, c := range strings.Join(strings.Fields(outer), "") {
+		at = len(text) - len(strings.TrimLeftFunc(text[at:], unicode.IsSpace))
+		if !strings.HasPrefix(text[at:], string(c)) {
+			break
+		}
+		at += utf8.RuneLen(c)
+		if bordered(at) {
+			end = at
+		}
+	}
+	return end
+}
+
+// spelledBefore returns where the longest end of outer that text spells up
+// to at starts, ignoring spacing, among those before which bordered holds,
+// or at when there are none.
+func spelledBefore(text string, at int, outer string, bordered func(int) bool) int {
+	start := at
+	punct := []rune(strings.Join(strings.Fields(outer), ""))
+	for i := len(punct) - 1; i >= 0; i-- {
+		at = len(strings.TrimRightFunc(text[:at], unicode.IsSpace))
+		if !strings.HasSuffix(text[:at], string(punct[i])) {
+			break
+		}
+		at -= utf8.RuneLen(punct[i])
+		if bordered(at) {
+			start = at
+		}
+	}
+	return start
+}
+
+// isWord reports whether c is a letter, a mark on one or a digit.
+func isWord(c rune) bool { return unicode.IsLetter(c) || unicode.IsMark(c) || unicode.IsDigit(c) }
+
+// isOuter reports whether c may be left off the end of a name: punctuation
+// or white space.
+func isOuter(c rune) bool { return unicode.IsPunct(c) || unicode.IsSpace(c) }

internal/ai/skills/suggest_side_quests_test.go

@@ -0,0 +1,488 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"reflect"
+	"slices"
+	"strings"
+	"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/store"
+)
+
+func date(y int, m time.Month, d int) store.LocalDate {
+	return store.LocalDateOf(time.Date(y, m, d, 0, 0, 0, 0, time.UTC))
+}
+
+// household asks for two Side quests, so four are requested.
+var household = SideQuestsRequest{
+	Context: harness.HouseholdContext{
+		Today:    date(2026, 10, 6),
+		Timezone: "America/New_York",
+		Regulars: []harness.RegularDinner{
+			{Name: "Beef Chili", Cuisine: "Tex-Mex", Method: "crockpot", Minutes: 240},
+			{Name: "Chicken Fajitas", Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30, Favorite: true},
+			{Name: "Spaghetti Bolognese", Cuisine: "Italian", Method: "stovetop", Minutes: 45},
+		},
+		QuestLog: []string{"Pad Thai"},
+		Passed:   []string{"Chicken Tikka Masala"},
+		Plans: []harness.PlannedDinner{
+			{Date: date(2026, 10, 5), Name: "Chicken Fajitas"},
+			{Date: date(2026, 10, 6), Name: "Beef Chili"},
+		},
+	},
+	Needed:   2,
+	Pending:  []string{"Shrimp Scampi"},
+	Declined: []string{"Chicken Tikka Masala", "Fish Tacos"},
+}
+
+// sideQuest renders one Side quest of a reply.
+func sideQuest(name, reason string, cited ...string) string {
+	c, _ := json.Marshal(append([]string{}, cited...))
+	r, _ := json.Marshal(reason)
+	return fmt.Sprintf(`{"name":%q,"cuisine":"Fusion","method":"stovetop","est_minutes":35,"difficulty":"easy","reason":%s,"cited_regulars":%s,"search_query":%q}`,
+		name, r, c, strings.ToLower(name)+" recipe")
+}
+
+// batch renders a reply holding the Side quests given.
+func batch(quests ...string) string {
+	return `{"suggestions":[` + strings.Join(quests, ",") + `]}`
+}
+
+var (
+	shawarma = sideQuest("Chicken Shawarma Bowls", "Spiced chicken and crisp toppings, like your Chicken Fajitas.", "Chicken Fajitas")
+	ragu     = sideQuest("Beef Ragu Pappardelle", "A slow beef sauce like your Spaghetti Bolognese, on wide noodles.", "Spaghetti Bolognese")
+	verde    = sideQuest("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "beef chili")
+	bulgogi  = sideQuest("Beef Bulgogi", "Sweet, quick-seared beef for fans of Chicken Fajitas and Beef Chili.", "Chicken Fajitas", "Beef Chili")
+)
+
+// want returns the Side quest that sideQuest renders, with cited as the
+// household writes them.
+func want(name, reason string, cited ...string) SideQuest {
+	return SideQuest{
+		Name: name, Cuisine: "Fusion", Method: "stovetop", EstMinutes: 35, Difficulty: "easy",
+		Reason: reason, CitedRegulars: cited, SearchQuery: strings.ToLower(name) + " recipe",
+	}
+}
+
+var (
+	wantShawarma = want("Chicken Shawarma Bowls", "Spiced chicken and crisp toppings, like your Chicken Fajitas.", "Chicken Fajitas")
+	wantRagu     = want("Beef Ragu Pappardelle", "A slow beef sauce like your Spaghetti Bolognese, on wide noodles.", "Spaghetti Bolognese")
+	wantVerde    = want("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "Beef Chili")
+	wantBulgogi  = want("Beef Bulgogi", "Sweet, quick-seared beef for fans of Chicken Fajitas and Beef Chili.", "Chicken Fajitas", "Beef Chili")
+)
+
+// suggest runs SuggestSideQuests on household with f and checks f was
+// called exactly calls times, each at the household temperature.
+func suggest(t *testing.T, f *llm.Fake, in SideQuestsRequest, calls int) (SideQuests, []llm.Request, error) {
+	t.Helper()
+	out, err := SuggestSideQuests(context.Background(), testConfig(t, f), "2026-W41", in)
+	reqs := f.Requests()
+	if len(reqs) != calls {
+		t.Fatalf("Generate called %d times, want %d", len(reqs), calls)
+	}
+	if g, _, _ := f.Remaining(); g != 0 {
+		t.Fatalf("%d scripted Generate results unused", g)
+	}
+	for i, req := range reqs {
+		if req.Temperature == nil || *req.Temperature != 0.7 {
+			t.Fatalf("request %d temperature = %v, want 0.7", i+1, req.Temperature)
+		}
+		if req.Schema == nil || req.Schema.Name != "suggest_side_quests" {
+			t.Fatalf("request %d schema = %v, want suggest_side_quests", i+1, req.Schema)
+		}
+	}
+	return out, reqs, err
+}
+
+func assertSideQuests(t *testing.T, got, want SideQuests) {
+	t.Helper()
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("output = %+v\nwant     %+v", got, want)
+	}
+}
+
+func TestSuggestSideQuestsCleanBatch(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(shawarma, ragu, verde, bulgogi)))
+	out, reqs, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu, wantVerde, wantBulgogi}})
+
+	system, user := reqs[0].System, reqs[0].Messages[0].Content
+	golden(t, "suggest_side_quests_clean.system.golden", system)
+	golden(t, "suggest_side_quests_clean.user.golden", user)
+	for _, part := range []string{
+		"## Household context",
+		"- Chicken Fajitas (Tex-Mex, stovetop, 30 min, favorite)",
+		"### Quest log\n- Pad Thai",
+		"### Passed, oldest first\n- Chicken Tikka Masala",
+		"- 2026-10-06 Tue: Beef Chili",
+		"### Pending Side quests\n- Shrimp Scampi",
+		"## Output contract",
+		`"cited_regulars"`,
+		`"search_query"`,
+	} {
+		if !strings.Contains(system, part) {
+			t.Errorf("system prompt lacks %q", part)
+		}
+	}
+	if strings.Index(system, "## Household context") > strings.Index(system, "## Output contract") {
+		t.Error("the output contract is not after the household context")
+	}
+	if user != "Suggest 4 Side quests." {
+		t.Errorf("user message = %q, want twice the 2 needed", user)
+	}
+}
+
+func TestSuggestSideQuestsPersonaFirst(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(shawarma)))
+	cfg := testConfig(t, &f)
+	cfg.Persona = "You are the household's cheerful kitchen helper."
+	if _, err := SuggestSideQuests(context.Background(), cfg, "2026-W41", household); err != nil {
+		t.Fatal(err)
+	}
+	if system := f.Requests()[0].System; !strings.HasPrefix(system, cfg.Persona+"\n\n## Instructions\n") {
+		t.Fatalf("system prompt does not start with the persona then the instructions:\n%s", system)
+	}
+}
+
+func TestSuggestSideQuestsInventedRegularDropped(t *testing.T) {
+	invented := sideQuest("Meatloaf Wellington", "Your Grandma's Meatloaf, wrapped in pastry.", "Grandma's Meatloaf")
+	partly := sideQuest("Fajita Meatballs", "Chicken Fajitas meets your Grandma's Meatloaf.", "Chicken Fajitas", "Grandma's Meatloaf")
+	none := sideQuest("Mushroom Risotto", "Creamy and comforting.")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(invented, shawarma, partly, none)))
+	out, _, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{wantShawarma},
+		Dropped: []DroppedSideQuest{
+			{Name: "Meatloaf Wellington", Why: `cites "Grandma's Meatloaf", which is not a Regular`},
+			{Name: "Fajita Meatballs", Why: `cites "Grandma's Meatloaf", which is not a Regular`},
+			{Name: "Mushroom Risotto", Why: "cites no Regular"},
+		},
+	})
+}
+
+func TestSuggestSideQuestsSharedNormalizedRegularNotRewritten(t *testing.T) {
+	in := household
+	in.Context.Regulars = append(slices.Clone(household.Context.Regulars),
+		harness.RegularDinner{Name: "Easy Beef Chili", Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30})
+	plain := sideQuest("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "beef chili")
+	easy := sideQuest("Frito Pie", "Your Easy Beef Chili over corn chips.", "EASY  beef chili")
+	either := sideQuest("Tamale Bake", "Your Beef Chili under a cornbread crust.", "Beef Chili!")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(plain, easy, either)))
+	out, _, err := suggest(t, &f, in, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{
+			want("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "Beef Chili"),
+			want("Frito Pie", "Your Easy Beef Chili over corn chips.", "Easy Beef Chili"),
+		},
+		Dropped: []DroppedSideQuest{
+			{Name: "Tamale Bake", Why: `cites "Beef Chili!", which could be any of the Regulars ["Beef Chili" "Easy Beef Chili"]`},
+		},
+	})
+}
+
+func TestSuggestSideQuestsReasonNamesResolvedRegular(t *testing.T) {
+	in := household
+	in.Context.Regulars = append(slices.Clone(household.Context.Regulars),
+		harness.RegularDinner{Name: "Easy Beef Chili", Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30})
+	other := sideQuest("Chili Verde", "Your Beef Chili gone green, with pork and tomatillos.", "Easy Beef Chili")
+	easy := sideQuest("Frito Pie", "Your Easy Beef Chili over corn chips.", "Easy Beef Chili")
+	plain := sideQuest("Chili Mac", "The Beef Chili, not the Easy Beef Chili, over macaroni.", "Beef Chili")
+	inside := sideQuest("Tamale Bake", "Your Easy Beef Chili under a cornbread crust.", "Beef Chili")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(other, easy, plain, inside)))
+	out, _, err := suggest(t, &f, in, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{
+			want("Frito Pie", "Your Easy Beef Chili over corn chips.", "Easy Beef Chili"),
+			want("Chili Mac", "The Beef Chili, not the Easy Beef Chili, over macaroni.", "Beef Chili"),
+		},
+		Dropped: []DroppedSideQuest{
+			{Name: "Chili Verde", Why: "reason names none of its cited Regulars"},
+			{Name: "Tamale Bake", Why: "reason names none of its cited Regulars"},
+		},
+	})
+}
+
+func TestSuggestSideQuestsReasonMentionRule(t *testing.T) {
+	const none = "reason names none of its cited Regulars"
+	for name, tc := range map[string]struct {
+		extra  []string // Regulars added to household's
+		reason string
+		cited  string
+		why    string // "" when the Side quest is kept
+	}{
+		"exact name":                   {nil, "Like your Beef Chili, gone green.", "Beef Chili", ""},
+		"other case and spacing":       {nil, "Like your beef  CHILI, gone green.", "Beef Chili", ""},
+		"sentence punctuation":         {nil, `Green, like "Beef Chili" (yours).`, "Beef Chili", ""},
+		"possessive":                   {nil, "Beef Chili's spices, gone green.", "Beef Chili", ""},
+		"joined by punctuation":        {nil, "A Beef Chili-inspired stew.", "Beef Chili", ""},
+		"no mention":                   {nil, "Grilled skewers with a peanut sauce.", "Beef Chili", none},
+		"letters run on":               {[]string{"Ham"}, "Like your Hamburgers, glazed.", "Ham", none},
+		"stored punctuation written":   {[]string{"Easy Beef Chili!"}, "Your Easy Beef Chili! over corn chips.", "Easy Beef Chili!", ""},
+		"stored punctuation as period": {[]string{"Easy Beef Chili!"}, "Corn chips under your Easy Beef Chili.", "Easy Beef Chili!", ""},
+		"inside stored punctuation":    {[]string{"Easy Beef Chili!"}, "Your Easy Beef Chili! over corn chips.", "Beef Chili", none},
+		"inside before period":         {[]string{"Easy Beef Chili!"}, "Corn chips under your Easy Beef Chili.", "Beef Chili", none},
+		"longer name cited":            {[]string{"Easy Beef Chili"}, "Your Easy Beef Chili over corn chips.", "Easy Beef Chili", ""},
+		"shorter inside longer":        {[]string{"Easy Beef Chili"}, "Your Easy Beef Chili over corn chips.", "Beef Chili", none},
+		"longer not mentioned":         {[]string{"Easy Beef Chili"}, "Your Beef Chili over corn chips.", "Easy Beef Chili", none},
+		"shorter also on its own":      {[]string{"Easy Beef Chili"}, "The Beef Chili, not the Easy Beef Chili.", "Beef Chili", ""},
+		"punctuation-only difference":  {[]string{"Beef Chili!"}, "Your Beef Chili! over corn chips.", "Beef Chili!", ""},
+		"bare name inside punctuated":  {[]string{"Beef Chili!"}, "Your Beef Chili! over corn chips.", "Beef Chili", none},
+		"spelled alike by both":        {[]string{"Beef Chili!"}, "Corn chips under your Beef Chili.", "Beef Chili", none},
+		"punctuation then a letter":    {[]string{"Beef Chili!"}, "Your Beef Chili!X is our inspiration.", "Beef Chili!", none},
+		"letter before punctuation":    {[]string{"¡Beef Chili"}, "Your X¡Beef Chili is our inspiration.", "¡Beef Chili", none},
+		"spacing before punctuation":   {[]string{"Beef Chili!"}, "Your Beef Chili ! over corn chips.", "Beef Chili!", ""},
+		"spacing after punctuation":    {[]string{"¡Beef Chili"}, "Your ¡ Beef Chili is our inspiration.", "¡Beef Chili", ""},
+		"stored spacing left off":      {[]string{"Beef Chili !", "Chili!"}, "Like your Beef Chili!", "Beef Chili !", ""},
+		"inside unspaced punctuation":  {[]string{"Beef Chili !", "Chili!"}, "Like your Beef Chili!", "Chili!", none},
+		"stored punctuation partly":    {[]string{"Beef Chili!!", "Chili!"}, "Like your Beef Chili!", "Beef Chili!!", ""},
+		"inside partial punctuation":   {[]string{"Beef Chili!!", "Chili!"}, "Like your Beef Chili!", "Chili!", none},
+		"partly then a letter":         {[]string{"Beef Chili!!", "Chili!"}, "Your Beef Chili!!X is our inspiration.", "Chili!", none},
+		"leading punctuation partly":   {[]string{"¡¡Beef Chili", "¡Beef"}, "Like your ¡Beef Chili.", "¡¡Beef Chili", ""},
+		"inside partial leading":       {[]string{"¡¡Beef Chili", "¡Beef"}, "Like your ¡Beef Chili.", "¡Beef", none},
+		"stored symbol left off":       {[]string{"Green Chili 🌶"}, "Like your Green Chili, gone green.", "Green Chili 🌶", none},
+		"stored accent left off":       {[]string{"Chicken Cafe\u0301"}, "Like your Chicken Cafe, gone green.", "Chicken Cafe\u0301", none},
+		"accent written after name":    {[]string{"Chicken Cafe"}, "Like your Chicken Cafe\u0301, gone green.", "Chicken Cafe", none},
+	} {
+		t.Run(name, func(t *testing.T) {
+			in := household
+			in.Context.Regulars = slices.Clone(household.Context.Regulars)
+			for _, r := range tc.extra {
+				in.Context.Regulars = append(in.Context.Regulars, harness.RegularDinner{Name: r, Cuisine: "Tex-Mex", Method: "stovetop", Minutes: 30})
+			}
+			var f llm.Fake
+			f.QueueGenerate(reply(batch(sideQuest("Frito Pie", tc.reason, tc.cited))))
+			out, _, err := suggest(t, &f, in, 1)
+			if err != nil {
+				t.Fatal(err)
+			}
+			result := SideQuests{Suggestions: []SideQuest{want("Frito Pie", oneLine(tc.reason), tc.cited)}}
+			if tc.why != "" {
+				result = SideQuests{Suggestions: []SideQuest{}, Dropped: []DroppedSideQuest{{Name: "Frito Pie", Why: tc.why}}}
+			}
+			assertSideQuests(t, out, result)
+		})
+	}
+}
+
+func TestSuggestSideQuestsDuplicatesDropped(t *testing.T) {
+	declined := sideQuest("The Best Homemade Chicken Tikka-Masala", "Spiced like your Chicken Fajitas.", "Chicken Fajitas")
+	oldDeclined := sideQuest("Fish Tacos!", "Tortillas like your Chicken Fajitas.", "Chicken Fajitas")
+	regular := sideQuest("Easy Beef Chili", "Just like your Beef Chili.", "Beef Chili")
+	questLog := sideQuest("Pad Thai", "Noodles like your Spaghetti Bolognese.", "Spaghetti Bolognese")
+	pending := sideQuest("Shrimp Scampi", "Pasta like your Spaghetti Bolognese.", "Spaghetti Bolognese")
+	again := sideQuest("Chicken Shawarma Bowls", "Chicken Fajitas, but Middle Eastern.", "Chicken Fajitas")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(declined, oldDeclined, regular, questLog, pending, shawarma, again)))
+	in := household
+	in.Needed = 4
+	out, _, err := suggest(t, &f, in, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	known := "repeats a Regular, Quest log dinner, pending or passed Side quest"
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{wantShawarma},
+		Dropped: []DroppedSideQuest{
+			{Name: "The Best Homemade Chicken Tikka-Masala", Why: known},
+			{Name: "Fish Tacos!", Why: known},
+			{Name: "Easy Beef Chili", Why: known},
+			{Name: "Pad Thai", Why: known},
+			{Name: "Shrimp Scampi", Why: known},
+			{Name: "Chicken Shawarma Bowls", Why: `repeats the Side quest "Chicken Shawarma Bowls" in the same batch`},
+		},
+	})
+}
+
+func TestSuggestSideQuestsReasonRulesDropped(t *testing.T) {
+	long := sideQuest("Beef Stroganoff", "Your Beef Chili"+strings.Repeat(" and more", 20)+".", "Beef Chili")
+	unnamed := sideQuest("Chicken Satay", "Grilled skewers with a peanut sauce.", "Chicken Fajitas")
+	wrongOne := sideQuest("Beef Tacos", "Like your Beef Chili, in a shell.", "Chicken Fajitas")
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(long, unnamed, ragu, wrongOne)))
+	out, _, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{wantRagu},
+		Dropped: []DroppedSideQuest{
+			{Name: "Beef Stroganoff", Why: "reason has 196 characters, over 180"},
+			{Name: "Chicken Satay", Why: "reason names none of its cited Regulars"},
+			{Name: "Beef Tacos", Why: "reason names none of its cited Regulars"},
+		},
+	})
+}
+
+func TestSuggestSideQuestsAllDroppedIsNotRepaired(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(batch(sideQuest("Pad Thai", "Like your Beef Chili.", "Beef Chili"))))
+	out, _, err := suggest(t, &f, household, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{
+		Suggestions: []SideQuest{},
+		Dropped:     []DroppedSideQuest{{Name: "Pad Thai", Why: "repeats a Regular, Quest log dinner, pending or passed Side quest"}},
+	})
+}
+
+func TestSuggestSideQuestsMalformedRepairedOnce(t *testing.T) {
+	for name, tc := range map[string]struct{ first, want string }{
+		"truncated JSON": {
+			`{"suggestions":[` + shawarma + `,{"name":"Beef`,
+			"reply does not decode: unexpected EOF",
+		},
+		"omitted field": {
+			batch(strings.Replace(shawarma, `"cuisine":"Fusion",`, ``, 1)),
+			`suggestion has no "cuisine" field; give every field the schema requires`,
+		},
+		"unknown field": {
+			batch(strings.Replace(shawarma, `"easy",`, `"easy","spice":"mild",`, 1)),
+			`suggestion has unknown field "spice"`,
+		},
+		"bad method": {
+			batch(strings.Replace(shawarma, `"stovetop"`, `"air fryer"`, 1)),
+			`suggestion 1 method "air fryer" is not one of stovetop, oven, crockpot, grill, other`,
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			var f llm.Fake
+			f.QueueGenerate(reply(tc.first), reply(batch(shawarma, ragu)))
+			out, reqs, err := suggest(t, &f, household, 2)
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertSideQuests(t, out, SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu}})
+			repair := reqs[1].Messages
+			if len(repair) != 3 || repair[1].Content != tc.first {
+				t.Fatalf("repair turn does not quote the first reply: %+v", repair)
+			}
+			if !strings.Contains(repair[2].Content, tc.want) {
+				t.Fatalf("repair message = %q, want it to contain %q", repair[2].Content, tc.want)
+			}
+		})
+	}
+}
+
+func TestSuggestSideQuestsFillerNameRepaired(t *testing.T) {
+	filler := sideQuest("The.", "Like your Beef Chili.", "Beef Chili")
+	first := batch(filler, filler)
+	var f llm.Fake
+	f.QueueGenerate(reply(first), reply(batch(shawarma, ragu)))
+	out, reqs, err := suggest(t, &f, household, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	assertSideQuests(t, out, SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu}})
+	repair := reqs[1].Messages
+	if len(repair) != 3 || repair[1].Content != first {
+		t.Fatalf("repair turn does not quote the first reply: %+v", repair)
+	}
+	for _, want := range []string{
+		`suggestion 1 name "The." has only filler words; name the dish`,
+		`suggestion 2 name "The." has only filler words; name the dish`,
+	} {
+		if !strings.Contains(repair[2].Content, want) {
+			t.Fatalf("repair message = %q, want it to contain %q", repair[2].Content, want)
+		}
+	}
+}
+
+func TestSuggestSideQuestsMalformedTwiceFails(t *testing.T) {
+	var f llm.Fake
+	f.QueueGenerate(reply(`{"suggestions":`), reply(`{"suggestions":[]}`))
+	out, _, err := suggest(t, &f, household, 2)
+	var bad *harness.BadOutputError
+	if !errors.As(err, &bad) || !errors.Is(err, llm.ErrBadOutput) {
+		t.Fatalf("err = %v, want a BadOutputError", err)
+	}
+	if !slices.Equal(bad.Repair, []string{"suggestions is empty; give 4 Side quests"}) {
+		t.Fatalf("repair problems = %q", bad.Repair)
+	}
+	if out.Suggestions != nil {
+		t.Fatalf("output = %+v, want none", out)
+	}
+}
+
+func TestSideQuestsValidate(t *testing.T) {
+	s := suggestSideQuests{in: household}
+	if p := s.Validate(SideQuests{Suggestions: []SideQuest{wantShawarma}}); len(p) != 0 {
+		t.Fatalf("valid output has problems: %q", p)
+	}
+	if p := s.Validate(SideQuests{Suggestions: []SideQuest{}, Dropped: []DroppedSideQuest{{Name: "x", Why: "y"}}}); len(p) != 0 {
+		t.Fatalf("output whose Side quests were all dropped has problems: %q", p)
+	}
+	for name, tc := range map[string]struct {
+		out  SideQuests
+		want []string
+	}{
+		"empty": {SideQuests{}, []string{"suggestions is empty; give 4 Side quests"}},
+		"too many": {
+			SideQuests{Suggestions: []SideQuest{wantShawarma, wantRagu, wantVerde, wantBulgogi, wantShawarma}},
+			[]string{"suggestions has 5 entries; give at most 4 Side quests"},
+		},
+		"malformed": {
+			SideQuests{Suggestions: []SideQuest{{Name: " ", Method: "air fryer", EstMinutes: 0, Difficulty: "trivial", CitedRegulars: []string{}}}},
+			[]string{
+				"suggestion 1 has an empty name; give one",
+				"suggestion 1 has an empty cuisine; give one",
+				"suggestion 1 has an empty reason; give one",
+				"suggestion 1 has an empty search_query; give one",
+				`suggestion 1 method "air fryer" is not one of stovetop, oven, crockpot, grill, other`,
+				"suggestion 1 est_minutes 0 is not positive; give the minutes from prep to table",
+				`suggestion 1 difficulty "trivial" is not one of easy, medium, hard`,
+			},
+		},
+	} {
+		t.Run(name, func(t *testing.T) {
+			if got := s.Validate(tc.out); !slices.Equal(got, tc.want) {
+				t.Fatalf("problems =\n%s\nwant\n%s", strings.Join(got, "\n"), strings.Join(tc.want, "\n"))
+			}
+		})
+	}
+}
+
+func TestSideQuestsPromptInputRejects(t *testing.T) {
+	noRegulars := household
+	noRegulars.Context.Regulars = nil
+	none := household
+	none.Needed = 0
+	for name, tc := range map[string]struct {
+		in   SideQuestsRequest
+		want string
+	}{
+		"no Regulars": {noRegulars, "household has no Regulars for Side quests to be based on"},
+		"none needed": {none, "0 Side quests needed; the number must be positive"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			_, err := suggestSideQuests{in: tc.in}.PromptInput(tc.in)
+			if err == nil || err.Error() != tc.want {
+				t.Fatalf("err = %v, want %q", err, tc.want)
+			}
+		})
+	}
+}

internal/ai/skills/testdata/draft_week_valid.system.golden

@@ -0,0 +1,80 @@
+## Instructions
+You draft the household's dinner plan for one week, Monday to Sunday: one dinner for each day, chosen from the candidate pool in the household context.
+
+Rules:
+- Give exactly 7 days, one for each date of the week, in order from Monday to Sunday, each date written as YYYY-MM-DD.
+- Use only dinners from the candidate pool, each by its id exactly as the pool writes it.
+- Plan each dinner at most once in the week.
+- Avoid the dinners marked "planned last week" whenever the pool has enough others.
+- Mix the week: vary cuisines and methods, put quick dinners (a crockpot or 30 minutes or less) on weeknights, and include a Quest log dinner when the pool has one.
+
+Give:
+- days: the 7 days, each with date and dinner_id.
+- note: one sentence of at most 160 characters about the week.
+
+One valid day, for a pool with a dinner whose id is "d1" (an example only, not about this household):
+{"date": "2026-01-05", "dinner_id": "d1"}
+
+## Household context
+### Today
+- Thursday 2026-10-08 (America/New_York)
+
+### Regulars
+- Beef Chili (Tex-Mex, crockpot, 240 min)
+- Chicken Fajitas (Tex-Mex, stovetop, 30 min, favorite)
+
+### Quest log
+- Pad Thai
+
+### Passed, oldest first
+(none)
+
+### Recent plans
+- 2026-10-05 Mon: Chicken Fajitas
+- 2026-10-06 Tue: Fish Tacos
+
+### Candidate pool
+- id "chili": Beef Chili (Regular, crockpot, 240 min)
+- id "fajitas": Chicken Fajitas (Regular, stovetop, 30 min, planned last week)
+- id "bolognese": Spaghetti Bolognese (Regular, stovetop, 45 min)
+- id "salmon": Sheet Pan Salmon (Regular, oven)
+- id "tacos": Fish Tacos (Regular, 25 min, planned last week)
+- id "padthai": Pad Thai (Quest log, stovetop, 35 min)
+- id "roast": Pot Roast (Regular, crockpot)
+- id "shawarma": Chicken Shawarma Bowls (Quest log, oven, 40 min)
+
+## Output contract
+This contract overrides any earlier instruction about the form of your reply. Reply with one JSON value matching the JSON Schema "draft_week" below, and nothing else: no prose and no Markdown code fences.
+
+{
+  "type": "object",
+  "properties": {
+    "days": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "date": {
+            "type": "string"
+          },
+          "dinner_id": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "date",
+          "dinner_id"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "note": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "days",
+    "note"
+  ],
+  "additionalProperties": false
+}

internal/ai/skills/testdata/draft_week_valid.user.golden

@@ -0,0 +1 @@
+Draft the week of Mon 2026-10-12, Tue 2026-10-13, Wed 2026-10-14, Thu 2026-10-15, Fri 2026-10-16, Sat 2026-10-17, Sun 2026-10-18.

internal/ai/skills/testdata/suggest_side_quests_clean.system.golden

@@ -0,0 +1,110 @@
+## Instructions
+You suggest Side quests: new dinners for the household to try, based on the dinners it already makes.
+
+Every Side quest must be a dinner the household has not had: never one of its Regulars, its Quest log, its pending Side quests or the dinners it has passed, and never one of those under another name. Base every Side quest on one or more of the household's Regulars, such as a familiar protein in a new cuisine or familiar flavours cooked a new way. Prefer the favorite Regulars, and vary the cuisines across the batch.
+
+Give for each Side quest:
+- name: the dinner's usual name, as a recipe site would title it.
+- cuisine: its cuisine, e.g. "Thai" or "Tex-Mex".
+- method: how it is mainly cooked: "stovetop", "oven", "crockpot" (slow cooker or crock pot), "grill" or "other".
+- est_minutes: your estimate of the whole minutes from starting prep to the table.
+- difficulty: "easy", "medium" or "hard" for a home cook.
+- reason: one sentence of at most 180 characters saying why the household would like it. It must name at least one of the Regulars in cited_regulars.
+- cited_regulars: the Regulars the reason relies on, at least one, each written exactly as its name appears in the Regulars list of the household context, without the details in parentheses. Cite only Regulars from that list.
+- search_query: a web search query that finds a recipe for this dinner.
+
+One valid Side quest, for a household with a Regular named "Chicken Fajitas" (an example only, not about this household):
+{"name": "Chicken Shawarma Bowls", "cuisine": "Middle Eastern", "method": "oven", "est_minutes": 40, "difficulty": "easy", "reason": "Spiced roast chicken and crisp toppings, like your Chicken Fajitas with a Middle Eastern twist.", "cited_regulars": ["Chicken Fajitas"], "search_query": "chicken shawarma bowls recipe"}
+
+## Household context
+### Today
+- Tuesday 2026-10-06 (America/New_York)
+
+### Regulars
+- Beef Chili (Tex-Mex, crockpot, 240 min)
+- Chicken Fajitas (Tex-Mex, stovetop, 30 min, favorite)
+- Spaghetti Bolognese (Italian, stovetop, 45 min)
+
+### Quest log
+- Pad Thai
+
+### Passed, oldest first
+- Chicken Tikka Masala
+
+### Recent plans
+- 2026-10-05 Mon: Chicken Fajitas
+- 2026-10-06 Tue: Beef Chili
+
+### Pending Side quests
+- Shrimp Scampi
+
+## Output contract
+This contract overrides any earlier instruction about the form of your reply. Reply with one JSON value matching the JSON Schema "suggest_side_quests" below, and nothing else: no prose and no Markdown code fences.
+
+{
+  "type": "object",
+  "properties": {
+    "suggestions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "cuisine": {
+            "type": "string"
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "stovetop",
+              "oven",
+              "crockpot",
+              "grill",
+              "other"
+            ]
+          },
+          "est_minutes": {
+            "type": "integer"
+          },
+          "difficulty": {
+            "type": "string",
+            "enum": [
+              "easy",
+              "medium",
+              "hard"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "cited_regulars": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "search_query": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "cuisine",
+          "method",
+          "est_minutes",
+          "difficulty",
+          "reason",
+          "cited_regulars",
+          "search_query"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "suggestions"
+  ],
+  "additionalProperties": false
+}

internal/ai/skills/testdata/suggest_side_quests_clean.user.golden

@@ -0,0 +1 @@
+Suggest 4 Side quests.

internal/db/dinners.sql.go

@@ -347,6 +347,7 @@ func (q *Queries) GroundDinner(ctx context.Context, arg GroundDinnerParams) (Din
 const groundPendingDinner = `-- name: GroundPendingDinner :execrows
 UPDATE dinners
 SET recipe_id = ?1,
+	recipe_url = NULL,
 	photo_id = ?2,
 	method = COALESCE(method, ?3),
 	minutes_total = COALESCE(minutes_total, ?4),
@@ -375,7 +376,8 @@ type GroundPendingDinnerParams struct {
 // 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,
 // minutes_total or difficulty already set is kept: a pending dinner has
-// them only when a member edited them while it was grounding.
+// them only when a member edited them while it was grounding. Like
+// GroundDinner it clears the pasted recipe_url: the recipe replaces the link.
 func (q *Queries) GroundPendingDinner(ctx context.Context, arg GroundPendingDinnerParams) (int64, error) {
 	result, err := q.db.ExecContext(ctx, groundPendingDinner,
 		arg.RecipeID,
@@ -501,6 +503,63 @@ func (q *Queries) ListUnarchivedDinners(ctx context.Context) ([]ListUnarchivedDi
 	return items, nil
 }
 
+const listUnplannedQuestLogDinners = `-- name: ListUnplannedQuestLogDinners :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 = 'quest_log'
+  AND NOT EXISTS (
+	SELECT 1 FROM plan_days
+	JOIN week_plans ON week_plans.id = plan_days.plan_id
+	WHERE plan_days.dinner_id = dinners.id
+	  AND week_plans.week_start >= ?1
+  )
+ORDER BY normalized_name, id
+`
+
+// The Quest log: dinners with status quest_log that no plan for the week
+// starting from_week_start or later has on any day.
+func (q *Queries) ListUnplannedQuestLogDinners(ctx context.Context, fromWeekStart string) ([]Dinner, error) {
+	rows, err := q.db.QueryContext(ctx, listUnplannedQuestLogDinners, fromWeekStart)
+	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 setDinnerFavorite = `-- name: SetDinnerFavorite :one
 UPDATE dinners
 SET is_favorite = ?,

internal/db/household_context.sql.go

@@ -52,20 +52,26 @@ func (q *Queries) ListPlannedDinners(ctx context.Context, arg ListPlannedDinners
 	return items, nil
 }
 
-const listRecentDeclinedNames = `-- name: ListRecentDeclinedNames :many
+const listRecentPassedNames = `-- name: ListRecentPassedNames :many
 
-SELECT dinners.name
-FROM suggestions
-JOIN dinners ON dinners.id = suggestions.dinner_id
-WHERE suggestions.status = 'declined'
-ORDER BY suggestions.decided_at DESC, suggestions.id DESC
+SELECT name FROM (
+	SELECT name, decided_at, id
+	FROM suggestions
+	WHERE status = 'declined'
+	UNION ALL
+	SELECT name, decided_at, id
+	FROM rotation_reviews
+	WHERE decision = 'drop'
+)
+ORDER BY decided_at DESC, id DESC
 LIMIT ?
 `
 
 // Reads for the AI household context block (internal/ai/harness).
-// The names of the most recently declined suggestions, newest first.
-func (q *Queries) ListRecentDeclinedNames(ctx context.Context, limit int64) ([]string, error) {
-	rows, err := q.db.QueryContext(ctx, listRecentDeclinedNames, limit)
+// The most recent names the household turned down, newest first, as
+// ListPassedNames has them.
+func (q *Queries) ListRecentPassedNames(ctx context.Context, limit int64) ([]string, error) {
+	rows, err := q.db.QueryContext(ctx, listRecentPassedNames, limit)
 	if err != nil {
 		return nil, err
 	}

internal/db/models.go

@@ -228,6 +228,7 @@ type RotationReview struct {
 	PlanDate  string
 	Status    string
 	Decision  sql.NullString
+	Name      sql.NullString
 	DecidedAt sql.NullString
 	UpdatedBy sql.NullString
 	CreatedAt string
@@ -289,6 +290,7 @@ type Suggestion struct {
 	ID              string
 	DinnerID        string
 	BatchID         string
+	Name            string
 	Reason          string
 	CitedRegularIds string
 	Status          string
@@ -315,4 +317,5 @@ type WeekPlan struct {
 	CalendarSyncedAt sql.NullString
 	CreatedAt        string
 	UpdatedAt        string
+	Revision         int64
 }

internal/db/plans.sql.go

@@ -0,0 +1,355 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: plans.sql
+
+package db
+
+import (
+	"context"
+	"database/sql"
+)
+
+const createWeekPlan = `-- name: CreateWeekPlan :exec
+INSERT INTO week_plans (id, week_start, status, ai_note, created_at, updated_at)
+VALUES (?, ?, 'draft', ?, ?, ?)
+`
+
+type CreateWeekPlanParams struct {
+	ID        string
+	WeekStart string
+	AiNote    sql.NullString
+	CreatedAt string
+	UpdatedAt string
+}
+
+func (q *Queries) CreateWeekPlan(ctx context.Context, arg CreateWeekPlanParams) error {
+	_, err := q.db.ExecContext(ctx, createWeekPlan,
+		arg.ID,
+		arg.WeekStart,
+		arg.AiNote,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	return err
+}
+
+const getActiveDraftJob = `-- name: GetActiveDraftJob :one
+SELECT id, CAST(json_extract(payload, '$.confirm') = 1 AS INTEGER) AS confirmed
+FROM jobs
+WHERE kind = ?1
+	AND status IN ('queued', 'running')
+	AND json_extract(payload, '$.week_start') = ?2
+ORDER BY id
+LIMIT 1
+`
+
+type GetActiveDraftJobParams struct {
+	Kind      string
+	WeekStart string
+}
+
+type GetActiveDraftJobRow struct {
+	ID        string
+	Confirmed int64
+}
+
+// The job of kind queued or running for the week starting week_start,
+// with whether its payload has confirm. StartDraft enqueues a draft only
+// when there is none, so there is at most one. Returns sql.ErrNoRows when
+// there is none.
+func (q *Queries) GetActiveDraftJob(ctx context.Context, arg GetActiveDraftJobParams) (GetActiveDraftJobRow, error) {
+	row := q.db.QueryRowContext(ctx, getActiveDraftJob, arg.Kind, arg.WeekStart)
+	var i GetActiveDraftJobRow
+	err := row.Scan(&i.ID, &i.Confirmed)
+	return i, err
+}
+
+const getWeekPlan = `-- name: GetWeekPlan :one
+SELECT id, week_start, status, ai_note, ai_run_id, calendar_synced_at, created_at, updated_at, revision FROM week_plans
+WHERE week_start = ?
+`
+
+// The plan of the week starting week_start. Returns sql.ErrNoRows when
+// there is none.
+func (q *Queries) GetWeekPlan(ctx context.Context, weekStart string) (WeekPlan, error) {
+	row := q.db.QueryRowContext(ctx, getWeekPlan, weekStart)
+	var i WeekPlan
+	err := row.Scan(
+		&i.ID,
+		&i.WeekStart,
+		&i.Status,
+		&i.AiNote,
+		&i.AiRunID,
+		&i.CalendarSyncedAt,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+		&i.Revision,
+	)
+	return i, err
+}
+
+const listDraftPool = `-- name: ListDraftPool :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 = 'regular'
+	OR (status = 'quest_log' AND NOT EXISTS (
+		SELECT 1 FROM plan_days
+		JOIN week_plans ON week_plans.id = plan_days.plan_id
+		WHERE plan_days.dinner_id = dinners.id
+			AND week_plans.week_start >= ?1
+			AND week_plans.week_start <> ?2
+	))
+ORDER BY normalized_name, id
+`
+
+type ListDraftPoolParams struct {
+	FromWeekStart string
+	WeekStart     string
+}
+
+// The dinners a draft of the week starting week_start may plan: every
+// Regular, and every Quest log dinner no other plan for the week starting
+// from_week_start or later has on any day.
+func (q *Queries) ListDraftPool(ctx context.Context, arg ListDraftPoolParams) ([]Dinner, error) {
+	rows, err := q.db.QueryContext(ctx, listDraftPool, arg.FromWeekStart, arg.WeekStart)
+	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 listPlanDays = `-- name: ListPlanDays :many
+SELECT plan_days.date, plan_days.is_new, 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
+FROM plan_days
+JOIN dinners ON dinners.id = plan_days.dinner_id
+WHERE plan_days.plan_id = ?
+ORDER BY plan_days.date
+`
+
+type ListPlanDaysRow struct {
+	Date   string
+	IsNew  int64
+	Dinner Dinner
+}
+
+// The days of plan plan_id with their dinners, Monday first. A day with
+// no dinner is left out.
+func (q *Queries) ListPlanDays(ctx context.Context, planID string) ([]ListPlanDaysRow, error) {
+	rows, err := q.db.QueryContext(ctx, listPlanDays, planID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListPlanDaysRow
+	for rows.Next() {
+		var i ListPlanDaysRow
+		if err := rows.Scan(
+			&i.Date,
+			&i.IsNew,
+			&i.Dinner.ID,
+			&i.Dinner.Name,
+			&i.Dinner.NormalizedName,
+			&i.Dinner.Status,
+			&i.Dinner.Origin,
+			&i.Dinner.Method,
+			&i.Dinner.MinutesTotal,
+			&i.Dinner.Difficulty,
+			&i.Dinner.Cuisine,
+			&i.Dinner.IsFavorite,
+			&i.Dinner.RecipeID,
+			&i.Dinner.PhotoID,
+			&i.Dinner.GroundingStatus,
+			&i.Dinner.UpdatedBy,
+			&i.Dinner.CreatedAt,
+			&i.Dinner.UpdatedAt,
+			&i.Dinner.RecipeUrl,
+			&i.Dinner.GroundingError,
+			&i.Dinner.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 listWeekPlanDinnerIDs = `-- name: ListWeekPlanDinnerIDs :many
+SELECT plan_days.dinner_id
+FROM plan_days
+JOIN week_plans ON week_plans.id = plan_days.plan_id
+WHERE week_plans.week_start = ? AND plan_days.dinner_id IS NOT NULL
+ORDER BY plan_days.date
+`
+
+// The ids of the dinners planned in the week starting week_start, Monday
+// first.
+func (q *Queries) ListWeekPlanDinnerIDs(ctx context.Context, weekStart string) ([]sql.NullString, error) {
+	rows, err := q.db.QueryContext(ctx, listWeekPlanDinnerIDs, weekStart)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []sql.NullString
+	for rows.Next() {
+		var dinner_id sql.NullString
+		if err := rows.Scan(&dinner_id); err != nil {
+			return nil, err
+		}
+		items = append(items, dinner_id)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const markWeekPlanEdited = `-- name: MarkWeekPlanEdited :exec
+UPDATE week_plans
+SET status = CASE WHEN status = 'synced' THEN 'changed' ELSE status END,
+	revision = revision + 1,
+	updated_at = ?
+WHERE id = ?
+`
+
+type MarkWeekPlanEditedParams struct {
+	UpdatedAt string
+	ID        string
+}
+
+// Records an edit of plan id, raising its revision: a synced plan becomes
+// changed, any other keeps its status.
+func (q *Queries) MarkWeekPlanEdited(ctx context.Context, arg MarkWeekPlanEditedParams) error {
+	_, err := q.db.ExecContext(ctx, markWeekPlanEdited, arg.UpdatedAt, arg.ID)
+	return err
+}
+
+const putPlanDay = `-- name: PutPlanDay :exec
+INSERT INTO plan_days (id, plan_id, date, dinner_id, is_new, created_at, updated_at)
+VALUES (?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT (plan_id, date) DO UPDATE
+SET dinner_id = excluded.dinner_id, is_new = excluded.is_new, updated_at = excluded.updated_at
+`
+
+type PutPlanDayParams struct {
+	ID        string
+	PlanID    string
+	Date      string
+	DinnerID  sql.NullString
+	IsNew     int64
+	CreatedAt string
+	UpdatedAt string
+}
+
+// Plans dinner_id on date of plan_id, keeping the day's calendar event id
+// when the day exists.
+func (q *Queries) PutPlanDay(ctx context.Context, arg PutPlanDayParams) error {
+	_, err := q.db.ExecContext(ctx, putPlanDay,
+		arg.ID,
+		arg.PlanID,
+		arg.Date,
+		arg.DinnerID,
+		arg.IsNew,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	return err
+}
+
+const redraftWeekPlan = `-- name: RedraftWeekPlan :exec
+UPDATE week_plans
+SET status = ?, ai_note = ?, revision = revision + 1, updated_at = ?
+WHERE id = ?
+`
+
+type RedraftWeekPlanParams struct {
+	Status    string
+	AiNote    sql.NullString
+	UpdatedAt string
+	ID        string
+}
+
+// Records a new draft over plan id: its status and note, raising its
+// revision.
+func (q *Queries) RedraftWeekPlan(ctx context.Context, arg RedraftWeekPlanParams) error {
+	_, err := q.db.ExecContext(ctx, redraftWeekPlan,
+		arg.Status,
+		arg.AiNote,
+		arg.UpdatedAt,
+		arg.ID,
+	)
+	return err
+}
+
+const swapPlanDay = `-- name: SwapPlanDay :execrows
+UPDATE plan_days
+SET dinner_id = ?, is_new = ?, updated_at = ?
+WHERE plan_id = ? AND date = ?
+`
+
+type SwapPlanDayParams struct {
+	DinnerID  sql.NullString
+	IsNew     int64
+	UpdatedAt string
+	PlanID    string
+	Date      string
+}
+
+// Plans dinner_id on an existing day of plan_id; a date the plan does not
+// have is left as it is (0 rows).
+func (q *Queries) SwapPlanDay(ctx context.Context, arg SwapPlanDayParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, swapPlanDay,
+		arg.DinnerID,
+		arg.IsNew,
+		arg.UpdatedAt,
+		arg.PlanID,
+		arg.Date,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}

internal/db/querier.go

@@ -21,8 +21,12 @@ type Querier interface {
 	// Drops references to the runs created before the cutoff, so the purge
 	// can delete them.
 	ClearWeekPlanAIRunsBefore(ctx context.Context, cutoff string) (int64, error)
+	// How many suggestions ListDeck returns.
+	CountDeck(ctx context.Context) (int64, error)
 	// How many Regulars the household has; archived dinners are not counted.
 	CountRegularDinners(ctx context.Context) (int64, error)
+	// How many Rotation checks dinner_id has had, pending or decided.
+	CountRotationReviews(ctx context.Context, dinnerID string) (int64, error)
 	CreateAIRun(ctx context.Context, arg CreateAIRunParams) error
 	CreateDinner(ctx context.Context, arg CreateDinnerParams) (Dinner, error)
 	CreateJob(ctx context.Context, arg CreateJobParams) error
@@ -32,6 +36,19 @@ type Querier interface {
 	CreatePhoto(ctx context.Context, arg CreatePhotoParams) (Photo, error)
 	CreateRecipeIngredient(ctx context.Context, arg CreateRecipeIngredientParams) error
 	CreateRecipeStep(ctx context.Context, arg CreateRecipeStepParams) error
+	CreateRotationReview(ctx context.Context, arg CreateRotationReviewParams) error
+	// name is the name the dish is suggested under, kept whatever its dinner is
+	// later renamed.
+	CreateSuggestion(ctx context.Context, arg CreateSuggestionParams) error
+	CreateSuggestionBatch(ctx context.Context, arg CreateSuggestionBatchParams) (SuggestionBatch, error)
+	CreateWeekPlan(ctx context.Context, arg CreateWeekPlanParams) error
+	// Records the household's decision on a pending Rotation check, with the
+	// dinner's name for a drop and NULL otherwise; one already decided is left
+	// as it is (0 rows).
+	DecideRotationReview(ctx context.Context, arg DecideRotationReviewParams) (int64, error)
+	// Records the household's decision on a pending suggestion; one already
+	// decided is left as it is (0 rows).
+	DecideSuggestion(ctx context.Context, arg DecideSuggestionParams) (int64, error)
 	DeleteAIRunsBefore(ctx context.Context, cutoff string) (int64, error)
 	DeleteRecipeIngredients(ctx context.Context, recipeID string) error
 	DeleteRecipeSteps(ctx context.Context, recipeID string) error
@@ -42,6 +59,10 @@ type Querier interface {
 	// archived dinner is left as it is; archiving stopped its grounding. Run at
 	// boot, after the job runner fails the jobs a previous process left running.
 	FailOrphanedPendingDinnerGroundings(ctx context.Context, arg FailOrphanedPendingDinnerGroundingsParams) (int64, error)
+	// Fails every batch still pending or running whose job is no longer queued
+	// or running: the process stopped, or recording the batch's end failed,
+	// before its handler recorded a result. Run before reading the active batch.
+	FailOrphanedSuggestionBatches(ctx context.Context, arg FailOrphanedSuggestionBatchesParams) (int64, error)
 	// Records why the background grounding of an unarchived dinner still
 	// pending at the grounding_revision it was grounded for failed; a dinner
 	// grounded some other way, renamed or archived meanwhile is left as it is
@@ -49,8 +70,19 @@ type Querier interface {
 	FailPendingDinnerGrounding(ctx context.Context, arg FailPendingDinnerGroundingParams) (int64, error)
 	// Fails every job left running, at boot before any worker starts.
 	FailRunningJobs(ctx context.Context, arg FailRunningJobsParams) (int64, error)
+	// Records a pending or running batch as done or failed; a batch already
+	// finished is left as it is (0 rows).
+	FinishSuggestionBatch(ctx context.Context, arg FinishSuggestionBatchParams) (int64, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetAISettings(ctx context.Context) (AiSetting, error)
+	// The job of kind queued or running for the week starting week_start,
+	// with whether its payload has confirm. StartDraft enqueues a draft only
+	// 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 batch still pending or running, oldest first. Returns sql.ErrNoRows
+	// when there is none.
+	GetActiveSuggestionBatch(ctx context.Context) (SuggestionBatch, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetChatSettings(ctx context.Context) (ChatSetting, error)
 	GetDinner(ctx context.Context, id string) (Dinner, error)
@@ -59,6 +91,13 @@ type Querier interface {
 	// Returns sql.ErrNoRows until the row exists.
 	GetIntegrationsGoogle(ctx context.Context) (IntegrationsGoogle, error)
 	GetJob(ctx context.Context, id string) (Job, error)
+	// The newest batch, whatever its status. Returns sql.ErrNoRows when there
+	// is none.
+	GetLatestSuggestionBatch(ctx context.Context) (SuggestionBatch, error)
+	// The pending Rotation check of dinner_id. MarkTried makes one only for a
+	// dinner in the Quest log, which it moves to tried, so a dinner has at
+	// most one. Returns sql.ErrNoRows when there is none.
+	GetPendingRotationReview(ctx context.Context, dinnerID string) (RotationReview, error)
 	GetPhoto(ctx context.Context, id string) (Photo, error)
 	// Finds stored image bytes by content hash. The schema does not make sha256
 	// unique, so the earliest-created (lowest id) match is returned.
@@ -67,6 +106,13 @@ type Querier interface {
 	GetRecipeBySourceURL(ctx context.Context, sourceUrl string) (Recipe, error)
 	// Returns sql.ErrNoRows until the row exists.
 	GetRecipeSearchSettings(ctx context.Context) (RecipeSearchSetting, error)
+	// A suggestion with its dinner. Returns sql.ErrNoRows for an unknown id.
+	GetSuggestion(ctx context.Context, id string) (GetSuggestionRow, error)
+	// The id of the job that runs batch batch_id.
+	GetSuggestionBatchJobID(ctx context.Context, arg GetSuggestionBatchJobIDParams) (string, error)
+	// The plan of the week starting week_start. Returns sql.ErrNoRows when
+	// there is none.
+	GetWeekPlan(ctx context.Context, weekStart string) (WeekPlan, error)
 	// Records a dinner's grounding by hand (grounded or manual) and clears any
 	// grounding_error and pasted recipe_url: the recipe chosen replaces the
 	// link. It writes only an unarchived dinner still as it was observed
@@ -80,25 +126,80 @@ type Querier interface {
 	// 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,
 	// minutes_total or difficulty already set is kept: a pending dinner has
-	// them only when a member edited them while it was grounding.
+	// 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)
+	// The pending suggestions whose dinner is still suggested, oldest first,
+	// with their dinners.
+	ListDeck(ctx context.Context) ([]ListDeckRow, error)
 	ListDinnersByStatus(ctx context.Context, status string) ([]Dinner, error)
+	// The dinners a draft of the week starting week_start may plan: every
+	// Regular, and every Quest log dinner no other plan for the week starting
+	// from_week_start or later has on any day.
+	ListDraftPool(ctx context.Context, arg ListDraftPoolParams) ([]Dinner, error)
+	// Every name the household turned down, oldest decision first: the name
+	// each declined suggestion was suggested under, which renaming its dinner
+	// does not change, and the name each dinner a Rotation check dropped
+	// ("Not for us") had when dropped, which renaming it does not change.
+	ListPassedNames(ctx context.Context) ([]string, error)
+	// The pending Rotation checks whose dinner is still tried, oldest plan
+	// date first, with their dinners.
+	ListPendingRotationReviews(ctx context.Context) ([]ListPendingRotationReviewsRow, 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)
 	// The planned dinners dated from from_date up to but not including
 	// to_date, oldest first. Days with no dinner are left out.
 	ListPlannedDinners(ctx context.Context, arg ListPlannedDinnersParams) ([]ListPlannedDinnersRow, error)
 	// Reads for the AI household context block (internal/ai/harness).
-	// The names of the most recently declined suggestions, newest first.
-	ListRecentDeclinedNames(ctx context.Context, limit int64) ([]string, error)
+	// The most recent names the household turned down, newest first, as
+	// ListPassedNames has them.
+	ListRecentPassedNames(ctx context.Context, limit int64) ([]string, error)
 	ListRecipeIngredients(ctx context.Context, recipeID string) ([]RecipeIngredient, error)
 	ListRecipeSteps(ctx context.Context, recipeID string) ([]RecipeStep, error)
+	// The ids of the dinners with status quest_log planned on date, on a plan
+	// of any status, that have no Rotation check for date yet.
+	ListTriedCandidates(ctx context.Context, date string) ([]string, error)
 	// Every dinner a new or renamed dinner must not repeat, with the
 	// source_url of the recipe it is grounded in (NULL while it has none).
 	ListUnarchivedDinners(ctx context.Context) ([]ListUnarchivedDinnersRow, error)
+	// The Quest log: dinners with status quest_log that no plan for the week
+	// starting from_week_start or later has on any day.
+	ListUnplannedQuestLogDinners(ctx context.Context, fromWeekStart string) ([]Dinner, error)
+	// The ids of the dinners planned in the week starting week_start, Monday
+	// first.
+	ListWeekPlanDinnerIDs(ctx context.Context, weekStart string) ([]sql.NullString, error)
+	// Moves a dinner still in the Quest log to tried; a dinner with any other
+	// status is left as it is (0 rows).
+	MarkDinnerTried(ctx context.Context, arg MarkDinnerTriedParams) (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
+	// Moves a dinner still suggested to status (quest_log or archived),
+	// recording updated_by; a dinner no longer suggested is left as it is
+	// (0 rows).
+	MoveSuggestedDinner(ctx context.Context, arg MoveSuggestedDinnerParams) (int64, error)
+	// Moves a dinner still tried to status (regular, archived or quest_log)
+	// by a Rotation check decision, recording updated_by; its origin is kept.
+	// A dinner no longer tried is left as it is (0 rows).
+	MoveTriedDinner(ctx context.Context, arg MoveTriedDinnerParams) (int64, error)
 	// Stores a partial result of a running job.
 	PublishJobResult(ctx context.Context, arg PublishJobResultParams) (int64, error)
+	// Plans dinner_id on date of plan_id, keeping the day's calendar event id
+	// when the day exists.
+	PutPlanDay(ctx context.Context, arg PutPlanDayParams) error
+	// Records a new draft over plan id: its status and note, raising its
+	// revision.
+	RedraftWeekPlan(ctx context.Context, arg RedraftWeekPlanParams) error
 	// An unknown id returns sql.ErrNoRows.
 	SetDinnerFavorite(ctx context.Context, arg SetDinnerFavoriteParams) (Dinner, error)
+	// Marks a pending batch running; a batch in any other status is left as
+	// it is (0 rows).
+	StartSuggestionBatch(ctx context.Context, arg StartSuggestionBatchParams) (int64, error)
 	SucceedJob(ctx context.Context, arg SucceedJobParams) (int64, error)
+	// Plans dinner_id on an existing day of plan_id; a date the plan does not
+	// have is left as it is (0 rows).
+	SwapPlanDay(ctx context.Context, arg SwapPlanDayParams) (int64, error)
 	// An unknown id returns sql.ErrNoRows.
 	ToggleDinnerFavorite(ctx context.Context, arg ToggleDinnerFavoriteParams) (Dinner, error)
 	// An unknown id returns sql.ErrNoRows.

internal/db/rotation_reviews.sql.go

@@ -0,0 +1,257 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: rotation_reviews.sql
+
+package db
+
+import (
+	"context"
+	"database/sql"
+)
+
+const countRotationReviews = `-- name: CountRotationReviews :one
+SELECT COUNT(*) FROM rotation_reviews WHERE dinner_id = ?
+`
+
+// How many Rotation checks dinner_id has had, pending or decided.
+func (q *Queries) CountRotationReviews(ctx context.Context, dinnerID string) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countRotationReviews, dinnerID)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const createRotationReview = `-- name: CreateRotationReview :exec
+INSERT INTO rotation_reviews (id, dinner_id, plan_date, status, created_at, updated_at)
+VALUES (?, ?, ?, 'pending', ?, ?)
+`
+
+type CreateRotationReviewParams struct {
+	ID        string
+	DinnerID  string
+	PlanDate  string
+	CreatedAt string
+	UpdatedAt string
+}
+
+func (q *Queries) CreateRotationReview(ctx context.Context, arg CreateRotationReviewParams) error {
+	_, err := q.db.ExecContext(ctx, createRotationReview,
+		arg.ID,
+		arg.DinnerID,
+		arg.PlanDate,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	return err
+}
+
+const decideRotationReview = `-- name: DecideRotationReview :execrows
+UPDATE rotation_reviews
+SET status = 'decided',
+	decision = ?1,
+	name = ?2,
+	decided_at = ?3,
+	updated_by = ?4,
+	updated_at = ?3
+WHERE id = ?5 AND status = 'pending'
+`
+
+type DecideRotationReviewParams struct {
+	Decision  sql.NullString
+	Name      sql.NullString
+	Now       sql.NullString
+	UpdatedBy sql.NullString
+	ID        string
+}
+
+// Records the household's decision on a pending Rotation check, with the
+// dinner's name for a drop and NULL otherwise; one already decided is left
+// as it is (0 rows).
+func (q *Queries) DecideRotationReview(ctx context.Context, arg DecideRotationReviewParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, decideRotationReview,
+		arg.Decision,
+		arg.Name,
+		arg.Now,
+		arg.UpdatedBy,
+		arg.ID,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const getPendingRotationReview = `-- name: GetPendingRotationReview :one
+SELECT id, dinner_id, plan_date, status, decision, name, decided_at, updated_by, created_at, updated_at FROM rotation_reviews
+WHERE dinner_id = ? AND status = 'pending'
+`
+
+// The pending Rotation check of dinner_id. MarkTried makes one only for a
+// dinner in the Quest log, which it moves to tried, so a dinner has at
+// most one. Returns sql.ErrNoRows when there is none.
+func (q *Queries) GetPendingRotationReview(ctx context.Context, dinnerID string) (RotationReview, error) {
+	row := q.db.QueryRowContext(ctx, getPendingRotationReview, dinnerID)
+	var i RotationReview
+	err := row.Scan(
+		&i.ID,
+		&i.DinnerID,
+		&i.PlanDate,
+		&i.Status,
+		&i.Decision,
+		&i.Name,
+		&i.DecidedAt,
+		&i.UpdatedBy,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const listPendingRotationReviews = `-- name: ListPendingRotationReviews :many
+SELECT rotation_reviews.plan_date, 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
+FROM rotation_reviews
+JOIN dinners ON dinners.id = rotation_reviews.dinner_id
+WHERE rotation_reviews.status = 'pending' AND dinners.status = 'tried'
+ORDER BY rotation_reviews.plan_date, rotation_reviews.id
+`
+
+type ListPendingRotationReviewsRow struct {
+	PlanDate string
+	Dinner   Dinner
+}
+
+// The pending Rotation checks whose dinner is still tried, oldest plan
+// date first, with their dinners.
+func (q *Queries) ListPendingRotationReviews(ctx context.Context) ([]ListPendingRotationReviewsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listPendingRotationReviews)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListPendingRotationReviewsRow
+	for rows.Next() {
+		var i ListPendingRotationReviewsRow
+		if err := rows.Scan(
+			&i.PlanDate,
+			&i.Dinner.ID,
+			&i.Dinner.Name,
+			&i.Dinner.NormalizedName,
+			&i.Dinner.Status,
+			&i.Dinner.Origin,
+			&i.Dinner.Method,
+			&i.Dinner.MinutesTotal,
+			&i.Dinner.Difficulty,
+			&i.Dinner.Cuisine,
+			&i.Dinner.IsFavorite,
+			&i.Dinner.RecipeID,
+			&i.Dinner.PhotoID,
+			&i.Dinner.GroundingStatus,
+			&i.Dinner.UpdatedBy,
+			&i.Dinner.CreatedAt,
+			&i.Dinner.UpdatedAt,
+			&i.Dinner.RecipeUrl,
+			&i.Dinner.GroundingError,
+			&i.Dinner.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 listTriedCandidates = `-- name: ListTriedCandidates :many
+SELECT DISTINCT dinners.id
+FROM plan_days
+JOIN dinners ON dinners.id = plan_days.dinner_id
+WHERE plan_days.date = ?1
+	AND dinners.status = 'quest_log'
+	AND NOT EXISTS (
+		SELECT 1 FROM rotation_reviews
+		WHERE rotation_reviews.dinner_id = dinners.id
+			AND rotation_reviews.plan_date = plan_days.date
+	)
+ORDER BY dinners.id
+`
+
+// The ids of the dinners with status quest_log planned on date, on a plan
+// of any status, that have no Rotation check for date yet.
+func (q *Queries) ListTriedCandidates(ctx context.Context, date string) ([]string, error) {
+	rows, err := q.db.QueryContext(ctx, listTriedCandidates, date)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			return nil, err
+		}
+		items = append(items, id)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const markDinnerTried = `-- name: MarkDinnerTried :execrows
+UPDATE dinners
+SET status = 'tried', updated_at = ?
+WHERE id = ? AND status = 'quest_log'
+`
+
+type MarkDinnerTriedParams struct {
+	UpdatedAt string
+	ID        string
+}
+
+// Moves a dinner still in the Quest log to tried; a dinner with any other
+// status is left as it is (0 rows).
+func (q *Queries) MarkDinnerTried(ctx context.Context, arg MarkDinnerTriedParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, markDinnerTried, arg.UpdatedAt, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const moveTriedDinner = `-- name: MoveTriedDinner :execrows
+UPDATE dinners
+SET status = ?1, updated_by = ?2, updated_at = ?3
+WHERE id = ?4 AND status = 'tried'
+`
+
+type MoveTriedDinnerParams struct {
+	Status    string
+	UpdatedBy sql.NullString
+	UpdatedAt string
+	ID        string
+}
+
+// Moves a dinner still tried to status (regular, archived or quest_log)
+// by a Rotation check decision, recording updated_by; its origin is kept.
+// A dinner no longer tried is left as it is (0 rows).
+func (q *Queries) MoveTriedDinner(ctx context.Context, arg MoveTriedDinnerParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, moveTriedDinner,
+		arg.Status,
+		arg.UpdatedBy,
+		arg.UpdatedAt,
+		arg.ID,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}

internal/db/suggestions.sql.go

@@ -0,0 +1,439 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: suggestions.sql
+
+package db
+
+import (
+	"context"
+	"database/sql"
+)
+
+const countDeck = `-- name: CountDeck :one
+SELECT COUNT(*)
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.status = 'pending' AND dinners.status = 'suggested'
+`
+
+// How many suggestions ListDeck returns.
+func (q *Queries) CountDeck(ctx context.Context) (int64, error) {
+	row := q.db.QueryRowContext(ctx, countDeck)
+	var count int64
+	err := row.Scan(&count)
+	return count, err
+}
+
+const createSuggestion = `-- name: CreateSuggestion :exec
+INSERT INTO suggestions (
+	id, dinner_id, batch_id, name, reason, cited_regular_ids, status, created_at, updated_at
+) VALUES (
+	?, ?, ?, ?, ?, ?, 'pending', ?, ?
+)
+`
+
+type CreateSuggestionParams struct {
+	ID              string
+	DinnerID        string
+	BatchID         string
+	Name            string
+	Reason          string
+	CitedRegularIds string
+	CreatedAt       string
+	UpdatedAt       string
+}
+
+// name is the name the dish is suggested under, kept whatever its dinner is
+// later renamed.
+func (q *Queries) CreateSuggestion(ctx context.Context, arg CreateSuggestionParams) error {
+	_, err := q.db.ExecContext(ctx, createSuggestion,
+		arg.ID,
+		arg.DinnerID,
+		arg.BatchID,
+		arg.Name,
+		arg.Reason,
+		arg.CitedRegularIds,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	return err
+}
+
+const createSuggestionBatch = `-- name: CreateSuggestionBatch :one
+INSERT INTO suggestion_batches (id, trigger, status, created_at, updated_at)
+VALUES (?, ?, 'pending', ?, ?)
+RETURNING id, "trigger", status, ai_run_id, created_at, updated_at
+`
+
+type CreateSuggestionBatchParams struct {
+	ID        string
+	Trigger   string
+	CreatedAt string
+	UpdatedAt string
+}
+
+func (q *Queries) CreateSuggestionBatch(ctx context.Context, arg CreateSuggestionBatchParams) (SuggestionBatch, error) {
+	row := q.db.QueryRowContext(ctx, createSuggestionBatch,
+		arg.ID,
+		arg.Trigger,
+		arg.CreatedAt,
+		arg.UpdatedAt,
+	)
+	var i SuggestionBatch
+	err := row.Scan(
+		&i.ID,
+		&i.Trigger,
+		&i.Status,
+		&i.AiRunID,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const decideSuggestion = `-- name: DecideSuggestion :execrows
+UPDATE suggestions
+SET status = ?1, decided_at = ?2, updated_at = ?2
+WHERE id = ?3 AND status = 'pending'
+`
+
+type DecideSuggestionParams struct {
+	Status string
+	Now    sql.NullString
+	ID     string
+}
+
+// Records the household's decision on a pending suggestion; one already
+// decided is left as it is (0 rows).
+func (q *Queries) DecideSuggestion(ctx context.Context, arg DecideSuggestionParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, decideSuggestion, arg.Status, arg.Now, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const failOrphanedSuggestionBatches = `-- name: FailOrphanedSuggestionBatches :execrows
+UPDATE suggestion_batches
+SET status = 'failed', updated_at = ?1
+WHERE status IN ('pending', 'running')
+	AND NOT EXISTS (
+		SELECT 1 FROM jobs
+		WHERE jobs.kind = ?2
+			AND jobs.status IN ('queued', 'running')
+			AND json_extract(jobs.payload, '$.batch_id') = suggestion_batches.id
+	)
+`
+
+type FailOrphanedSuggestionBatchesParams struct {
+	UpdatedAt string
+	Kind      string
+}
+
+// Fails every batch still pending or running whose job is no longer queued
+// or running: the process stopped, or recording the batch's end failed,
+// before its handler recorded a result. Run before reading the active batch.
+func (q *Queries) FailOrphanedSuggestionBatches(ctx context.Context, arg FailOrphanedSuggestionBatchesParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, failOrphanedSuggestionBatches, arg.UpdatedAt, arg.Kind)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const finishSuggestionBatch = `-- name: FinishSuggestionBatch :execrows
+UPDATE suggestion_batches
+SET status = ?, updated_at = ?
+WHERE id = ? AND status IN ('pending', 'running')
+`
+
+type FinishSuggestionBatchParams struct {
+	Status    string
+	UpdatedAt string
+	ID        string
+}
+
+// Records a pending or running batch as done or failed; a batch already
+// finished is left as it is (0 rows).
+func (q *Queries) FinishSuggestionBatch(ctx context.Context, arg FinishSuggestionBatchParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, finishSuggestionBatch, arg.Status, arg.UpdatedAt, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const getActiveSuggestionBatch = `-- name: GetActiveSuggestionBatch :one
+SELECT id, "trigger", status, ai_run_id, created_at, updated_at FROM suggestion_batches
+WHERE status IN ('pending', 'running')
+ORDER BY id
+LIMIT 1
+`
+
+// The batch still pending or running, oldest first. Returns sql.ErrNoRows
+// when there is none.
+func (q *Queries) GetActiveSuggestionBatch(ctx context.Context) (SuggestionBatch, error) {
+	row := q.db.QueryRowContext(ctx, getActiveSuggestionBatch)
+	var i SuggestionBatch
+	err := row.Scan(
+		&i.ID,
+		&i.Trigger,
+		&i.Status,
+		&i.AiRunID,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const getLatestSuggestionBatch = `-- name: GetLatestSuggestionBatch :one
+SELECT id, "trigger", status, ai_run_id, created_at, updated_at FROM suggestion_batches
+ORDER BY id DESC
+LIMIT 1
+`
+
+// The newest batch, whatever its status. Returns sql.ErrNoRows when there
+// is none.
+func (q *Queries) GetLatestSuggestionBatch(ctx context.Context) (SuggestionBatch, error) {
+	row := q.db.QueryRowContext(ctx, getLatestSuggestionBatch)
+	var i SuggestionBatch
+	err := row.Scan(
+		&i.ID,
+		&i.Trigger,
+		&i.Status,
+		&i.AiRunID,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const getSuggestion = `-- name: GetSuggestion :one
+SELECT suggestions.id, suggestions.dinner_id, suggestions.batch_id, suggestions.name, suggestions.reason, suggestions.cited_regular_ids, suggestions.status, suggestions.decided_at, suggestions.created_at, suggestions.updated_at, 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
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.id = ?
+`
+
+type GetSuggestionRow struct {
+	Suggestion Suggestion
+	Dinner     Dinner
+}
+
+// A suggestion with its dinner. Returns sql.ErrNoRows for an unknown id.
+func (q *Queries) GetSuggestion(ctx context.Context, id string) (GetSuggestionRow, error) {
+	row := q.db.QueryRowContext(ctx, getSuggestion, id)
+	var i GetSuggestionRow
+	err := row.Scan(
+		&i.Suggestion.ID,
+		&i.Suggestion.DinnerID,
+		&i.Suggestion.BatchID,
+		&i.Suggestion.Name,
+		&i.Suggestion.Reason,
+		&i.Suggestion.CitedRegularIds,
+		&i.Suggestion.Status,
+		&i.Suggestion.DecidedAt,
+		&i.Suggestion.CreatedAt,
+		&i.Suggestion.UpdatedAt,
+		&i.Dinner.ID,
+		&i.Dinner.Name,
+		&i.Dinner.NormalizedName,
+		&i.Dinner.Status,
+		&i.Dinner.Origin,
+		&i.Dinner.Method,
+		&i.Dinner.MinutesTotal,
+		&i.Dinner.Difficulty,
+		&i.Dinner.Cuisine,
+		&i.Dinner.IsFavorite,
+		&i.Dinner.RecipeID,
+		&i.Dinner.PhotoID,
+		&i.Dinner.GroundingStatus,
+		&i.Dinner.UpdatedBy,
+		&i.Dinner.CreatedAt,
+		&i.Dinner.UpdatedAt,
+		&i.Dinner.RecipeUrl,
+		&i.Dinner.GroundingError,
+		&i.Dinner.GroundingRevision,
+	)
+	return i, err
+}
+
+const getSuggestionBatchJobID = `-- name: GetSuggestionBatchJobID :one
+SELECT id FROM jobs
+WHERE kind = ?1
+	AND json_extract(payload, '$.batch_id') = ?2
+ORDER BY id
+LIMIT 1
+`
+
+type GetSuggestionBatchJobIDParams struct {
+	Kind    string
+	BatchID string
+}
+
+// The id of the job that runs batch batch_id.
+func (q *Queries) GetSuggestionBatchJobID(ctx context.Context, arg GetSuggestionBatchJobIDParams) (string, error) {
+	row := q.db.QueryRowContext(ctx, getSuggestionBatchJobID, arg.Kind, arg.BatchID)
+	var id string
+	err := row.Scan(&id)
+	return id, err
+}
+
+const listDeck = `-- name: ListDeck :many
+SELECT suggestions.id, suggestions.dinner_id, suggestions.batch_id, suggestions.name, suggestions.reason, suggestions.cited_regular_ids, suggestions.status, suggestions.decided_at, suggestions.created_at, suggestions.updated_at, 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
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.status = 'pending' AND dinners.status = 'suggested'
+ORDER BY suggestions.created_at, suggestions.id
+`
+
+type ListDeckRow struct {
+	Suggestion Suggestion
+	Dinner     Dinner
+}
+
+// The pending suggestions whose dinner is still suggested, oldest first,
+// with their dinners.
+func (q *Queries) ListDeck(ctx context.Context) ([]ListDeckRow, error) {
+	rows, err := q.db.QueryContext(ctx, listDeck)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListDeckRow
+	for rows.Next() {
+		var i ListDeckRow
+		if err := rows.Scan(
+			&i.Suggestion.ID,
+			&i.Suggestion.DinnerID,
+			&i.Suggestion.BatchID,
+			&i.Suggestion.Name,
+			&i.Suggestion.Reason,
+			&i.Suggestion.CitedRegularIds,
+			&i.Suggestion.Status,
+			&i.Suggestion.DecidedAt,
+			&i.Suggestion.CreatedAt,
+			&i.Suggestion.UpdatedAt,
+			&i.Dinner.ID,
+			&i.Dinner.Name,
+			&i.Dinner.NormalizedName,
+			&i.Dinner.Status,
+			&i.Dinner.Origin,
+			&i.Dinner.Method,
+			&i.Dinner.MinutesTotal,
+			&i.Dinner.Difficulty,
+			&i.Dinner.Cuisine,
+			&i.Dinner.IsFavorite,
+			&i.Dinner.RecipeID,
+			&i.Dinner.PhotoID,
+			&i.Dinner.GroundingStatus,
+			&i.Dinner.UpdatedBy,
+			&i.Dinner.CreatedAt,
+			&i.Dinner.UpdatedAt,
+			&i.Dinner.RecipeUrl,
+			&i.Dinner.GroundingError,
+			&i.Dinner.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 listPassedNames = `-- name: ListPassedNames :many
+SELECT name FROM (
+	SELECT name, decided_at, id
+	FROM suggestions
+	WHERE status = 'declined'
+	UNION ALL
+	SELECT name, decided_at, id
+	FROM rotation_reviews
+	WHERE decision = 'drop'
+)
+ORDER BY decided_at, id
+`
+
+// Every name the household turned down, oldest decision first: the name
+// each declined suggestion was suggested under, which renaming its dinner
+// does not change, and the name each dinner a Rotation check dropped
+// ("Not for us") had when dropped, which renaming it does not change.
+func (q *Queries) ListPassedNames(ctx context.Context) ([]string, error) {
+	rows, err := q.db.QueryContext(ctx, listPassedNames)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []string
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			return nil, err
+		}
+		items = append(items, name)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const moveSuggestedDinner = `-- name: MoveSuggestedDinner :execrows
+UPDATE dinners
+SET status = ?1, updated_by = ?2, updated_at = ?3
+WHERE id = ?4 AND status = 'suggested'
+`
+
+type MoveSuggestedDinnerParams struct {
+	Status    string
+	UpdatedBy sql.NullString
+	UpdatedAt string
+	ID        string
+}
+
+// Moves a dinner still suggested to status (quest_log or archived),
+// recording updated_by; a dinner no longer suggested is left as it is
+// (0 rows).
+func (q *Queries) MoveSuggestedDinner(ctx context.Context, arg MoveSuggestedDinnerParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, moveSuggestedDinner,
+		arg.Status,
+		arg.UpdatedBy,
+		arg.UpdatedAt,
+		arg.ID,
+	)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
+const startSuggestionBatch = `-- name: StartSuggestionBatch :execrows
+UPDATE suggestion_batches
+SET status = 'running', updated_at = ?
+WHERE id = ? AND status = 'pending'
+`
+
+type StartSuggestionBatchParams struct {
+	UpdatedAt string
+	ID        string
+}
+
+// Marks a pending batch running; a batch in any other status is left as
+// it is (0 rows).
+func (q *Queries) StartSuggestionBatch(ctx context.Context, arg StartSuggestionBatchParams) (int64, error) {
+	result, err := q.db.ExecContext(ctx, startSuggestionBatch, arg.UpdatedAt, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}

internal/dinners/dinners.go

@@ -7,6 +7,7 @@ package dinners
 
 import (
 	"context"
+	"crypto/rand"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -16,10 +17,12 @@ import (
 	"slices"
 	"strings"
 	"sync"
+	"time"
 	"unicode/utf8"
 
 	"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/jobs"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
@@ -140,6 +143,18 @@ type Service struct {
 	// by dinner id, so archiving or renaming a dinner can stop them.
 	groundingsMu sync.Mutex
 	groundings   map[string]map[*runningGrounding]struct{}
+
+	// offerKey keys the candidate ids Candidates offers, so they are
+	// opaque and stable for this process.
+	offerKey []byte
+	// offersMu guards offers and offerSearches. offers holds, by dinner
+	// id, the candidates last offered by Candidates until they expire, so
+	// a candidate id is resolved here and its URL never leaves the server.
+	// offerSearches holds the Candidates searches running, by dinner id,
+	// so clearing a dinner's offers keeps them from storing stale ones.
+	offersMu      sync.Mutex
+	offers        map[string]*offerSet
+	offerSearches map[string]map[*offerSearch]struct{}
 }
 
 // NewService returns a service over st that grounds dinners with grounder
@@ -156,7 +171,8 @@ func NewService(st *store.Store, grounder *recipes.Grounder, runner *jobs.Runner
 	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{})}
+	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{})}
+	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
@@ -273,12 +289,20 @@ func (s *Service) createRegular(ctx context.Context, r NewRegular, updatedBy str
 }
 
 // List returns the dinners with status, which must be regular or
-// quest_log, ordered by normalized name.
+// quest_log, ordered by normalized name. The Quest log is the dinners
+// accepted and not yet scheduled, so a quest_log dinner on the plan for the
+// household's current week or a later one is left out of it.
 func (s *Service) List(ctx context.Context, status string) ([]Dinner, error) {
 	if !slices.Contains(listable, status) {
 		return nil, invalid("status", "must be one of "+strings.Join(listable, ", "))
 	}
-	rows, err := db.New(s.st.Reader).ListDinnersByStatus(ctx, status)
+	var rows []db.Dinner
+	var err error
+	if status == StatusQuestLog {
+		rows, err = s.listQuestLog(ctx)
+	} else {
+		rows, err = db.New(s.st.Reader).ListDinnersByStatus(ctx, status)
+	}
 	if err != nil {
 		return nil, fmt.Errorf("dinners: list %s: %w", status, err)
 	}
@@ -289,13 +313,39 @@ func (s *Service) List(ctx context.Context, status string) ([]Dinner, error) {
 	return out, nil
 }
 
+// listQuestLog reads the Quest log in one read transaction, so the
+// household's current week and the plans come from the same snapshot.
+func (s *Service) listQuestLog(ctx context.Context) (rows []db.Dinner, err error) {
+	tx, err := s.st.Reader.BeginTx(ctx, nil)
+	if err != nil {
+		return nil, fmt.Errorf("begin read: %w", err)
+	}
+	defer func() {
+		err = errors.Join(err, tx.Rollback())
+	}()
+	q := db.New(tx)
+	settings, err := q.GetHouseholdSettings(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("read household settings: %w", err)
+	}
+	loc, err := household.LoadZone(settings.Timezone)
+	if err != nil {
+		return nil, fmt.Errorf("household settings: %w", err)
+	}
+	thisWeek := household.WeekStart(household.Today(time.Now(), loc))
+	return q.ListUnplannedQuestLogDinners(ctx, thisWeek.String())
+}
+
 // Update applies p to dinner id, recording updatedBy. An invalid patch is a
 // *ValidationError and a new name repeating another unarchived dinner a
-// *DuplicateError; either changes nothing. Renaming a dinner still pending
-// clears its recipe_url, raises its grounding_revision and enqueues a fresh
-// KindGroundDinner job that grounds the new name: a job queued or running
-// for the old name or link carries the old revision, so it can no longer
-// write the dinner, and one running is stopped.
+// *DuplicateError; either changes nothing. Renaming a dinner raises its
+// grounding_revision and drops the candidates offered for its old name:
+// each was offered at an earlier revision, so none of them grounds it.
+// Renaming a dinner still pending also enqueues a fresh KindGroundDinner
+// job that grounds the new name, and clears its recipe_url when the
+// normalized name changes: a job queued or running for the old name or
+// link carries the old revision, so it can no longer write the dinner, and
+// one running is stopped.
 func (s *Service) Update(ctx context.Context, id string, p Patch, updatedBy string) (Dinner, error) {
 	if updatedBy == "" {
 		return Dinner{}, errors.New("dinners: update: no member to record as updated_by")
@@ -306,7 +356,7 @@ func (s *Service) Update(ctx context.Context, id string, p Patch, updatedBy stri
 	}
 
 	var row db.Dinner
-	var regrounding bool
+	var renamed, regrounding bool
 	err = s.st.WithTx(ctx, func(tx *sql.Tx) error {
 		q := db.New(tx)
 		cur, err := q.GetDinner(ctx, id)
@@ -340,11 +390,13 @@ func (s *Service) Update(ctx context.Context, id string, p Patch, updatedBy stri
 			}
 			params.Name = name
 			params.NormalizedName = harness.Normalize(name)
+			if name != cur.Name {
+				params.GroundingRevision++
+			}
 			if cur.GroundingStatus == GroundingPending && params.NormalizedName != cur.NormalizedName {
 				// The link was the old dinner's recipe; the new name is
 				// grounded by name, and a link can be given by hand.
 				params.RecipeUrl = sql.NullString{}
-				params.GroundingRevision++
 			}
 		}
 		if p.Method != nil {
@@ -360,12 +412,17 @@ func (s *Service) Update(ctx context.Context, id string, p Patch, updatedBy stri
 		if err != nil {
 			return fmt.Errorf("dinners: update %s: %w", id, err)
 		}
-		regrounding = row.GroundingRevision != cur.GroundingRevision
+		renamed = row.GroundingRevision != cur.GroundingRevision
+		regrounding = renamed && cur.GroundingStatus == GroundingPending
 		return nil
 	})
 	if err != nil {
 		return Dinner{}, err
 	}
+	if renamed {
+		updateCommitted()
+		s.clearOffers(row.ID, row.GroundingRevision)
+	}
 	if regrounding {
 		s.stopGroundings(row.ID, row.GroundingRevision)
 		jobID, err := s.enqueueGrounding(ctx, row.ID, row.GroundingRevision)
@@ -384,7 +441,8 @@ func (s *Service) Update(ctx context.Context, id string, p Patch, updatedBy stri
 
 // Archive sets dinner id's status to archived, recording updatedBy. The row
 // is kept, so its name still counts for Side quest dedupe. A
-// KindGroundDinner job running for it is stopped.
+// KindGroundDinner job running for it is stopped, and its candidates no
+// longer ground it.
 func (s *Service) Archive(ctx context.Context, id, updatedBy string) (Dinner, error) {
 	if updatedBy == "" {
 		return Dinner{}, errors.New("dinners: archive: no member to record as updated_by")
@@ -401,6 +459,7 @@ func (s *Service) Archive(ctx context.Context, id, updatedBy string) (Dinner, er
 		return Dinner{}, fmt.Errorf("dinners: archive %s: %w", id, err)
 	}
 	s.stopGroundings(row.ID, math.MaxInt64)
+	s.clearOffers(row.ID, math.MaxInt64)
 	return fromRow(row), nil
 }
 

internal/dinners/dinners_test.go

@@ -16,8 +16,10 @@ import (
 func TestCreateRegularNeverNamesFromLink(t *testing.T) {
 	t.Parallel()
 	e := newUnstartedEnv(t)
-	const link = "https://c.example/stew-key-abcdefghijklmno?sig=zyxwvut#frag"
-	leaks := []string{"c.example", "key", "abcdefghijklmno", "sig", "zyxwvut", "frag"}
+	const link = "https://c.example/stew-key-abcdefghijklmno?sig=zyxwvut#lookup"
+	// Each leak holds a character no ULID has (Crockford base32 has no I, L,
+	// O, U, "-", "." or "/"), so a dinner's id never matches one.
+	leaks := []string{link, "c.example", "stew-key", "abcdefghijklmno", "sig", "zyxwvut", "lookup"}
 	check := func(what, text string) {
 		t.Helper()
 		lower := strings.ToLower(text)

internal/dinners/export_test.go

@@ -14,6 +14,56 @@ func SetGroundTimeout(t *testing.T, d time.Duration) {
 	t.Cleanup(func() { groundTimeout = old })
 }
 
+// SetOfferLifetime sets how long candidates ground a dinner until t ends.
+// A test calling it must not run in parallel.
+func SetOfferLifetime(t *testing.T, d time.Duration) {
+	old := offerLifetime
+	offerLifetime = d
+	t.Cleanup(func() { offerLifetime = old })
+}
+
+// SetUpdateCommitted runs f in Update once a rename is committed, before
+// the dinner's offers are cleared, until t ends. A test calling it must
+// not run in parallel.
+func SetUpdateCommitted(t *testing.T, f func()) {
+	old := updateCommitted
+	updateCommitted = f
+	t.Cleanup(func() { updateCommitted = old })
+}
+
+// AdvanceClock moves the service's clock d ahead of real time until t
+// ends, without firing any timer. A test calling it must not run in
+// parallel.
+func AdvanceClock(t *testing.T, d time.Duration) {
+	old := now
+	now = func() time.Time { return old().Add(d) }
+	t.Cleanup(func() { now = old })
+}
+
+// HasOffers reports whether the service holds candidates offered for
+// dinner id.
+func (s *Service) HasOffers(id string) bool {
+	s.offersMu.Lock()
+	defer s.offersMu.Unlock()
+	_, ok := s.offers[id]
+	return ok
+}
+
+// StoreOffers stores urls as dinner id's offers, as a Candidates search
+// that read the dinner at grounding_revision revision would on finishing.
+func (s *Service) StoreOffers(id string, urls map[string]string, revision int64) {
+	keep, done := s.trackOffers(id)
+	defer done()
+	keep(urls, revision)
+}
+
+// OfferCount is the number of dinners whose candidates the service holds.
+func (s *Service) OfferCount() int {
+	s.offersMu.Lock()
+	defer s.offersMu.Unlock()
+	return len(s.offers)
+}
+
 // RunGroundJob runs the KindGroundDinner handler for p in the caller's
 // goroutine, as the job runner would, and returns the grounding status it
 // reports.

internal/dinners/grounding.go

@@ -2,10 +2,14 @@ package dinners
 
 import (
 	"context"
+	"crypto/hmac"
+	"crypto/sha256"
 	"database/sql"
+	"encoding/base64"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"math"
 	"slices"
 	"strings"
 	"time"
@@ -81,6 +85,11 @@ var ErrGroundTimeout = errors.New("dinners: grounding the recipe took too long")
 // logged.
 var ErrGroundFailed = errors.New("dinners: grounding the recipe failed")
 
+// ErrCandidatesFailed wraps any unexpected failure finding a dinner's
+// candidates. Its text may quote a candidate's URL and dependency errors,
+// so it is never logged.
+var ErrCandidatesFailed = errors.New("dinners: finding recipe candidates failed")
+
 // ErrArchived is grounding an archived dinner by hand.
 var ErrArchived = errors.New("dinner archived")
 
@@ -282,7 +291,9 @@ func reasonFor(err error, fromURL bool) string {
 
 // Candidate is a recipe page offered to ground a dinner in.
 type Candidate struct {
-	// CandidateID is the page's URL; Fix.CandidateID grounds it.
+	// CandidateID is an opaque id for the page, resolved by the server:
+	// Fix.CandidateID grounds it. The page's URL is never returned, as it
+	// may carry a token.
 	CandidateID string `json:"candidate_id"`
 	Title       string `json:"title"`
 	SiteName    string `json:"site_name"`
@@ -291,29 +302,182 @@ type Candidate struct {
 	Minutes  *int    `json:"minutes"`
 }
 
+// offerLifetime is how long the candidates Candidates offers a dinner
+// ground it; tests shorten it.
+var offerLifetime = 30 * time.Minute
+
+// now is the clock offer lifetimes are measured on; tests advance it.
+var now = time.Now
+
+// updateCommitted runs in Update once a rename is committed, before the
+// dinner's offers are cleared; tests use it to act in between.
+var updateCommitted = func() {}
+
+// offerSet is the candidates last offered for a dinner: the page URL of
+// each candidate id, found by searching the dinner's name at its
+// grounding_revision revision. They ground the dinner until deadline, and
+// only while it is still at that revision, which every rename raises;
+// expiry drops the set from offers once deadline has passed.
+type offerSet struct {
+	urls     map[string]string
+	revision int64
+	deadline time.Time
+	expiry   *time.Timer
+}
+
+// offerSearch is a Candidates search running for a dinner. It stores no
+// offers found at a grounding_revision below below, which clearing the
+// dinner's offers raises.
+type offerSearch struct {
+	below int64
+}
+
 // Candidates searches for dinner id's name and returns up to MaxCandidates
-// recipe pages to ground it in, best first; the list may be empty. A
-// search that fails wraps recipes.ErrSearchFailed.
+// recipe pages to ground it in, best first; the list may be empty. They
+// replace the dinner's earlier candidates: one not offered again no longer
+// grounds it. They ground it for offerLifetime, and not at all once it is
+// grounded by hand, renamed or archived, even while this search runs. A
+// missing dinner is ErrNotFound; any other failure wraps
+// ErrCandidatesFailed, and a search that fails also wraps
+// recipes.ErrSearchFailed.
 func (s *Service) Candidates(ctx context.Context, id string) ([]Candidate, error) {
+	// Tracked before the dinner is read: grounding, renaming or archiving
+	// it after the read keeps this search from storing what it found.
+	keep, done := s.trackOffers(id)
+	defer done()
 	row, err := s.get(ctx, id)
-	if err != nil {
+	if errors.Is(err, ErrNotFound) {
 		return nil, err
 	}
+	if err != nil {
+		return nil, fmt.Errorf("%w: dinner %s: %w", ErrCandidatesFailed, id, err)
+	}
 	offers, err := s.grounder.Candidates(ctx, row.Name, row.Name, MaxCandidates)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("%w: dinner %s: %w", ErrCandidatesFailed, id, err)
 	}
 	out := make([]Candidate, len(offers))
+	urls := make(map[string]string, len(offers))
 	for i, o := range offers {
-		out[i] = Candidate{CandidateID: o.URL, Title: o.Title, SiteName: o.SiteName, Minutes: o.Minutes}
+		cid := s.candidateID(row.ID, o.URL)
+		urls[cid] = o.URL
+		out[i] = Candidate{CandidateID: cid, Title: o.Title, SiteName: o.SiteName, Minutes: o.Minutes}
 		if o.PhotoID != "" {
 			u := PhotoURL(o.PhotoID)
 			out[i].PhotoURL = &u
 		}
 	}
+	if row.Status != StatusArchived {
+		keep(urls, row.GroundingRevision)
+	}
 	return out, nil
 }
 
+// trackOffers registers a Candidates search for dinner id. It returns keep,
+// which stores urls, found for the dinner at grounding_revision revision,
+// as its offers for offerLifetime unless clearOffers has run for it since
+// with a revision above that, or offers found at a later revision are
+// stored, and done, to call when the search ends.
+func (s *Service) trackOffers(id string) (keep func(urls map[string]string, revision int64), done func()) {
+	search := &offerSearch{}
+	s.offersMu.Lock()
+	if s.offerSearches[id] == nil {
+		s.offerSearches[id] = make(map[*offerSearch]struct{})
+	}
+	s.offerSearches[id][search] = struct{}{}
+	s.offersMu.Unlock()
+	keep = func(urls map[string]string, revision int64) {
+		s.offersMu.Lock()
+		defer s.offersMu.Unlock()
+		if revision < search.below {
+			return
+		}
+		if set := s.offers[id]; set != nil && set.revision > revision {
+			// Found at a later revision, so the earlier search's offers
+			// are already stale.
+			return
+		}
+		s.dropOffers(id)
+		set := &offerSet{urls: urls, revision: revision, deadline: now().Add(offerLifetime)}
+		// expiry waits for offersMu, so it finds set stored even when it
+		// fires at once, and drops set only, never offers stored later.
+		set.expiry = time.AfterFunc(offerLifetime, func() {
+			s.offersMu.Lock()
+			defer s.offersMu.Unlock()
+			if s.offers[id] == set {
+				delete(s.offers, id)
+			}
+		})
+		s.offers[id] = set
+	}
+	done = func() {
+		s.offersMu.Lock()
+		delete(s.offerSearches[id], search)
+		if len(s.offerSearches[id]) == 0 {
+			delete(s.offerSearches, id)
+		}
+		s.offersMu.Unlock()
+	}
+	return keep, done
+}
+
+// clearOffers drops dinner id's offers found at a grounding_revision below
+// below and keeps every Candidates search running for it from storing
+// such offers, so none of them grounds it. Offers found at below or above
+// are kept. Call it with math.MaxInt64 once the dinner is grounded by hand
+// or archived, and with its new revision once it is renamed: a search
+// that read the rename meanwhile keeps its offers.
+func (s *Service) clearOffers(id string, below int64) {
+	s.offersMu.Lock()
+	defer s.offersMu.Unlock()
+	if set := s.offers[id]; set != nil && set.revision < below {
+		s.dropOffers(id)
+	}
+	for search := range s.offerSearches[id] {
+		search.below = max(search.below, below)
+	}
+}
+
+// dropOffers drops dinner id's offers and stops their expiry. The caller
+// holds offersMu.
+func (s *Service) dropOffers(id string) {
+	if set := s.offers[id]; set != nil {
+		set.expiry.Stop()
+		delete(s.offers, id)
+	}
+}
+
+// candidateID is the opaque id of the page at rawURL as a candidate for
+// dinner id: the same page is offered under the same id until the service
+// restarts, and the id reveals nothing of the URL.
+func (s *Service) candidateID(id, rawURL string) string {
+	mac := hmac.New(sha256.New, s.offerKey)
+	mac.Write([]byte(id + "\x00" + rawURL))
+	return base64.RawURLEncoding.EncodeToString(mac.Sum(nil)[:16])
+}
+
+// candidateURL is the page URL of candidate cid last offered for dinner d.
+// A cid not among the dinner's live offers, or whose page is not a valid
+// recipe link, is a *ValidationError. Offers past their deadline, or found
+// at a grounding_revision other than d's, are not live, even before they
+// are dropped: d was renamed since they were found, if only to its name
+// then.
+func (s *Service) candidateURL(d db.Dinner, cid string) (string, error) {
+	var raw string
+	var ok bool
+	s.offersMu.Lock()
+	if set := s.offers[d.ID]; set != nil && set.revision == d.GroundingRevision && now().Before(set.deadline) {
+		raw, ok = set.urls[cid]
+	}
+	s.offersMu.Unlock()
+	if ok {
+		if u, err := checkRecipeURL(raw); err == nil {
+			return u.String(), nil
+		}
+	}
+	return "", invalid("candidate_id", "is not a candidate from recipe-candidates; reload the candidates")
+}
+
 // Fix grounds a dinner by hand: exactly one of a candidate from
 // Candidates, a pasted recipe link or a recipe typed in.
 type Fix struct {
@@ -367,6 +531,11 @@ func (s *Service) Ground(ctx context.Context, id string, f Fix, updatedBy string
 	if cur.Status == StatusArchived {
 		return Dinner{}, ErrArchived
 	}
+	if f.CandidateID != nil {
+		if link, err = s.candidateURL(cur, *f.CandidateID); err != nil {
+			return Dinner{}, err
+		}
+	}
 	groundCtx, cancel := context.WithTimeout(ctx, groundTimeout)
 	defer cancel()
 	gr, err := s.grounder.GroundURL(groundCtx, link)
@@ -401,6 +570,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.clearOffers(cur.ID, math.MaxInt64)
 	return fromRow(row), nil
 }
 
@@ -422,9 +592,10 @@ func (s *Service) groundRejected(ctx context.Context, id string) error {
 }
 
 // groundManual stores m as dinner id's recipe, with its ingredients and
-// steps, and records it on the dinner, all in one transaction. A missing
-// or archived dinner is ErrNotFound or ErrArchived; any other failure
-// wraps ErrGroundFailed.
+// steps, and records it on the dinner, all in one transaction; the
+// dinner's candidates then no longer ground it. A missing or archived
+// dinner is ErrNotFound or ErrArchived; any other failure wraps
+// ErrGroundFailed.
 func (s *Service) groundManual(ctx context.Context, id string, m ManualRecipe, updatedBy string) (Dinner, error) {
 	var row db.Dinner
 	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
@@ -522,6 +693,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.clearOffers(row.ID, math.MaxInt64)
 	return fromRow(row), nil
 }
 
@@ -550,11 +722,8 @@ func (f Fix) validate() (link string, manual *ManualRecipe, err error) {
 	}
 	switch {
 	case f.CandidateID != nil:
-		u, err := checkRecipeURL(*f.CandidateID)
-		if err != nil {
-			return "", nil, invalid("candidate_id", "is not a candidate from recipe-candidates")
-		}
-		return u.String(), nil, nil
+		// Ground resolves the candidate to its page.
+		return "", nil, nil
 	case f.RecipeURL != nil:
 		u, err := checkRecipeURL(*f.RecipeURL)
 		if err != nil {

internal/dinners/grounding_test.go

@@ -9,6 +9,7 @@ import (
 	"io/fs"
 	"log/slog"
 	"slices"
+	"strings"
 	"testing"
 	"testing/fstest"
 	"time"
@@ -214,6 +215,39 @@ func TestCreateByRecipeURLGroundsThatURL(t *testing.T) {
 	}
 }
 
+// TestCreateByRecipeURLClearsLink: once background grounding resolves a
+// pasted link, which may carry a personal token, the dinner no longer
+// stores it; the recipe it grounded in records the page.
+func TestCreateByRecipeURLClearsLink(t *testing.T) {
+	t.Parallel()
+	e := newEnv(t)
+	const link = "https://c.example/recipes/beef-stew?access_token=personal-token-abc123"
+	e.pages.Bodies[link] = recipestest.RecipePage("Beef Stew", "Stew Co", "https://c.example/stew.jpg", 150)
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+
+	c, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Beef stew"), RecipeURL: ptr(link)}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if job := e.waitJob(t, *c.GroundingJobID); job.Status != jobs.StatusSucceeded {
+		t.Fatalf("job = %+v", job)
+	}
+	row := e.dinner(t, c.ID)
+	if row.GroundingStatus != "grounded" || !row.RecipeID.Valid {
+		t.Fatalf("dinner = %+v, want grounded", row)
+	}
+	if row.RecipeUrl.Valid {
+		t.Errorf("recipe_url = %q after grounding, want cleared", row.RecipeUrl.String)
+	}
+	rec, err := db.New(e.st.Reader).GetRecipe(t.Context(), row.RecipeID.String)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rec.SourceUrl != link {
+		t.Errorf("recipe source = %q, want %q", rec.SourceUrl, link)
+	}
+}
+
 func TestCreateGroundingFailureRecordsReason(t *testing.T) {
 	t.Parallel()
 	tests := []struct {
@@ -642,6 +676,26 @@ func failedDinner(t *testing.T, e *env, name string) string {
 	return c.ID
 }
 
+// candidateID returns the candidate_id Candidates offers dinner id for the
+// page titled title.
+func candidateID(t *testing.T, e *env, id, title string) string {
+	t.Helper()
+	got, err := e.svc.Candidates(t.Context(), id)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range got {
+		if c.Title == title {
+			if strings.Contains(c.CandidateID, "://") {
+				t.Fatalf("candidate_id = %q, want an opaque id, not the page URL", c.CandidateID)
+			}
+			return c.CandidateID
+		}
+	}
+	t.Fatalf("candidates = %+v, want one titled %q", got, title)
+	return ""
+}
+
 func TestCandidates(t *testing.T) {
 	t.Parallel()
 	e := newEnv(t)
@@ -664,14 +718,25 @@ func TestCandidates(t *testing.T) {
 	}
 	first, second := got[0], got[1]
 	wantPhoto := dinners.PhotoURL(e.dinner(t, c.ID).PhotoID.String)
-	if first.CandidateID != curryA || first.Title != "Chicken Curry" || first.SiteName != "Curry House" ||
+	if first.Title != "Chicken Curry" || first.SiteName != "Curry House" ||
 		first.PhotoURL == nil || *first.PhotoURL != wantPhoto || first.Minutes == nil || *first.Minutes != 40 {
 		t.Errorf("first = %+v, want the stored curryA with photo %s", first, wantPhoto)
 	}
-	if second.CandidateID != curryB || second.Title != "Easy Weeknight Curry" || second.SiteName != "B Kitchen" ||
+	if second.Title != "Easy Weeknight Curry" || second.SiteName != "B Kitchen" ||
 		second.PhotoURL != nil || second.Minutes == nil || *second.Minutes != 25 {
 		t.Errorf("second = %+v, want curryB without a photo", second)
 	}
+	if first.CandidateID == "" || first.CandidateID == second.CandidateID ||
+		first.CandidateID == curryA || second.CandidateID == curryB {
+		t.Errorf("candidate ids = %q, %q, want distinct opaque ids", first.CandidateID, second.CandidateID)
+	}
+	again, err := e.svc.Candidates(t.Context(), c.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(again) != 2 || again[0].CandidateID != first.CandidateID || again[1].CandidateID != second.CandidateID {
+		t.Errorf("candidates again = %+v, want the same ids", again)
+	}
 
 	if _, err := e.svc.Candidates(t.Context(), "nope"); !errors.Is(err, dinners.ErrNotFound) {
 		t.Errorf("unknown dinner: err = %v, want ErrNotFound", err)
@@ -702,9 +767,11 @@ func TestFixViaCandidate(t *testing.T) {
 	t.Parallel()
 	e := newEnv(t)
 	id := failedDinner(t, e, "Mystery curry")
+	e.search.Results["Mystery curry"] = []recipes.Candidate{{URL: curryA}, {URL: curryB}}
+	cid := candidateID(t, e, id, "Easy Weeknight Curry")
 	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
 
-	d, err := e.svc.Ground(t.Context(), id, dinners.Fix{CandidateID: ptr(curryB)}, "member-2")
+	d, err := e.svc.Ground(t.Context(), id, dinners.Fix{CandidateID: ptr(cid)}, "member-2")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -721,6 +788,435 @@ func TestFixViaCandidate(t *testing.T) {
 	}
 }
 
+// wantStaleCandidate checks that candidate cid no longer grounds dinner
+// id: Ground refuses it as invalid, and the dinner is unchanged.
+func wantStaleCandidate(t *testing.T, e *env, id, cid string) {
+	t.Helper()
+	before := e.dinner(t, id)
+	_, err := e.svc.Ground(t.Context(), id, dinners.Fix{CandidateID: ptr(cid)}, member)
+	var invalid *dinners.ValidationError
+	if !errors.As(err, &invalid) {
+		t.Fatalf("stale candidate: err = %v, want *ValidationError", err)
+	}
+	if after := e.dinner(t, id); after != before {
+		t.Errorf("dinner changed by a stale candidate: %+v, was %+v", after, before)
+	}
+}
+
+// TestGroundingOrArchivingClearsCandidates: once a dinner is grounded by
+// hand — by candidate, link or manual recipe — renamed or archived, the
+// service holds none of its candidates' URLs and none of them grounds it.
+func TestGroundingOrArchivingClearsCandidates(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name string
+		// clear grounds or archives dinner id, offered candidate cid.
+		clear func(t *testing.T, e *env, id, cid string)
+		// archived says the dinner ends archived, which Ground refuses
+		// before it reads a candidate.
+		archived bool
+	}{
+		{"candidate", func(t *testing.T, e *env, id, cid string) {
+			e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+			if _, err := e.svc.Ground(t.Context(), id, dinners.Fix{CandidateID: ptr(cid)}, member); err != nil {
+				t.Fatal(err)
+			}
+		}, false},
+		{"link", func(t *testing.T, e *env, id, _ string) {
+			e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+			if _, err := e.svc.Ground(t.Context(), id, dinners.Fix{RecipeURL: ptr(stew)}, member); err != nil {
+				t.Fatal(err)
+			}
+		}, false},
+		{"manual", func(t *testing.T, e *env, id, _ string) {
+			m := &dinners.ManualRecipe{Ingredients: []string{"1 chicken"}, Minutes: ptr(40), Method: ptr("stovetop")}
+			if _, err := e.svc.Ground(t.Context(), id, dinners.Fix{Manual: m}, member); err != nil {
+				t.Fatal(err)
+			}
+		}, false},
+		{"rename", func(t *testing.T, e *env, id, _ string) {
+			if _, err := e.svc.Update(t.Context(), id, dinners.Patch{Name: ptr("Beef stew")}, member); err != nil {
+				t.Fatal(err)
+			}
+		}, false},
+		{"archive", func(t *testing.T, e *env, id, _ string) {
+			if _, err := e.svc.Archive(t.Context(), id, member); err != nil {
+				t.Fatal(err)
+			}
+		}, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			e := newEnv(t)
+			id := failedDinner(t, e, "Mystery curry")
+			e.search.Results["Mystery curry"] = []recipes.Candidate{{URL: curryA}, {URL: curryB}}
+			cidA := candidateID(t, e, id, "Chicken Curry")
+			cidB := candidateID(t, e, id, "Easy Weeknight Curry")
+
+			tt.clear(t, e, id, cidA)
+			if e.svc.HasOffers(id) {
+				t.Errorf("service still holds the candidates of dinner %s", id)
+			}
+			if !tt.archived {
+				wantStaleCandidate(t, e, id, cidB)
+			}
+		})
+	}
+}
+
+// TestRenamePendingRefusesOldCandidates: candidates offered for a pending
+// dinner's old name no longer ground it once it is renamed — Ground refuses
+// them and leaves the old recipe off it — while candidates for the new name
+// do.
+func TestRenamePendingRefusesOldCandidates(t *testing.T) {
+	t.Parallel()
+	// Unstarted, so the dinner stays pending with its jobs queued.
+	e := newUnstartedEnv(t)
+	e.search.Results["Beef stew"] = []recipes.Candidate{{URL: stew}}
+	c, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Chicken curry")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	old := candidateID(t, e, c.ID, "Chicken Curry")
+
+	d, err := e.svc.Update(t.Context(), c.ID, dinners.Patch{Name: ptr("Beef stew")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.GroundingStatus != dinners.GroundingPending {
+		t.Fatalf("renamed = %+v, want still pending", d)
+	}
+	if e.svc.HasOffers(c.ID) {
+		t.Errorf("service still holds the old name's candidates of dinner %s", c.ID)
+	}
+	wantStaleCandidate(t, e, c.ID, old)
+	if row := e.dinner(t, c.ID); row.RecipeID.Valid || row.GroundingStatus != dinners.GroundingPending {
+		t.Fatalf("dinner = %+v, want pending with no recipe", row)
+	}
+
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+	g, err := e.svc.Ground(t.Context(), c.ID, dinners.Fix{CandidateID: ptr(candidateID(t, e, c.ID, "Beef Stew"))}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if g.GroundingStatus != dinners.GroundingGrounded || g.RecipeID == nil {
+		t.Fatalf("dinner = %+v, want grounded for the new name", g)
+	}
+	rec, err := db.New(e.st.Reader).GetRecipe(t.Context(), *g.RecipeID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rec.SourceUrl != stew {
+		t.Errorf("recipe source = %s, want %s", rec.SourceUrl, stew)
+	}
+}
+
+// TestRenameSameNormalizedNameRefusesOldCandidates: a rename that leaves
+// the normalized name as it was still drops the candidates offered before
+// it, and none of them grounds the dinner.
+func TestRenameSameNormalizedNameRefusesOldCandidates(t *testing.T) {
+	t.Parallel()
+	// Unstarted, so the dinner stays pending with its jobs queued.
+	e := newUnstartedEnv(t)
+	e.search.Results["Quick Chicken curry"] = e.search.Results["Chicken curry"]
+	c, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Chicken curry")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	old := candidateID(t, e, c.ID, "Chicken Curry")
+	before := e.dinner(t, c.ID)
+
+	d, err := e.svc.Update(t.Context(), c.ID, dinners.Patch{Name: ptr("Quick Chicken curry")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if e.svc.HasOffers(c.ID) {
+		t.Errorf("service still holds the candidates offered before dinner %s was renamed", c.ID)
+	}
+	// A reply is queued, so only refusing the candidate keeps its recipe off.
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+	wantStaleCandidate(t, e, c.ID, old)
+	row := e.dinner(t, c.ID)
+	if row.RecipeID.Valid {
+		t.Fatalf("dinner = %+v, want no recipe", row)
+	}
+	if row.NormalizedName != before.NormalizedName {
+		t.Fatalf("normalized name = %q, want %q unchanged", row.NormalizedName, before.NormalizedName)
+	}
+	// Still pending, now at the rename's revision, with a job for it.
+	if d.GroundingStatus != dinners.GroundingPending || row.GroundingRevision != before.GroundingRevision+1 {
+		t.Fatalf("renamed = %+v, want pending at revision %d", row, before.GroundingRevision+1)
+	}
+	var queued int
+	if err := e.st.Reader.QueryRowContext(t.Context(),
+		`SELECT count(*) FROM jobs WHERE status = 'queued' AND json_extract(payload, '$.revision') = ?`,
+		row.GroundingRevision).Scan(&queued); err != nil {
+		t.Fatal(err)
+	}
+	if queued != 1 {
+		t.Fatalf("queued jobs at revision %d = %d, want 1", row.GroundingRevision, queued)
+	}
+}
+
+// TestCandidatesBetweenRenameAndClearKept: a candidate search that reads
+// a dinner after its rename commits, and stores its candidates before the
+// rename clears the dinner's offers, keeps them: they ground the renamed
+// dinner, while one offered before the rename does not, even when a search
+// that read the dinner before the rename finishes after them.
+func TestCandidatesBetweenRenameAndClearKept(t *testing.T) {
+	// Unstarted, so the dinner stays pending with its jobs queued.
+	e := newUnstartedEnv(t)
+	e.search.Results["Beef stew"] = []recipes.Candidate{{URL: stew}}
+	c, err := e.svc.CreateRegular(t.Context(), dinners.NewRegular{Name: ptr("Chicken curry")}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	old := candidateID(t, e, c.ID, "Chicken Curry")
+	before := e.dinner(t, c.ID)
+
+	var fresh string
+	dinners.SetUpdateCommitted(t, func() {
+		fresh = candidateID(t, e, c.ID, "Beef Stew")
+		e.svc.StoreOffers(c.ID, map[string]string{old: curryA}, before.GroundingRevision)
+	})
+	if _, err := e.svc.Update(t.Context(), c.ID, dinners.Patch{Name: ptr("Beef stew")}, member); err != nil {
+		t.Fatal(err)
+	}
+	if fresh == "" {
+		t.Fatal("no candidate search ran between the rename and clearing offers")
+	}
+	if !e.svc.HasOffers(c.ID) {
+		t.Fatalf("clearing offers after the rename dropped the candidates found at its revision for dinner %s", c.ID)
+	}
+	wantStaleCandidate(t, e, c.ID, old)
+
+	e.model.QueueGenerate(recipestest.NormalizedReply("oven", 150))
+	g, err := e.svc.Ground(t.Context(), c.ID, dinners.Fix{CandidateID: ptr(fresh)}, member)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if g.GroundingStatus != dinners.GroundingGrounded || g.RecipeID == nil {
+		t.Fatalf("dinner = %+v, want grounded for the new name", g)
+	}
+	rec, err := db.New(e.st.Reader).GetRecipe(t.Context(), *g.RecipeID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rec.SourceUrl != stew {
+		t.Errorf("recipe source = %s, want %s", rec.SourceUrl, stew)
+	}
+}
+
+// TestRenameBackDuringCandidatesRefusesThem: a candidate search that read
+// a dinner as A and finishes after renames A -> B -> A have committed, but
+// before either has cleared the dinner's offers, stores candidates that
+// do not ground it, though its name is A again.
+func TestRenameBackDuringCandidatesRefusesThem(t *testing.T) {
+	e := newEnv(t)
+	id := failedDinner(t, e, "Mystery curry")
+	e.search.Results["Mystery curry"] = []recipes.Candidate{{URL: curryA}}
+	asked := len(e.search.Queries())
+	gate := make(chan struct{})
+	e.search.Gate = gate
+
+	type result struct {
+		got []dinners.Candidate
+		err error
+	}
+	done := make(chan result, 1)
+	go func() {
+		got, err := e.svc.Candidates(t.Context(), id)
+		done <- result{got, err}
+	}()
+	deadline := time.Now().Add(10 * time.Second)
+	for len(e.search.Queries()) == asked {
+		if time.Now().After(deadline) {
+			t.Fatal("candidate search never started")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	// The first rename's hook makes the second; the second's lets the
+	// search finish and tries its candidate, before either clears offers.
+	var hooks int
+	var stale error
+	var groundedBy *dinners.Dinner
+	dinners.SetUpdateCommitted(t, func() {
+		hooks++
+		switch hooks {
+		case 1:
+			if _, err := e.svc.Update(t.Context(), id, dinners.Patch{Name: ptr("Mystery curry")}, member); err != nil {
+				t.Error(err)
+			}
+		case 2:
+			close(gate)
+			r := <-done
+			if r.err != nil || len(r.got) != 1 {
+				t.Errorf("candidates = %+v, %v; want curryA", r.got, r.err)
+				return
+			}
+			e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 40))
+			d, err := e.svc.Ground(t.Context(), id, dinners.Fix{CandidateID: ptr(r.got[0].CandidateID)}, member)
+			if err == nil {
+				groundedBy = &d
+			}
+			stale = err
+		}
+	})
+	if _, err := e.svc.Update(t.Context(), id, dinners.Patch{Name: ptr("Beef stew")}, member); err != nil {
+		t.Fatal(err)
+	}
+	if hooks != 2 {
+		t.Fatalf("renames committed = %d, want 2", hooks)
+	}
+	var invalid *dinners.ValidationError
+	if !errors.As(stale, &invalid) {
+		t.Fatalf("stale candidate: err = %v, grounded %+v; want *ValidationError", stale, groundedBy)
+	}
+	row := e.dinner(t, id)
+	if row.Name != "Mystery curry" || row.RecipeID.Valid || row.GroundingStatus != dinners.GroundingFailed {
+		t.Errorf("dinner = %+v, want Mystery curry still failed with no recipe", row)
+	}
+	if e.svc.HasOffers(id) {
+		t.Errorf("service still holds the stale candidates of dinner %s", id)
+	}
+}
+
+// TestCandidatesRunningWhenCleared: a candidate search still running when
+// its dinner is grounded by hand, renamed or archived stores none of the
+// candidates it returns, so none of them grounds the dinner.
+func TestCandidatesRunningWhenCleared(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name  string
+		clear func(t *testing.T, e *env, id string)
+		// archived says the dinner ends archived.
+		archived bool
+	}{
+		{"manual", func(t *testing.T, e *env, id string) {
+			m := &dinners.ManualRecipe{Ingredients: []string{"1 chicken"}, Minutes: ptr(40), Method: ptr("stovetop")}
+			if _, err := e.svc.Ground(t.Context(), id, dinners.Fix{Manual: m}, member); err != nil {
+				t.Fatal(err)
+			}
+		}, false},
+		{"rename", func(t *testing.T, e *env, id string) {
+			if _, err := e.svc.Update(t.Context(), id, dinners.Patch{Name: ptr("Beef stew")}, member); err != nil {
+				t.Fatal(err)
+			}
+		}, false},
+		{"archive", func(t *testing.T, e *env, id string) {
+			if _, err := e.svc.Archive(t.Context(), id, member); err != nil {
+				t.Fatal(err)
+			}
+		}, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			e := newEnv(t)
+			id := failedDinner(t, e, "Mystery curry")
+			e.search.Results["Mystery curry"] = []recipes.Candidate{{URL: curryA}}
+			asked := len(e.search.Queries())
+			gate := make(chan struct{})
+			e.search.Gate = gate
+
+			type result struct {
+				got []dinners.Candidate
+				err error
+			}
+			done := make(chan result, 1)
+			go func() {
+				got, err := e.svc.Candidates(t.Context(), id)
+				done <- result{got, err}
+			}()
+			deadline := time.Now().Add(10 * time.Second)
+			for len(e.search.Queries()) == asked {
+				if time.Now().After(deadline) {
+					t.Fatal("candidate search never started")
+				}
+				time.Sleep(5 * time.Millisecond)
+			}
+			tt.clear(t, e, id)
+			close(gate)
+			r := <-done
+			if r.err != nil {
+				t.Fatal(r.err)
+			}
+			if len(r.got) != 1 {
+				t.Fatalf("candidates = %+v, want curryA", r.got)
+			}
+			if e.svc.HasOffers(id) {
+				t.Errorf("a search finishing after dinner %s was cleared stored its candidates", id)
+			}
+			if !tt.archived {
+				wantStaleCandidate(t, e, id, r.got[0].CandidateID)
+			}
+		})
+	}
+}
+
+// TestCandidatesExpire: once their lifetime passes, a dinner's candidates
+// are dropped and no longer ground it, with no other search running.
+func TestCandidatesExpire(t *testing.T) {
+	dinners.SetOfferLifetime(t, 0)
+	e := newEnv(t)
+	id := failedDinner(t, e, "Mystery curry")
+	e.search.Results["Mystery curry"] = []recipes.Candidate{{URL: curryA}}
+	cid := candidateID(t, e, id, "Chicken Curry")
+
+	waitNoOffers(t, e)
+	wantStaleCandidate(t, e, id, cid)
+}
+
+// TestCandidatesExpireBeforeEviction: once their lifetime passes, a
+// dinner's candidates no longer ground it, even while the service still
+// holds them because their eviction has not run yet.
+func TestCandidatesExpireBeforeEviction(t *testing.T) {
+	dinners.SetOfferLifetime(t, time.Hour)
+	e := newEnv(t)
+	id := failedDinner(t, e, "Mystery curry")
+	e.search.Results["Mystery curry"] = []recipes.Candidate{{URL: curryA}}
+	cid := candidateID(t, e, id, "Chicken Curry")
+
+	dinners.AdvanceClock(t, time.Hour)
+	if !e.svc.HasOffers(id) {
+		t.Fatal("candidates evicted already, want them held until their timer fires")
+	}
+	wantStaleCandidate(t, e, id, cid)
+}
+
+// TestExpiredCandidatesNotHeld: the service holds no dinner's candidates
+// past their lifetime, however many dinners were offered some.
+func TestExpiredCandidatesNotHeld(t *testing.T) {
+	dinners.SetOfferLifetime(t, 50*time.Millisecond)
+	e := newEnv(t)
+	names := map[string]string{"Mystery curry": curryA, "Other curry": curryB}
+	ids := make([]string, 0, len(names))
+	for name, u := range names {
+		ids = append(ids, failedDinner(t, e, name))
+		e.search.Results[name] = []recipes.Candidate{{URL: u}}
+	}
+	for _, id := range ids {
+		if _, err := e.svc.Candidates(t.Context(), id); err != nil {
+			t.Fatal(err)
+		}
+	}
+	waitNoOffers(t, e)
+}
+
+// waitNoOffers waits for the service to hold no dinner's candidates.
+func waitNoOffers(t *testing.T, e *env) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for n := e.svc.OfferCount(); n > 0; n = e.svc.OfferCount() {
+		if time.Now().After(deadline) {
+			t.Fatalf("service still holds the expired candidates of %d dinners", n)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
 // TestFixReplacesPendingLink: fixing a Regular added from a link that held
 // no recipe drops that link, so it no longer blocks adding the link again,
 // while the link of the recipe chosen does.
@@ -729,12 +1225,18 @@ func TestFixReplacesPendingLink(t *testing.T) {
 	const lost = "https://gone.example/recipes/lamb-tagine"
 	tests := []struct {
 		name string
-		fix  dinners.Fix
+		// fix is the fix for dinner id.
+		fix func(t *testing.T, e *env, id string) dinners.Fix
 		// linkTaken is the recipe link the fixed dinner now has, if any.
 		linkTaken string
 	}{
-		{"candidate", dinners.Fix{CandidateID: ptr(curryB)}, curryB},
-		{"manual", dinners.Fix{Manual: &dinners.ManualRecipe{Ingredients: []string{"1 lamb"}, Minutes: ptr(90), Method: ptr("oven")}}, ""},
+		{"candidate", func(t *testing.T, e *env, id string) dinners.Fix {
+			e.search.Results["Weeknight dinner"] = []recipes.Candidate{{URL: curryB}}
+			return dinners.Fix{CandidateID: ptr(candidateID(t, e, id, "Easy Weeknight Curry"))}
+		}, curryB},
+		{"manual", func(*testing.T, *env, string) dinners.Fix {
+			return dinners.Fix{Manual: &dinners.ManualRecipe{Ingredients: []string{"1 lamb"}, Minutes: ptr(90), Method: ptr("oven")}}
+		}, ""},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -752,7 +1254,7 @@ func TestFixReplacesPendingLink(t *testing.T) {
 				t.Fatal(err)
 			}
 			e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
-			if _, err := e.svc.Ground(t.Context(), c.ID, tt.fix, member); err != nil {
+			if _, err := e.svc.Ground(t.Context(), c.ID, tt.fix(t, e, c.ID), member); err != nil {
 				t.Fatal(err)
 			}
 			row, err := db.New(e.st.Reader).GetDinner(t.Context(), c.ID)
@@ -855,7 +1357,8 @@ func TestFixValidation(t *testing.T) {
 	tests := map[string]dinners.Fix{
 		"nothing":           {},
 		"two":               {CandidateID: ptr(curryA), RecipeURL: ptr(stew)},
-		"candidate not URL": {CandidateID: ptr("cand-1")},
+		"unknown candidate": {CandidateID: ptr("cand-1")},
+		"candidate a URL":   {CandidateID: ptr(curryA)},
 		"http link":         {RecipeURL: ptr("http://a.example/x")},
 		"no ingredients":    {Manual: &dinners.ManualRecipe{Minutes: ptr(20), Method: ptr("oven")}},
 		"blank ingredient":  {Manual: &dinners.ManualRecipe{Ingredients: []string{" "}, Minutes: ptr(20), Method: ptr("oven")}},

internal/jobs/jobs.go

@@ -54,14 +54,30 @@ const (
 	CodeUnknownKind = "unknown_kind"
 )
 
-// Claim retry backoff. A worker whose claim fails with a database error
-// retries after claimRetryMin, doubling up to claimRetryMax, so a job queued
-// when the error clears is claimed without waiting for a wake token.
+// Retry backoff. A worker whose claim or final job write fails with a
+// database error retries after retryMin, doubling up to retryMax, so a job
+// queued when the error clears is claimed without waiting for a wake token,
+// and a job the worker has finished is never left running.
 const (
-	claimRetryMin = 50 * time.Millisecond
-	claimRetryMax = 5 * time.Second
+	retryMin = 50 * time.Millisecond
+	retryMax = 5 * time.Second
 )
 
+// FinalWriteTimeout bounds each attempt at a job's final write, and at a
+// handler's own last write, so a writer connection that stays busy cannot
+// hold a stopping worker, and with it shutdown, open.
+const FinalWriteTimeout = 5 * time.Second
+
+// FinalWriteContext returns the context for one attempt at a final write
+// of a job: it is not cancelled with ctx, so a job that finishes during
+// shutdown is still recorded, but it ends after FinalWriteTimeout. A
+// handler makes its own last write, the one recording what the job did,
+// with it too, and returns the error when the attempt times out, so its
+// worker can stop; the next Start fails the job as interrupted.
+func FinalWriteContext(ctx context.Context) (context.Context, context.CancelFunc) {
+	return context.WithTimeout(context.WithoutCancel(ctx), FinalWriteTimeout)
+}
+
 // codePattern is the form of every failure code: lower-case snake case.
 var codePattern = regexp.MustCompile(`^[a-z][a-z0-9_]{0,63}$`)
 
@@ -72,6 +88,10 @@ var ErrNotFound = errors.New("jobs: job not found")
 // registered handler.
 var ErrUnknownKind = errors.New("jobs: unknown job kind")
 
+// ErrServiceOnly is returned by Runner.Enqueue for a kind made ServiceOnly,
+// whose jobs only its own service enqueues.
+var ErrServiceOnly = errors.New("jobs: job kind is enqueued only by its service")
+
 // ErrInvalidPayload is returned by Runner.Enqueue for a payload that does
 // not decode into the kind's payload type.
 var ErrInvalidPayload = errors.New("jobs: payload does not decode")
@@ -114,11 +134,13 @@ type Job struct {
 // never quotes an error.
 type runFunc func(ctx context.Context, payload string, publish func(json.RawMessage) error) (result json.RawMessage, code, reason string)
 
-// handler is a registered kind: run runs a job, and check reports whether
-// a payload decodes into the kind's payload type.
+// handler is a registered kind: run runs a job, check reports whether a
+// payload decodes into the kind's payload type, and serviceOnly is set when
+// Runner.Enqueue refuses the kind.
 type handler struct {
-	run   runFunc
-	check func(payload []byte) bool
+	run         runFunc
+	check       func(payload []byte) bool
+	serviceOnly bool
 }
 
 // Runner owns the job handlers and the worker pool.
@@ -259,11 +281,41 @@ func (k *Kind[P]) Enqueue(ctx context.Context, payload P) (string, error) {
 	return k.r.enqueue(ctx, k.name, data)
 }
 
+// EnqueueTx stores a queued job with payload in tx and returns its id, so
+// the job exists exactly when what else tx writes does. Once tx has
+// committed, call Wake so an idle worker runs it.
+func (k *Kind[P]) EnqueueTx(ctx context.Context, tx *sql.Tx, payload P) (string, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("jobs: enqueue %s: encode payload: %w", k.name, err)
+	}
+	return createJob(ctx, db.New(tx), k.name, data)
+}
+
+// ServiceOnly makes Runner.Enqueue refuse the kind with ErrServiceOnly, so
+// its jobs are enqueued only through k, by the service that checks what
+// must hold before one starts. It must be called before Start.
+func (k *Kind[P]) ServiceOnly() error {
+	k.r.mu.Lock()
+	defer k.r.mu.Unlock()
+	if k.r.started {
+		return fmt.Errorf("jobs: service-only %q: runner already started", k.name)
+	}
+	h := k.r.handlers[k.name]
+	h.serviceOnly = true
+	k.r.handlers[k.name] = h
+	return nil
+}
+
+// Wake tells an idle worker to look for a job, as Enqueue does itself:
+// call it after committing the transaction a job was enqueued in.
+func (k *Kind[P]) Wake() { k.r.wakeOne() }
+
 // Enqueue stores a queued job of kind with its JSON payload and returns its
 // id, as Kind.Enqueue does for a kind known at compile time. It returns
-// ErrUnknownKind for a kind with no registered handler and
-// ErrInvalidPayload for a payload that does not decode into the kind's
-// payload type; neither stores a job.
+// ErrUnknownKind for a kind with no registered handler, ErrServiceOnly for
+// a ServiceOnly kind and ErrInvalidPayload for a payload that does not
+// decode into the kind's payload type; none stores a job.
 func (r *Runner) Enqueue(ctx context.Context, kind string, payload json.RawMessage) (string, error) {
 	r.mu.Lock()
 	h, ok := r.handlers[kind]
@@ -271,6 +323,9 @@ func (r *Runner) Enqueue(ctx context.Context, kind string, payload json.RawMessa
 	if !ok {
 		return "", ErrUnknownKind
 	}
+	if h.serviceOnly {
+		return "", ErrServiceOnly
+	}
 	if !h.check(payload) {
 		return "", ErrInvalidPayload
 	}
@@ -280,9 +335,20 @@ func (r *Runner) Enqueue(ctx context.Context, kind string, payload json.RawMessa
 // enqueue stores a queued job of kind with its encoded payload and wakes a
 // worker.
 func (r *Runner) enqueue(ctx context.Context, kind string, payload []byte) (string, error) {
+	id, err := createJob(ctx, db.New(r.st.Writer), kind, payload)
+	if err != nil {
+		return "", err
+	}
+	r.wakeOne()
+	return id, nil
+}
+
+// createJob stores a queued job of kind with its encoded payload through q
+// and returns its id.
+func createJob(ctx context.Context, q *db.Queries, kind string, payload []byte) (string, error) {
 	id := store.NewID()
 	now := store.Now().String()
-	if err := db.New(r.st.Writer).CreateJob(ctx, db.CreateJobParams{
+	if err := q.CreateJob(ctx, db.CreateJobParams{
 		ID:        id,
 		Kind:      kind,
 		Payload:   string(payload),
@@ -291,11 +357,15 @@ func (r *Runner) enqueue(ctx context.Context, kind string, payload []byte) (stri
 	}); err != nil {
 		return "", fmt.Errorf("jobs: enqueue %s: %w", kind, err)
 	}
+	return id, nil
+}
+
+// wakeOne gives an idle worker a token to look for a queued job.
+func (r *Runner) wakeOne() {
 	select {
 	case r.wake <- struct{}{}:
 	default: // every worker already has a token and will look again
 	}
-	return id, nil
 }
 
 // Start fails every job a previous process left running with
@@ -357,16 +427,16 @@ func (r *Runner) Get(ctx context.Context, id string) (Job, error) {
 // already queued is not stranded by a transient error.
 func (r *Runner) work(ctx context.Context) {
 	defer r.wg.Done()
-	backoff := claimRetryMin
+	backoff := retryMin
 	for ctx.Err() == nil {
 		job, err := r.claim(ctx, sql.NullString{String: store.Now().String(), Valid: true})
 		switch {
 		case err == nil:
-			backoff = claimRetryMin
+			backoff = retryMin
 			r.run(ctx, job)
 			continue
 		case errors.Is(err, sql.ErrNoRows):
-			backoff = claimRetryMin
+			backoff = retryMin
 			select {
 			case <-r.wake:
 			case <-ctx.Done():
@@ -382,7 +452,7 @@ func (r *Runner) work(ctx context.Context) {
 		case <-ctx.Done():
 			timer.Stop()
 		}
-		backoff = min(2*backoff, claimRetryMax)
+		backoff = min(2*backoff, retryMax)
 	}
 }
 
@@ -390,14 +460,13 @@ func (r *Runner) work(ctx context.Context) {
 // ctx has been cancelled, so a handler that finishes during shutdown is
 // recorded.
 func (r *Runner) run(ctx context.Context, job db.Job) {
-	write := context.WithoutCancel(ctx)
 	logger := r.logger.With("job_id", job.ID, "kind", job.Kind)
 	q := db.New(r.st.Writer)
 
 	h, ok := r.handlers[job.Kind] // read-only once started
 	if !ok {
 		logger.ErrorContext(ctx, "job failed", "code", CodeUnknownKind, "reason", "no handler registered for the kind")
-		r.fail(write, logger, job.ID, CodeUnknownKind)
+		r.fail(ctx, logger, job.ID, CodeUnknownKind)
 		return
 	}
 
@@ -419,7 +488,7 @@ func (r *Runner) run(ctx context.Context, job db.Job) {
 	result, code, reason := h.run(ctx, job.Payload, publish)
 	if code != "" {
 		if ctx.Err() != nil {
-			logger.WarnContext(write, "job interrupted by shutdown; it fails at the next start")
+			logger.WarnContext(context.WithoutCancel(ctx), "job interrupted by shutdown; it fails at the next start")
 			return
 		}
 		level := slog.LevelInfo
@@ -427,35 +496,61 @@ func (r *Runner) run(ctx context.Context, job db.Job) {
 			level = slog.LevelError
 		}
 		logger.Log(ctx, level, "job failed", "code", code, "reason", reason)
-		r.fail(write, logger, job.ID, code)
+		r.fail(ctx, logger, job.ID, code)
 		return
 	}
 
-	n, err := q.SucceedJob(write, db.SucceedJobParams{
-		Result: sql.NullString{String: string(result), Valid: true},
-		Now:    sql.NullString{String: store.Now().String(), Valid: true},
-		ID:     job.ID,
+	r.record(ctx, logger, "record job success", func(write context.Context) (int64, error) {
+		return q.SucceedJob(write, db.SucceedJobParams{
+			Result: sql.NullString{String: string(result), Valid: true},
+			Now:    sql.NullString{String: store.Now().String(), Valid: true},
+			ID:     job.ID,
+		})
 	})
-	if err == nil && n != 1 {
-		err = errors.New("job is not running")
-	}
-	if err != nil {
-		logger.ErrorContext(write, "record job success", "error", err)
-	}
 }
 
 // fail records the job as failed with code. The record errors it logs come
 // from the database, never from a handler.
 func (r *Runner) fail(ctx context.Context, logger *slog.Logger, id, code string) {
-	n, err := db.New(r.st.Writer).FailJob(ctx, db.FailJobParams{
-		Error: sql.NullString{String: code, Valid: true},
-		Now:   sql.NullString{String: store.Now().String(), Valid: true},
-		ID:    id,
+	r.record(ctx, logger, "record job failure", func(write context.Context) (int64, error) {
+		return db.New(r.st.Writer).FailJob(write, db.FailJobParams{
+			Error: sql.NullString{String: code, Valid: true},
+			Now:   sql.NullString{String: store.Now().String(), Valid: true},
+			ID:    id,
+		})
 	})
-	if err == nil && n != 1 {
-		err = errors.New("job is not running")
-	}
-	if err != nil {
-		logger.ErrorContext(ctx, "record job failure", "error", err)
+}
+
+// record makes a job's final write, which must change the one running job.
+// A database error is retried with backoff until the write lands, so a
+// worker never moves on from a job it has finished while leaving it
+// running. Each attempt is made with FinalWriteContext, so even when ctx
+// has been cancelled, and is bounded by FinalWriteTimeout; once ctx is
+// cancelled, a failed or timed-out attempt is not retried and the job
+// stays running, so the next Start fails it as interrupted.
+func (r *Runner) record(ctx context.Context, logger *slog.Logger, what string, write func(context.Context) (int64, error)) {
+	backoff := retryMin
+	for {
+		attempt, cancel := FinalWriteContext(ctx)
+		n, err := write(attempt)
+		cancel()
+		if err == nil {
+			if n != 1 {
+				logger.ErrorContext(ctx, what, "error", "job is not running")
+			}
+			return
+		}
+		if ctx.Err() != nil {
+			logger.ErrorContext(context.WithoutCancel(ctx), what+" failed during shutdown; it fails at the next start", "error", err)
+			return
+		}
+		logger.ErrorContext(ctx, what+" failed; retrying", "error", err, "retry_in", backoff)
+		timer := time.NewTimer(backoff)
+		select {
+		case <-timer.C:
+		case <-ctx.Done():
+			timer.Stop()
+		}
+		backoff = min(2*backoff, retryMax)
 	}
 }

internal/jobs/jobs_test.go

@@ -187,6 +187,46 @@ func TestJobSucceeds(t *testing.T) {
 	}
 }
 
+func TestEnqueueTxStoresJobOnlyWithItsTransaction(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	r := newRunner(t, st, 1)
+	count := register(t, r, "count", func(_ context.Context, p countPayload, _ func(countResult) error) (countResult, error) {
+		return countResult{Done: p.Steps}, nil
+	})
+	start(t, r)
+	ctx := context.Background()
+
+	var rolledBack string
+	refused := errors.New("refused")
+	if err := st.WithTx(ctx, func(tx *sql.Tx) error {
+		var err error
+		rolledBack, err = count.EnqueueTx(ctx, tx, countPayload{Steps: 1})
+		if err != nil {
+			return err
+		}
+		return refused
+	}); !errors.Is(err, refused) {
+		t.Fatalf("WithTx = %v, want the refusal", err)
+	}
+	if _, err := r.Get(ctx, rolledBack); !errors.Is(err, ErrNotFound) {
+		t.Errorf("job of a rolled-back transaction: Get = %v, want ErrNotFound", err)
+	}
+
+	var id string
+	if err := st.WithTx(ctx, func(tx *sql.Tx) error {
+		var err error
+		id, err = count.EnqueueTx(ctx, tx, countPayload{Steps: 2})
+		return err
+	}); err != nil {
+		t.Fatal(err)
+	}
+	count.Wake()
+	if job := waitFor(t, r, id, finished); job.Status != StatusSucceeded || string(job.Result) != `{"done":2}` {
+		t.Errorf("job = %+v (result %s), want succeeded with {\"done\":2}", job, job.Result)
+	}
+}
+
 func TestJobFailsWithFailureCode(t *testing.T) {
 	t.Parallel()
 	st := migratedStore(t)
@@ -569,6 +609,98 @@ func TestClaimErrorIsRetried(t *testing.T) {
 	}
 }
 
+func TestFinalWriteErrorIsRetried(t *testing.T) {
+	st := migratedStore(t)
+	logs := &logBuffer{}
+	r := newRunnerLogging(t, st, 1, logs)
+	k := register(t, r, "count", func(ctx context.Context, p countPayload, publish func(countResult) error) (countResult, error) {
+		return countResult{Done: p.Steps}, nil
+	})
+	if _, err := st.Writer.ExecContext(t.Context(), `CREATE TRIGGER refuse_end BEFORE UPDATE OF status ON jobs WHEN NEW.status IN ('succeeded', 'failed') BEGIN SELECT RAISE(ABORT, 'end refused'); END`); err != nil {
+		t.Fatal(err)
+	}
+	start(t, r)
+	id := enqueue(t, k, countPayload{Steps: 3})
+
+	deadline := time.Now().Add(5 * time.Second)
+	for !strings.Contains(logs.String(), "record job success") {
+		if time.Now().After(deadline) {
+			t.Fatal("job success never recorded")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if _, err := st.Writer.ExecContext(t.Context(), `DROP TRIGGER refuse_end`); err != nil {
+		t.Fatal(err)
+	}
+
+	job := waitFor(t, r, id, finished)
+	if job.Status != StatusSucceeded || string(job.Result) != `{"done":3}` {
+		t.Fatalf("job = %+v (result %s), want succeeded with {\"done\":3}", job, job.Result)
+	}
+	if out := logs.String(); !strings.Contains(out, "record job success failed; retrying") {
+		t.Fatalf("final write error not logged as retried: %s", out)
+	}
+}
+
+func TestBlockedFinalWriteDoesNotHoldShutdown(t *testing.T) {
+	st := migratedStore(t)
+	r := newRunner(t, st, 1)
+	started, finish := make(chan struct{}), make(chan struct{})
+	k := register(t, r, "count", func(ctx context.Context, p countPayload, publish func(countResult) error) (countResult, error) {
+		close(started)
+		<-finish
+		return countResult{Done: p.Steps}, nil
+	})
+	stop := start(t, r)
+	id := enqueue(t, k, countPayload{Steps: 3})
+	<-started
+
+	// Hold the only writer connection, so the job's final write waits for it.
+	conn, err := st.Writer.Conn(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	waits := st.Writer.Stats().WaitCount
+	close(finish)
+	deadline := time.Now().Add(5 * time.Second)
+	for st.Writer.Stats().WaitCount == waits {
+		if time.Now().After(deadline) {
+			t.Fatal("final write never waited for the writer")
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	stopped := make(chan struct{})
+	go func() {
+		stop()
+		close(stopped)
+	}()
+	// The final write's attempt ends after 5 seconds; well past that, the
+	// worker is waiting for the writer with no bound.
+	select {
+	case <-stopped:
+	case <-time.After(15 * time.Second):
+		conn.Close()
+		<-stopped
+		t.Fatal("worker waited for a held writer through shutdown")
+	}
+	if err := conn.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	if job := waitFor(t, r, id, func(Job) bool { return true }); job.Status != StatusRunning {
+		t.Fatalf("after shutdown job = %+v, want left running", job)
+	}
+	second := newRunner(t, st, 1)
+	register(t, second, "count", func(context.Context, countPayload, func(countResult) error) (countResult, error) {
+		return countResult{}, nil
+	})
+	start(t, second)
+	if job := waitFor(t, second, id, finished); job.Status != StatusFailed || job.Error == nil || *job.Error != CodeInterrupted {
+		t.Errorf("interrupted job = %+v, want failed with %q", job, CodeInterrupted)
+	}
+}
+
 func TestRunnerEnqueueByKindName(t *testing.T) {
 	t.Parallel()
 	st := migratedStore(t)
@@ -604,3 +736,39 @@ func TestRunnerEnqueueByKindName(t *testing.T) {
 		t.Errorf("job = %+v (result %s), want succeeded with {\"done\":3}", job, job.Result)
 	}
 }
+
+func TestServiceOnlyKind(t *testing.T) {
+	t.Parallel()
+	st := migratedStore(t)
+	r := newRunner(t, st, 1)
+	k := register(t, r, "count", func(_ context.Context, p countPayload, _ func(countResult) error) (countResult, error) {
+		return countResult{Done: p.Steps}, nil
+	})
+	if err := k.ServiceOnly(); err != nil {
+		t.Fatal(err)
+	}
+	ctx := context.Background()
+
+	if _, err := r.Enqueue(ctx, "count", json.RawMessage(`{"steps":3}`)); !errors.Is(err, ErrServiceOnly) {
+		t.Errorf("Runner.Enqueue error = %v, want ErrServiceOnly", err)
+	}
+	var n int
+	if err := st.Reader.QueryRow("SELECT COUNT(*) FROM jobs").Scan(&n); err != nil {
+		t.Fatal(err)
+	}
+	if n != 0 {
+		t.Errorf("refused enqueue stored %d jobs, want 0", n)
+	}
+
+	id, err := k.Enqueue(ctx, countPayload{Steps: 3})
+	if err != nil {
+		t.Fatal(err)
+	}
+	start(t, r)
+	if job := waitFor(t, r, id, finished); job.Status != StatusSucceeded {
+		t.Errorf("job enqueued through its Kind = %+v, want succeeded", job)
+	}
+	if err := k.ServiceOnly(); err == nil {
+		t.Error("ServiceOnly after Start succeeded, want an error")
+	}
+}

internal/plan/draft.go

@@ -0,0 +1,229 @@
+package plan
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"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/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/store"
+)
+
+// DraftJob is the KindDraftWeek payload: the week to draft, and whether
+// the household confirmed drafting over a synced or changed plan.
+type DraftJob struct {
+	WeekStart string `json:"week_start"`
+	Confirm   bool   `json:"confirm"`
+}
+
+// draftResult is the KindDraftWeek result: the week drafted and its plan.
+type draftResult struct {
+	WeekStart string `json:"week_start"`
+	PlanID    string `json:"plan_id"`
+}
+
+func (r draftResult) PublicJSON() ([]byte, error) { return json.Marshal(r) }
+
+// runDraft drafts the week p.WeekStart: draft_week plans it from the
+// Regulars and the Quest log dinners no other current or later plan has,
+// given the household context and last week's dinners, and the draft is
+// stored as the week's plan if the plan is still as it was before
+// draft_week ran and every dinner it planned is still in the pool. A pool
+// under seven dinners fails with ReasonNotEnoughDinners and draft_week
+// failing with ReasonAIFailed; no week is made up instead.
+func (s *Service) runDraft(ctx context.Context, p DraftJob, _ func(draftResult) error) (draftResult, error) {
+	weekStart, err := ParseWeekStart(p.WeekStart)
+	if err != nil {
+		return draftResult{}, fmt.Errorf("plan: draft: %w", err)
+	}
+	base, err := s.revision(ctx, weekStart)
+	if err != nil {
+		return draftResult{}, err
+	}
+	in, err := s.request(ctx, weekStart)
+	if err != nil {
+		return draftResult{}, err
+	}
+	week, err := s.draft(ctx, household.PeriodKey(weekStart), in)
+	if err != nil {
+		if ctx.Err() != nil {
+			return draftResult{}, ctx.Err()
+		}
+		var few *skills.NotEnoughDinnersError
+		if errors.As(err, &few) {
+			return draftResult{}, &jobs.Failure{Code: ReasonNotEnoughDinners}
+		}
+		// Only the code is logged: the error may quote a model's response.
+		s.logger.InfoContext(ctx, "week draft failed", "week_start", p.WeekStart, "reason", ReasonAIFailed)
+		return draftResult{}, &jobs.Failure{Code: ReasonAIFailed}
+	}
+	for _, w := range week.Warnings {
+		s.logger.InfoContext(ctx, "week draft warning", "week_start", p.WeekStart, "warning", w)
+	}
+	planID, err := s.storeDraft(ctx, weekStart, household.WeekStart(in.Context.Today), p.Confirm, base, week)
+	if err != nil {
+		return draftResult{}, err
+	}
+	return draftResult{WeekStart: p.WeekStart, PlanID: planID}, nil
+}
+
+// noPlan is the revision of a week with no plan.
+const noPlan = -1
+
+// revision returns the revision of the plan of the week starting
+// weekStart, or noPlan when the week has none.
+func (s *Service) revision(ctx context.Context, weekStart store.LocalDate) (int64, error) {
+	cur, err := db.New(s.st.Reader).GetWeekPlan(ctx, weekStart.String())
+	if errors.Is(err, sql.ErrNoRows) {
+		return noPlan, nil
+	}
+	if err != nil {
+		return 0, fmt.Errorf("plan: read week %s: %w", weekStart, err)
+	}
+	return cur.Revision, nil
+}
+
+// request reads what draft_week is given for the week starting weekStart:
+// the household context, the pool, last week's dinners and the dinner
+// time.
+func (s *Service) request(ctx context.Context, weekStart store.LocalDate) (skills.WeekRequest, error) {
+	hctx, err := harness.BuildContext(ctx, s.st, time.Now(), ContextBudget)
+	if err != nil {
+		return skills.WeekRequest{}, fmt.Errorf("plan: %w", err)
+	}
+	q := db.New(s.st.Reader)
+	settings, err := q.GetHouseholdSettings(ctx)
+	if err != nil {
+		return skills.WeekRequest{}, fmt.Errorf("plan: read household settings: %w", err)
+	}
+	thisWeek := household.WeekStart(hctx.Today)
+	rows, err := q.ListDraftPool(ctx, db.ListDraftPoolParams{FromWeekStart: thisWeek.String(), WeekStart: weekStart.String()})
+	if err != nil {
+		return skills.WeekRequest{}, fmt.Errorf("plan: list draft pool: %w", err)
+	}
+	pool := make([]skills.Candidate, len(rows))
+	for i, d := range rows {
+		kind := skills.KindRegular
+		if d.Status == dinners.StatusQuestLog {
+			kind = skills.KindQuestLog
+		}
+		pool[i] = skills.Candidate{ID: d.ID, Name: d.Name, Kind: kind, Method: d.Method.String, Minutes: int(d.MinutesTotal.Int64)}
+	}
+	last, err := q.ListWeekPlanDinnerIDs(ctx, addDays(weekStart, -7).String())
+	if err != nil {
+		return skills.WeekRequest{}, fmt.Errorf("plan: list last week's dinners: %w", err)
+	}
+	lastWeek := []string{}
+	for _, id := range last {
+		lastWeek = append(lastWeek, id.String)
+	}
+	return skills.WeekRequest{
+		Context:    hctx,
+		WeekStart:  weekStart,
+		Pool:       pool,
+		LastWeek:   lastWeek,
+		DinnerTime: settings.DinnerTime,
+	}, nil
+}
+
+// storeDraft stores week as the plan of the week starting weekStart in one
+// transaction and returns the plan's id. A new plan is draft. A draft
+// replaces the days of an existing plan, keeping each day's calendar
+// event id; a draft plan stays draft and a synced or changed one becomes
+// changed, since Calendar no longer shows it. A plan synced since the
+// draft was asked for without confirm is left as it is, failing with
+// ReasonConfirmRequired, and so is a plan no longer at revision base (the
+// revision before draft_week ran, or noPlan), failing with
+// ReasonPlanChanged. The pool is read again, as of thisWeek like the pool
+// draft_week was given: a day whose dinner is no longer in it, or is in it
+// as a Regular rather than the Quest log or the other way round, leaves
+// everything as it is, failing with ReasonPoolChanged.
+func (s *Service) storeDraft(ctx context.Context, weekStart, thisWeek store.LocalDate, confirm bool, base int64, week skills.Week) (string, error) {
+	var planID string
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		rows, err := q.ListDraftPool(ctx, db.ListDraftPoolParams{FromWeekStart: thisWeek.String(), WeekStart: weekStart.String()})
+		if err != nil {
+			return fmt.Errorf("plan: list draft pool: %w", err)
+		}
+		pool := make(map[string]string, len(rows))
+		for _, d := range rows {
+			pool[d.ID] = d.Status
+		}
+		for _, d := range week.Days {
+			status, ok := pool[d.DinnerID]
+			if !ok || (status == dinners.StatusQuestLog) != d.IsNew {
+				return &jobs.Failure{Code: ReasonPoolChanged}
+			}
+		}
+		now := store.Now().String()
+		note := sql.NullString{String: week.Note, Valid: week.Note != ""}
+		cur, err := q.GetWeekPlan(ctx, weekStart.String())
+		switch {
+		case errors.Is(err, sql.ErrNoRows) && base != noPlan:
+			return &jobs.Failure{Code: ReasonPlanChanged}
+		case errors.Is(err, sql.ErrNoRows):
+			planID = store.NewID()
+			if err := q.CreateWeekPlan(ctx, db.CreateWeekPlanParams{
+				ID:        planID,
+				WeekStart: weekStart.String(),
+				AiNote:    note,
+				CreatedAt: now,
+				UpdatedAt: now,
+			}); err != nil {
+				return fmt.Errorf("plan: create week %s: %w", weekStart, err)
+			}
+		case err != nil:
+			return fmt.Errorf("plan: read week %s: %w", weekStart, err)
+		case cur.Status != StatusDraft && !confirm:
+			return &jobs.Failure{Code: ReasonConfirmRequired}
+		case cur.Revision != base:
+			return &jobs.Failure{Code: ReasonPlanChanged}
+		default:
+			planID = cur.ID
+			status := StatusDraft
+			if cur.Status != StatusDraft {
+				status = StatusChanged
+			}
+			if err := q.RedraftWeekPlan(ctx, db.RedraftWeekPlanParams{Status: status, AiNote: note, UpdatedAt: now, ID: cur.ID}); err != nil {
+				return fmt.Errorf("plan: redraft %s: %w", cur.ID, err)
+			}
+		}
+		for _, d := range week.Days {
+			isNew := int64(0)
+			if d.IsNew {
+				isNew = 1
+			}
+			if err := q.PutPlanDay(ctx, db.PutPlanDayParams{
+				ID:        store.NewID(),
+				PlanID:    planID,
+				Date:      d.Date,
+				DinnerID:  sql.NullString{String: d.DinnerID, Valid: true},
+				IsNew:     isNew,
+				CreatedAt: now,
+				UpdatedAt: now,
+			}); err != nil {
+				return fmt.Errorf("plan: put %s of %s: %w", d.Date, planID, err)
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		return "", err
+	}
+	return planID, nil
+}
+
+// addDays returns d plus n 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))
+}

internal/plan/plan.go

@@ -0,0 +1,445 @@
+// Package plan keeps the household's weekly plans: the Draft board the AI
+// drafts from the Regulars and the Quest log, and the swaps the household
+// makes on it. A draft runs as a job: draft_week plans seven dinners, one
+// a day from Monday to Sunday, and the job stores them as the week's plan,
+// replacing any draft before it unless the household edited the plan
+// while draft_week ran. A plan is draft until Push to Calendar
+// syncs it (Feature 16); an edit of a synced plan makes it changed.
+//
+// The Rotation check follows a plan day: MarkTried moves the Quest log
+// dinners planned on it to tried, and the household answers "Keep it in
+// rotation?" for each (D-021). Only their keep makes a dinner a Regular.
+package plan
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"log/slog"
+	"slices"
+	"time"
+
+	"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/store"
+)
+
+// KindDraftWeek is the job that drafts a week's plan.
+const KindDraftWeek = "draft_week"
+
+// Plan statuses (the week_plans.status column).
+const (
+	StatusDraft   = "draft"
+	StatusSynced  = "synced"
+	StatusChanged = "changed"
+)
+
+// Reasons a draft failed, stored as the KindDraftWeek job's failure code.
+// Any other failure, such as the database's, is the runner's
+// internal_error.
+const (
+	// ReasonNotEnoughDinners: the Regulars and Quest log hold fewer than
+	// seven dinners to draft from.
+	ReasonNotEnoughDinners = "not_enough_dinners"
+	// ReasonAIFailed: draft_week failed; no week is made up instead.
+	ReasonAIFailed = "ai_failed"
+	// ReasonConfirmRequired: the plan was synced after the draft was
+	// asked for without confirm, so the draft does not replace it.
+	ReasonConfirmRequired = "confirm_required"
+	// ReasonPlanChanged: the plan was edited while draft_week ran, so the
+	// draft does not replace the edit.
+	ReasonPlanChanged = "plan_changed"
+	// ReasonPoolChanged: a dinner the draft planned left the pool while
+	// draft_week ran (archived, tried, or its Quest log dinner planned on
+	// another week), so the draft is not stored; drafting again uses the
+	// pool as it is now.
+	ReasonPoolChanged = "pool_changed"
+)
+
+// Reasons are every draft failure reason.
+var Reasons = []string{ReasonNotEnoughDinners, ReasonAIFailed, ReasonConfirmRequired, ReasonPlanChanged, ReasonPoolChanged}
+
+// ContextBudget is the character budget of the household context
+// draft_week is given (see harness.BuildContext).
+const ContextBudget = 16000
+
+// plannable are the dinner statuses a day may be swapped to.
+var plannable = []string{dinners.StatusRegular, dinners.StatusQuestLog}
+
+// ErrNotFound is returned for a week with no plan.
+var ErrNotFound = errors.New("plan not found")
+
+// ErrDinnerNotFound is a swap to an unknown dinner.
+var ErrDinnerNotFound = errors.New("dinner not found")
+
+// ErrDinnerAlreadyPlanned is a swap to a dinner already on another day of
+// the week.
+var ErrDinnerAlreadyPlanned = errors.New("the dinner is already on another day of this week")
+
+// ErrConfirmRequired is a draft over a synced or changed plan asked for
+// without confirm.
+var ErrConfirmRequired = errors.New("the plan was pushed to Calendar; drafting over it needs confirm")
+
+// ErrDraftRunning is a confirmed draft asked for while a draft of the week
+// asked for without confirm is queued or running.
+var ErrDraftRunning = errors.New("a draft of the week without confirm is already running; ask again when it finishes")
+
+// InvalidWeekError is a week start that is not a Monday date.
+type InvalidWeekError struct {
+	Value string
+}
+
+func (e *InvalidWeekError) Error() string {
+	return fmt.Sprintf("week start %q is not a Monday date (YYYY-MM-DD)", e.Value)
+}
+
+// InvalidDayError is a swap of a date outside the plan's week.
+type InvalidDayError struct {
+	Value string
+}
+
+func (e *InvalidDayError) Error() string {
+	return fmt.Sprintf("date %q is not a day of the week (YYYY-MM-DD)", e.Value)
+}
+
+// DinnerNotPlannableError is a swap to a dinner that is neither a Regular
+// nor in the Quest log.
+type DinnerNotPlannableError struct {
+	Status string
+}
+
+func (e *DinnerNotPlannableError) Error() string {
+	return fmt.Sprintf("the dinner is %s; only Regulars and Quest log dinners can be planned", e.Status)
+}
+
+// ParseWeekStart parses s, a household-local Monday as YYYY-MM-DD.
+func ParseWeekStart(s string) (store.LocalDate, error) {
+	d, err := store.ParseLocalDate(s)
+	if err != nil {
+		return store.LocalDate{}, &InvalidWeekError{Value: s}
+	}
+	if _, err := household.WeekDays(d); err != nil {
+		return store.LocalDate{}, &InvalidWeekError{Value: s}
+	}
+	return d, nil
+}
+
+// Drafter runs draft_week on in; scope names the week. In production it is
+// skills.DraftWeek with the household's harness.Config.
+type Drafter func(ctx context.Context, scope string, in skills.WeekRequest) (skills.Week, error)
+
+// Service drafts, reads and edits weekly plans.
+type Service struct {
+	st       *store.Store
+	draft    Drafter
+	logger   *slog.Logger
+	draftJob *jobs.Kind[DraftJob]
+}
+
+// NewService returns a service over st that drafts with draft 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, logger *slog.Logger) (*Service, error) {
+	switch {
+	case st == nil:
+		return nil, errors.New("plan: nil store")
+	case draft == nil:
+		return nil, errors.New("plan: nil drafter")
+	case runner == nil:
+		return nil, errors.New("plan: nil job runner")
+	case logger == nil:
+		return nil, errors.New("plan: nil logger")
+	}
+	s := &Service{st: st, draft: draft, logger: logger}
+	kind, err := jobs.Register(runner, KindDraftWeek, s.runDraft, Reasons...)
+	if err != nil {
+		return nil, err
+	}
+	if err := kind.ServiceOnly(); err != nil {
+		return nil, err
+	}
+	s.draftJob = kind
+	return s, nil
+}
+
+// Plan is a week's plan as the API shows it.
+type Plan struct {
+	ID        string `json:"id"`
+	WeekStart string `json:"week_start"`
+	// WeekLabel is e.g. "Week 41 · Oct 5 – 11".
+	WeekLabel        string  `json:"week_label"`
+	Status           string  `json:"status"`
+	AINote           *string `json:"ai_note"`
+	CalendarSyncedAt *string `json:"calendar_synced_at"`
+	Days             []Day   `json:"days"`
+	UpdatedAt        string  `json:"updated_at"`
+}
+
+// Day is one day of a plan.
+type Day struct {
+	// Date is household-local, YYYY-MM-DD.
+	Date   string `json:"date"`
+	Dinner Dinner `json:"dinner"`
+	// IsNew is true for a dinner planned from the Quest log.
+	IsNew bool `json:"is_new"`
+	// StartBy is when a crock-pot dinner must start to be ready at the
+	// household's dinner time; null for any other dinner and for a
+	// crock-pot dinner whose minutes are unknown.
+	StartBy *time.Time `json:"start_by"`
+}
+
+// Dinner is a planned dinner as a plan day shows it.
+type Dinner struct {
+	ID      string  `json:"id"`
+	Name    string  `json:"name"`
+	Photo   *string `json:"photo"`
+	Minutes *int64  `json:"minutes"`
+	Method  *string `json:"method"`
+	Origin  string  `json:"origin"`
+}
+
+// Get returns the plan of the week starting weekStart, or ErrNotFound.
+// The plan and the household settings come from one read transaction.
+func (s *Service) Get(ctx context.Context, weekStart store.LocalDate) (p Plan, err error) {
+	tx, err := s.st.Reader.BeginTx(ctx, nil)
+	if err != nil {
+		return Plan{}, fmt.Errorf("plan: begin read: %w", err)
+	}
+	defer func() {
+		err = errors.Join(err, tx.Rollback())
+	}()
+	return readPlan(ctx, db.New(tx), weekStart)
+}
+
+// readPlan reads the plan of the week starting weekStart through q, with
+// each day's start_by from the household's dinner time and zone.
+func readPlan(ctx context.Context, q *db.Queries, weekStart store.LocalDate) (Plan, error) {
+	label, err := household.WeekLabel(weekStart)
+	if err != nil {
+		return Plan{}, fmt.Errorf("plan: %w", err)
+	}
+	row, err := q.GetWeekPlan(ctx, weekStart.String())
+	if errors.Is(err, sql.ErrNoRows) {
+		return Plan{}, ErrNotFound
+	}
+	if err != nil {
+		return Plan{}, fmt.Errorf("plan: read week %s: %w", weekStart, err)
+	}
+	settings, err := q.GetHouseholdSettings(ctx)
+	if err != nil {
+		return Plan{}, fmt.Errorf("plan: read household settings: %w", err)
+	}
+	zone, err := household.LoadZone(settings.Timezone)
+	if err != nil {
+		return Plan{}, fmt.Errorf("plan: household settings: %w", err)
+	}
+	rows, err := q.ListPlanDays(ctx, row.ID)
+	if err != nil {
+		return Plan{}, fmt.Errorf("plan: read days of %s: %w", row.ID, err)
+	}
+	dates, err := household.WeekDays(weekStart)
+	if err != nil {
+		return Plan{}, fmt.Errorf("plan: %w", err)
+	}
+	if len(rows) != len(dates) {
+		return Plan{}, fmt.Errorf("plan: week %s has %d planned days, want %d", weekStart, len(rows), len(dates))
+	}
+	p := Plan{
+		ID:               row.ID,
+		WeekStart:        row.WeekStart,
+		WeekLabel:        label,
+		Status:           row.Status,
+		AINote:           nullString(row.AiNote),
+		CalendarSyncedAt: nullString(row.CalendarSyncedAt),
+		Days:             make([]Day, len(rows)),
+		UpdatedAt:        row.UpdatedAt,
+	}
+	for i, r := range rows {
+		if r.Date != dates[i].String() {
+			return Plan{}, fmt.Errorf("plan: week %s day %d is %s, want %s", weekStart, i+1, r.Date, dates[i])
+		}
+		startBy, err := startBy(zone, dates[i], settings.DinnerTime, r.Dinner)
+		if err != nil {
+			return Plan{}, fmt.Errorf("plan: start by of %s: %w", r.Date, err)
+		}
+		p.Days[i] = Day{Date: r.Date, Dinner: fromDinner(r.Dinner), IsNew: r.IsNew == 1, StartBy: startBy}
+	}
+	return p, nil
+}
+
+// startBy returns when crock-pot dinner d must start on date to be ready at
+// dinnerTime in zone, or nil for any other dinner and for a crock-pot
+// dinner whose minutes are unknown.
+func startBy(zone *time.Location, date store.LocalDate, dinnerTime string, d db.Dinner) (*time.Time, error) {
+	if !d.Method.Valid || d.Method.String != "crockpot" || !d.MinutesTotal.Valid || d.MinutesTotal.Int64 <= 0 {
+		return nil, nil
+	}
+	at, err := household.LocalTime(zone, date, dinnerTime)
+	if err != nil {
+		return nil, err
+	}
+	at = at.Add(-time.Duration(d.MinutesTotal.Int64) * time.Minute)
+	return &at, nil
+}
+
+// Draft is a draft asked for: the job drafting the week, and whether this
+// call enqueued it rather than found one already queued or running.
+type Draft struct {
+	JobID   string `json:"jobId"`
+	Created bool   `json:"-"`
+}
+
+// StartDraft enqueues the KindDraftWeek job drafting the week starting
+// weekStart, unless one is already queued or running for it, which it
+// returns instead with Created false, so a week has at most one draft in
+// flight. A confirmed draft joins only a confirmed job: while the week's
+// job was asked for without confirm, it fails with ErrDraftRunning and
+// 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) {
+	if _, err := household.WeekDays(weekStart); err != nil {
+		return Draft{}, &InvalidWeekError{Value: weekStart.String()}
+	}
+	var d Draft
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		cur, err := q.GetWeekPlan(ctx, weekStart.String())
+		switch {
+		case errors.Is(err, sql.ErrNoRows):
+		case err != nil:
+			return fmt.Errorf("plan: read week %s: %w", weekStart, err)
+		case cur.Status != StatusDraft && !confirm:
+			return ErrConfirmRequired
+		}
+		active, err := q.GetActiveDraftJob(ctx, db.GetActiveDraftJobParams{Kind: KindDraftWeek, WeekStart: weekStart.String()})
+		switch {
+		case errors.Is(err, sql.ErrNoRows):
+		case err != nil:
+			return fmt.Errorf("plan: read draft job of %s: %w", weekStart, err)
+		case confirm && active.Confirmed != 1:
+			return ErrDraftRunning
+		default:
+			d = Draft{JobID: active.ID}
+			return nil
+		}
+		id, err := s.draftJob.EnqueueTx(ctx, tx, DraftJob{WeekStart: weekStart.String(), Confirm: confirm})
+		if err != nil {
+			return fmt.Errorf("plan: enqueue draft of %s: %w", weekStart, err)
+		}
+		d = Draft{JobID: id, Created: true}
+		return nil
+	})
+	if err != nil {
+		return Draft{}, err
+	}
+	if d.Created {
+		s.draftJob.Wake()
+	}
+	return d, nil
+}
+
+// Swap plans dinnerID on date of the week starting weekStart, marking the
+// day new when the dinner is in the Quest log. Swapping a synced plan
+// makes it changed. The week must have a plan (else ErrNotFound), date
+// must be one of its days (else *InvalidDayError), the dinner must be a
+// Regular or in the Quest log (else ErrDinnerNotFound or
+// *DinnerNotPlannableError), and it must not be on another day of the
+// week (else ErrDinnerAlreadyPlanned). It returns the plan as swapped.
+func (s *Service) Swap(ctx context.Context, weekStart store.LocalDate, date, dinnerID string) (Plan, error) {
+	dates, err := household.WeekDays(weekStart)
+	if err != nil {
+		return Plan{}, &InvalidWeekError{Value: weekStart.String()}
+	}
+	day, err := store.ParseLocalDate(date)
+	if err != nil || !slices.Contains(dates[:], day) {
+		return Plan{}, &InvalidDayError{Value: date}
+	}
+	var p Plan
+	err = s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		cur, err := q.GetWeekPlan(ctx, weekStart.String())
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrNotFound
+		}
+		if err != nil {
+			return fmt.Errorf("plan: read week %s: %w", weekStart, err)
+		}
+		d, err := q.GetDinner(ctx, dinnerID)
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrDinnerNotFound
+		}
+		if err != nil {
+			return fmt.Errorf("plan: read dinner %s: %w", dinnerID, err)
+		}
+		if !slices.Contains(plannable, d.Status) {
+			return &DinnerNotPlannableError{Status: d.Status}
+		}
+		days, err := q.ListPlanDays(ctx, cur.ID)
+		if err != nil {
+			return fmt.Errorf("plan: read days of %s: %w", cur.ID, err)
+		}
+		if slices.ContainsFunc(days, func(r db.ListPlanDaysRow) bool { return r.Date != day.String() && r.Dinner.ID == d.ID }) {
+			return ErrDinnerAlreadyPlanned
+		}
+		now := store.Now().String()
+		n, err := q.SwapPlanDay(ctx, db.SwapPlanDayParams{
+			DinnerID:  sql.NullString{String: d.ID, Valid: true},
+			IsNew:     isNew(d.Status),
+			UpdatedAt: now,
+			PlanID:    cur.ID,
+			Date:      day.String(),
+		})
+		if err != nil {
+			return fmt.Errorf("plan: swap %s of %s: %w", day, cur.ID, err)
+		}
+		if n != 1 {
+			return fmt.Errorf("plan: %s has no day %s", cur.ID, day)
+		}
+		if err := q.MarkWeekPlanEdited(ctx, db.MarkWeekPlanEditedParams{UpdatedAt: now, ID: cur.ID}); err != nil {
+			return fmt.Errorf("plan: mark %s edited: %w", cur.ID, err)
+		}
+		p, err = readPlan(ctx, q, weekStart)
+		return err
+	})
+	if err != nil {
+		return Plan{}, err
+	}
+	return p, nil
+}
+
+// isNew is plan_days.is_new for a dinner with status: 1 for the Quest log.
+func isNew(status string) int64 {
+	if status == dinners.StatusQuestLog {
+		return 1
+	}
+	return 0
+}
+
+func fromDinner(d db.Dinner) Dinner {
+	out := Dinner{
+		ID:     d.ID,
+		Name:   d.Name,
+		Method: nullString(d.Method),
+		Origin: d.Origin,
+	}
+	if d.MinutesTotal.Valid {
+		out.Minutes = &d.MinutesTotal.Int64
+	}
+	if d.PhotoID.Valid {
+		u := dinners.PhotoURL(d.PhotoID.String)
+		out.Photo = &u
+	}
+	return out
+}
+
+func nullString(s sql.NullString) *string {
+	if !s.Valid {
+		return nil
+	}
+	return &s.String
+}

internal/plan/plan_test.go

@@ -0,0 +1,946 @@
+package plan_test
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"slices"
+	"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/plan"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/migrations"
+)
+
+// week is the Monday the tests draft, and weekDates its days.
+var (
+	week      = mustDate("2026-10-12")
+	weekDates = []string{"2026-10-12", "2026-10-13", "2026-10-14", "2026-10-15", "2026-10-16", "2026-10-17", "2026-10-18"}
+)
+
+func mustDate(s string) store.LocalDate {
+	d, err := store.ParseLocalDate(s)
+	if err != nil {
+		panic(err)
+	}
+	return d
+}
+
+type env struct {
+	svc    *plan.Service
+	st     *store.Store
+	runner *jobs.Runner
+	model  *llm.Fake
+	// ids are the seeded dinners' ids by name.
+	ids map[string]string
+
+	mu     sync.Mutex
+	inputs []skills.WeekRequest
+}
+
+// newEnv returns a plan service over a migrated store in zone
+// America/New_York with dinner time 17:30, the Regulars below and Quest
+// log dinners Pad Thai and Shawarma Bowls, and an unstarted job runner
+// with two workers. It drafts through the real harness and draft_week with
+// the scripted e.model.
+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, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
+	e := &env{st: st, model: &llm.Fake{}, ids: map[string]string{}}
+	for _, d := range []struct {
+		name, status, method string
+		minutes              int64
+	}{
+		{"Beef Chili", "regular", "crockpot", 240},
+		{"Pot Roast", "regular", "crockpot", 0},
+		{"Chicken Fajitas", "regular", "stovetop", 30},
+		{"Spaghetti Bolognese", "regular", "stovetop", 45},
+		{"Sheet Pan Salmon", "regular", "oven", 35},
+		{"Pad Thai", "quest_log", "stovetop", 35},
+		{"Shawarma Bowls", "quest_log", "oven", 40},
+	} {
+		e.ids[d.name] = e.dinner(t, d.name, d.status, d.method, d.minutes)
+	}
+	guard, err := harness.NewGuard(harness.DefaultMaxCalls)
+	if err != nil {
+		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 e.model, nil },
+		Store:       st,
+		Guard:       guard,
+	}
+	drafter := func(ctx context.Context, scope string, in skills.WeekRequest) (skills.Week, error) {
+		e.mu.Lock()
+		e.inputs = append(e.inputs, in)
+		e.mu.Unlock()
+		return skills.DraftWeek(ctx, cfg, scope, in)
+	}
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	// Two workers, as cmd/server runs, so drafts of a week could overlap.
+	e.runner, err = jobs.NewRunner(st, logger, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.svc, err = plan.NewService(st, drafter, e.runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return e
+}
+
+// input returns the request of the ith draft_week run.
+func (e *env) input(i int) skills.WeekRequest {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return e.inputs[i]
+}
+
+// start starts the env's job runner, stopping it when the test ends.
+func (e *env) start(t *testing.T) {
+	t.Helper()
+	ctx, cancel := context.WithCancel(context.Background())
+	if err := e.runner.Start(ctx); err != nil {
+		cancel()
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		cancel()
+		e.runner.Wait()
+	})
+}
+
+// dinner stores a dinner and returns its id; minutes 0 is unknown.
+func (e *env) dinner(t *testing.T, name, status, method string, minutes int64) string {
+	t.Helper()
+	now := store.Now().String()
+	origin := "regular"
+	if status != "regular" {
+		origin = "side_quest"
+	}
+	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,
+		Method:          sql.NullString{String: method, Valid: method != ""},
+		MinutesTotal:    sql.NullInt64{Int64: minutes, Valid: minutes > 0},
+		GroundingStatus: "manual",
+		CreatedAt:       now,
+		UpdatedAt:       now,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return d.ID
+}
+
+// reply scripts one draft_week reply planning the dinners named names on
+// weekDates, in order.
+func (e *env) reply(note string, names ...string) {
+	e.model.QueueGenerate(e.weekReply(note, names...))
+}
+
+// weekReply is the draft_week reply planning the dinners named names on
+// weekDates, in order.
+func (e *env) weekReply(note string, names ...string) llm.GenerateResult {
+	return e.weekReplyOn(weekDates, note, names...)
+}
+
+// weekReplyOn is the draft_week reply planning the dinners named names on
+// dates, in order.
+func (e *env) weekReplyOn(dates []string, note string, names ...string) llm.GenerateResult {
+	var days []string
+	for i, name := range names {
+		days = append(days, fmt.Sprintf(`{"date":%q,"dinner_id":%q}`, dates[i], e.ids[name]))
+	}
+	js := fmt.Sprintf(`{"days":[%s],"note":%q}`, strings.Join(days, ","), note)
+	return llm.GenerateResult{Response: llm.Response{Text: js, JSON: json.RawMessage(js)}}
+}
+
+// fullWeek plans every seeded dinner, Beef Chili on Monday and Pot Roast
+// on Tuesday.
+var fullWeek = []string{"Beef Chili", "Pot Roast", "Pad Thai", "Chicken Fajitas", "Shawarma Bowls", "Spaghetti Bolognese", "Sheet Pan Salmon"}
+
+// waitJob waits for job id to finish and returns it.
+func (e *env) waitJob(t *testing.T, id string) jobs.Job {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for {
+		job, err := e.runner.Get(t.Context(), id)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if job.Status == jobs.StatusSucceeded || job.Status == jobs.StatusFailed {
+			return job
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("job %s still %s", id, job.Status)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+}
+
+// draft asks for a draft of week with confirm and waits for its job.
+func (e *env) draft(t *testing.T, confirm bool) jobs.Job {
+	t.Helper()
+	d, err := e.svc.StartDraft(t.Context(), week, confirm)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !d.Created {
+		t.Fatalf("draft job %s was already queued", d.JobID)
+	}
+	return e.waitJob(t, d.JobID)
+}
+
+// mustDraft drafts week with confirm, requiring the job to succeed, and
+// returns the plan.
+func (e *env) mustDraft(t *testing.T, confirm bool) plan.Plan {
+	t.Helper()
+	job := e.draft(t, confirm)
+	if job.Status != jobs.StatusSucceeded {
+		t.Fatalf("draft job %s, error %v", job.Status, *job.Error)
+	}
+	p, err := e.svc.Get(t.Context(), week)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var res struct {
+		WeekStart string `json:"week_start"`
+		PlanID    string `json:"plan_id"`
+	}
+	if err := json.Unmarshal(job.Result, &res); err != nil {
+		t.Fatal(err)
+	}
+	if res.WeekStart != week.String() || res.PlanID != p.ID {
+		t.Fatalf("draft result = %+v, want week %s plan %s", res, week, p.ID)
+	}
+	return p
+}
+
+// setStatus sets the plan of week to status, as Push to Calendar would.
+func (e *env) setStatus(t *testing.T, status string) {
+	t.Helper()
+	if _, err := e.st.Writer.ExecContext(t.Context(), `UPDATE week_plans SET status = ?, calendar_synced_at = ? WHERE week_start = ?`,
+		status, store.Now().String(), week.String()); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func dayNames(p plan.Plan) []string {
+	var names []string
+	for _, d := range p.Days {
+		names = append(names, d.Dinner.Name)
+	}
+	return names
+}
+
+func TestDraftCreatesPlan(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("Five Regulars and two from your Quest log.", fullWeek...)
+
+	p := e.mustDraft(t, false)
+
+	if p.Status != plan.StatusDraft || p.WeekStart != "2026-10-12" || p.WeekLabel != "Week 42 · Oct 12 – 18" {
+		t.Errorf("plan = %s %s %q, want draft 2026-10-12 \"Week 42 · Oct 12 – 18\"", p.Status, p.WeekStart, p.WeekLabel)
+	}
+	if p.AINote == nil || *p.AINote != "Five Regulars and two from your Quest log." {
+		t.Errorf("ai_note = %v", p.AINote)
+	}
+	if p.CalendarSyncedAt != nil {
+		t.Errorf("calendar_synced_at = %v, want null", *p.CalendarSyncedAt)
+	}
+	if got := dayNames(p); !slices.Equal(got, fullWeek) {
+		t.Errorf("days = %v, want %v", got, fullWeek)
+	}
+	for i, d := range p.Days {
+		if d.Date != weekDates[i] {
+			t.Errorf("day %d date = %s, want %s", i, d.Date, weekDates[i])
+		}
+		wantNew := d.Dinner.Name == "Pad Thai" || d.Dinner.Name == "Shawarma Bowls"
+		if d.IsNew != wantNew {
+			t.Errorf("%s is_new = %v, want %v", d.Dinner.Name, d.IsNew, wantNew)
+		}
+		if d.Dinner.ID != e.ids[d.Dinner.Name] {
+			t.Errorf("%s id = %s", d.Dinner.Name, d.Dinner.ID)
+		}
+	}
+	chili := p.Days[0]
+	if chili.Dinner.Method == nil || *chili.Dinner.Method != "crockpot" || chili.Dinner.Minutes == nil || *chili.Dinner.Minutes != 240 || chili.Dinner.Origin != "regular" {
+		t.Errorf("Beef Chili dinner = %+v", chili.Dinner)
+	}
+
+	// The pool is every Regular and Quest log dinner; last week has no
+	// plan.
+	in := e.input(0)
+	var pool []string
+	for _, c := range in.Pool {
+		pool = append(pool, c.Name+"/"+c.Kind)
+	}
+	slices.Sort(pool)
+	want := []string{"Beef Chili/regular", "Chicken Fajitas/regular", "Pad Thai/quest_log", "Pot Roast/regular",
+		"Shawarma Bowls/quest_log", "Sheet Pan Salmon/regular", "Spaghetti Bolognese/regular"}
+	if !slices.Equal(pool, want) {
+		t.Errorf("pool = %v, want %v", pool, want)
+	}
+	if in.WeekStart != week || in.DinnerTime != "17:30" || len(in.LastWeek) != 0 {
+		t.Errorf("request week %s dinner time %s last week %v", in.WeekStart, in.DinnerTime, in.LastWeek)
+	}
+}
+
+func TestStartByIsDinnerTimeMinusMinutesForCrockPot(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("", fullWeek...)
+	p := e.mustDraft(t, false)
+
+	newYork, err := time.LoadLocation("America/New_York")
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Beef Chili: crock pot, 240 minutes, dinner at 17:30 EDT.
+	if got, want := p.Days[0].StartBy, time.Date(2026, 10, 12, 13, 30, 0, 0, newYork); got == nil || !got.Equal(want) {
+		t.Errorf("Beef Chili start_by = %v, want %v", got, want)
+	}
+	// Pot Roast is a crock-pot dinner with no minutes; the rest are not
+	// crock-pot dinners.
+	for _, d := range p.Days[1:] {
+		if d.StartBy != nil {
+			t.Errorf("%s start_by = %v, want null", d.Dinner.Name, *d.StartBy)
+		}
+	}
+	if p.AINote != nil {
+		t.Errorf("ai_note = %q, want null for an empty note", *p.AINote)
+	}
+
+	// start_by follows the household's dinner time.
+	dinnerTime := "18:45"
+	if _, err := household.NewSettingsService(e.st).Update(t.Context(), household.SettingsPatch{DinnerTime: &dinnerTime}, "member-1"); err != nil {
+		t.Fatal(err)
+	}
+	p, err = e.svc.Get(t.Context(), week)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := p.Days[0].StartBy, time.Date(2026, 10, 12, 14, 45, 0, 0, newYork); got == nil || !got.Equal(want) {
+		t.Errorf("Beef Chili start_by = %v, want %v", got, want)
+	}
+	if b, err := json.Marshal(p.Days[0]); err != nil || !strings.Contains(string(b), `"start_by":"2026-10-12T14:45:00-04:00"`) {
+		t.Errorf("day JSON = %s, %v; want start_by in the household zone", b, err)
+	}
+}
+
+func TestStartByAcrossDaylightSavingTimeEnd(t *testing.T) {
+	e := newEnv(t)
+	// New York leaves daylight saving time at 02:00 on Sunday 2026-11-01.
+	// Beef Chili (240 minutes) is planned Monday to Saturday and a 20-hour
+	// crock-pot dinner on Sunday, so its start crosses the change.
+	stew := e.dinner(t, "Overnight Stew", "regular", "crockpot", 1200)
+	q := db.New(e.st.Writer)
+	now := store.Now().String()
+	id := store.NewID()
+	dst := mustDate("2026-10-26")
+	if err := q.CreateWeekPlan(t.Context(), db.CreateWeekPlanParams{ID: id, WeekStart: dst.String(), CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	dates := []string{"2026-10-26", "2026-10-27", "2026-10-28", "2026-10-29", "2026-10-30", "2026-10-31", "2026-11-01"}
+	for i, date := range dates {
+		dinner := e.ids["Beef Chili"]
+		if i == 6 {
+			dinner = stew
+		}
+		if err := q.PutPlanDay(t.Context(), db.PutPlanDayParams{ID: store.NewID(), PlanID: id, Date: date,
+			DinnerID: sql.NullString{String: dinner, Valid: true}, CreatedAt: now, UpdatedAt: now}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	p, err := e.svc.Get(t.Context(), dst)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Saturday's dinner is 17:30 EDT; Sunday's is 17:30 EST, 22:30 UTC, and
+	// twenty hours before it is 22:30 EDT on Saturday.
+	for _, tc := range []struct {
+		day  int
+		want string
+	}{
+		{5, `"2026-10-31T13:30:00-04:00"`},
+		{6, `"2026-10-31T22:30:00-04:00"`},
+	} {
+		b, err := json.Marshal(p.Days[tc.day].StartBy)
+		if err != nil || string(b) != tc.want {
+			t.Errorf("%s start_by = %s, %v; want %s", dates[tc.day], b, err, tc.want)
+		}
+	}
+	// Swapped to Short Ribs (240 minutes), Sunday starts at 13:30 EST.
+	ribs := e.dinner(t, "Short Ribs", "regular", "crockpot", 240)
+	if _, err := e.svc.Swap(t.Context(), dst, "2026-11-01", ribs); err != nil {
+		t.Fatal(err)
+	}
+	if p, err = e.svc.Get(t.Context(), dst); err != nil {
+		t.Fatal(err)
+	}
+	if b, err := json.Marshal(p.Days[6].StartBy); err != nil || string(b) != `"2026-11-01T13:30:00-05:00"` {
+		t.Errorf("Sunday Short Ribs start_by = %s, %v; want 13:30 EST", b, err)
+	}
+}
+
+func TestDraftGivesLastWeek(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	last := mustDate("2026-10-05")
+	q := db.New(e.st.Writer)
+	now := store.Now().String()
+	id := store.NewID()
+	if err := q.CreateWeekPlan(t.Context(), db.CreateWeekPlanParams{ID: id, WeekStart: last.String(), CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	if err := q.PutPlanDay(t.Context(), db.PutPlanDayParams{ID: store.NewID(), PlanID: id, Date: "2026-10-06",
+		DinnerID: sql.NullString{String: e.ids["Chicken Fajitas"], Valid: true}, CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	e.reply("", fullWeek...)
+	e.mustDraft(t, false)
+	if got := e.input(0).LastWeek; !slices.Equal(got, []string{e.ids["Chicken Fajitas"]}) {
+		t.Errorf("last week = %v, want Chicken Fajitas", got)
+	}
+}
+
+func TestDraftPoolLeavesOutQuestLogPlannedOnAnotherWeek(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	// Pad Thai is on a later week's plan, so the Quest log no longer
+	// offers it; an eighth dinner keeps the pool at seven.
+	q := db.New(e.st.Writer)
+	now := store.Now().String()
+	later := store.NewID()
+	if err := q.CreateWeekPlan(t.Context(), db.CreateWeekPlanParams{ID: later, WeekStart: "2099-01-05", CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	if err := q.PutPlanDay(t.Context(), db.PutPlanDayParams{ID: store.NewID(), PlanID: later, Date: "2099-01-05",
+		DinnerID: sql.NullString{String: e.ids["Pad Thai"], Valid: true}, IsNew: 1, CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	e.ids["Fish Tacos"] = e.dinner(t, "Fish Tacos", "regular", "", 0)
+	names := []string{"Beef Chili", "Pot Roast", "Fish Tacos", "Chicken Fajitas", "Shawarma Bowls", "Spaghetti Bolognese", "Sheet Pan Salmon"}
+	e.reply("", names...)
+	p := e.mustDraft(t, false)
+	if got := dayNames(p); !slices.Equal(got, names) {
+		t.Errorf("days = %v", got)
+	}
+	for _, c := range e.input(0).Pool {
+		if c.Name == "Pad Thai" {
+			t.Errorf("pool has Pad Thai, planned on a later week")
+		}
+	}
+	// A redraft of the week keeps offering its own Quest log dinners.
+	e.reply("", names...)
+	e.mustDraft(t, false)
+	if !slices.ContainsFunc(e.input(1).Pool, func(c skills.Candidate) bool { return c.Name == "Shawarma Bowls" }) {
+		t.Errorf("redraft pool left out Shawarma Bowls, planned on this week")
+	}
+}
+
+func TestDraftFailsWhenPoolDinnerLeavesWhileDrafting(t *testing.T) {
+	for _, status := range []string{"archived", "tried"} {
+		t.Run(status, func(t *testing.T) {
+			e := newEnv(t)
+			e.start(t)
+			// Pad Thai leaves the Quest log while draft_week plans it.
+			started, release := make(chan struct{}), make(chan struct{})
+			r := e.weekReply("", fullWeek...)
+			r.Started, r.Release = started, release
+			e.model.QueueGenerate(r)
+			d, err := e.svc.StartDraft(t.Context(), week, false)
+			if err != nil {
+				t.Fatal(err)
+			}
+			<-started
+			if _, err := e.st.Writer.ExecContext(t.Context(), `UPDATE dinners SET status = ? WHERE id = ?`, status, e.ids["Pad Thai"]); err != nil {
+				t.Fatal(err)
+			}
+			close(release)
+			job := e.waitJob(t, d.JobID)
+			if job.Status != jobs.StatusFailed || *job.Error != plan.ReasonPoolChanged {
+				t.Fatalf("job %s %v, want failed %s", job.Status, job.Error, plan.ReasonPoolChanged)
+			}
+			if _, err := e.svc.Get(t.Context(), week); !errors.Is(err, plan.ErrNotFound) {
+				t.Errorf("Get = %v, want ErrNotFound: no partial plan", err)
+			}
+		})
+	}
+}
+
+func TestDraftsOfTwoWeeksDoNotShareAQuestLogDinner(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	// This week's draft plans Pad Thai; while draft_week runs, the other
+	// worker drafts a later week with Pad Thai too and stores it first.
+	started, release := make(chan struct{}), make(chan struct{})
+	r := e.weekReply("", fullWeek...)
+	r.Started, r.Release = started, release
+	e.model.QueueGenerate(r)
+	d, err := e.svc.StartDraft(t.Context(), week, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	<-started
+	later := mustDate("2099-01-05")
+	laterDates := []string{"2099-01-05", "2099-01-06", "2099-01-07", "2099-01-08", "2099-01-09", "2099-01-10", "2099-01-11"}
+	e.model.QueueGenerate(e.weekReplyOn(laterDates, "", fullWeek...))
+	other, err := e.svc.StartDraft(t.Context(), later, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if job := e.waitJob(t, other.JobID); job.Status != jobs.StatusSucceeded {
+		t.Fatalf("later week's draft %s %v", job.Status, job.Error)
+	}
+	close(release)
+	job := e.waitJob(t, d.JobID)
+	if job.Status != jobs.StatusFailed || *job.Error != plan.ReasonPoolChanged {
+		t.Fatalf("job %s %v, want failed %s", job.Status, job.Error, plan.ReasonPoolChanged)
+	}
+	if _, err := e.svc.Get(t.Context(), week); !errors.Is(err, plan.ErrNotFound) {
+		t.Errorf("Get = %v, want ErrNotFound: no partial plan", err)
+	}
+}
+
+func TestDraftFailsWithNotEnoughDinners(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	if _, err := e.st.Writer.ExecContext(t.Context(), `UPDATE dinners SET status = 'archived' WHERE id = ?`, e.ids["Pad Thai"]); err != nil {
+		t.Fatal(err)
+	}
+	job := e.draft(t, false)
+	if job.Status != jobs.StatusFailed || *job.Error != plan.ReasonNotEnoughDinners {
+		t.Fatalf("job %s %v, want failed %s", job.Status, job.Error, plan.ReasonNotEnoughDinners)
+	}
+	if n := len(e.model.Requests()); n != 0 {
+		t.Errorf("model called %d times", n)
+	}
+	if _, err := e.svc.Get(t.Context(), week); !errors.Is(err, plan.ErrNotFound) {
+		t.Errorf("Get = %v, want ErrNotFound", err)
+	}
+}
+
+func TestDraftFailsWhenAIFails(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.model.QueueGenerate(llm.GenerateResult{Err: errors.New("provider down")})
+	job := e.draft(t, false)
+	if job.Status != jobs.StatusFailed || *job.Error != plan.ReasonAIFailed {
+		t.Fatalf("job %s %v, want failed %s", job.Status, job.Error, plan.ReasonAIFailed)
+	}
+	if _, err := e.svc.Get(t.Context(), week); !errors.Is(err, plan.ErrNotFound) {
+		t.Errorf("Get = %v, want ErrNotFound", err)
+	}
+}
+
+func TestStartDraftIsSingleFlight(t *testing.T) {
+	e := newEnv(t)
+	first, err := e.svc.StartDraft(t.Context(), week, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	again, err := e.svc.StartDraft(t.Context(), week, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !first.Created || again.Created || again.JobID != first.JobID {
+		t.Fatalf("drafts = %+v then %+v, want the second to join the first", first, again)
+	}
+	other, err := e.svc.StartDraft(t.Context(), mustDate("2026-10-19"), false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !other.Created || other.JobID == first.JobID {
+		t.Errorf("another week's draft = %+v, want its own job", other)
+	}
+}
+
+func TestSimultaneousStartDraftsShareOneJob(t *testing.T) {
+	for _, confirmFirst := range []bool{false, true} {
+		t.Run(fmt.Sprintf("first confirm %v", confirmFirst), func(t *testing.T) {
+			e := newEnv(t)
+			first, err := e.svc.StartDraft(t.Context(), week, confirmFirst)
+			if err != nil {
+				t.Fatal(err)
+			}
+			// Twenty simultaneous drafts, half of them confirmed: every
+			// one joins the queued job, except a confirmed one while the
+			// job is unconfirmed, which is refused.
+			const n = 20
+			drafts := make([]plan.Draft, n)
+			errs := make([]error, n)
+			var wg sync.WaitGroup
+			for i := range n {
+				wg.Go(func() {
+					drafts[i], errs[i] = e.svc.StartDraft(context.Background(), week, i%2 == 1)
+				})
+			}
+			wg.Wait()
+			for i, d := range drafts {
+				if i%2 == 1 && !confirmFirst {
+					if !errors.Is(errs[i], plan.ErrDraftRunning) {
+						t.Errorf("confirmed draft %d = %+v, %v, want ErrDraftRunning", i, d, errs[i])
+					}
+					continue
+				}
+				if errs[i] != nil || d.JobID != first.JobID || d.Created {
+					t.Errorf("draft %d = %+v, %v, want it to join %s", i, d, errs[i], first.JobID)
+				}
+			}
+			var queued int
+			if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM jobs WHERE kind = ?`, plan.KindDraftWeek).Scan(&queued); err != nil {
+				t.Fatal(err)
+			}
+			if queued != 1 {
+				t.Errorf("%d draft jobs, want 1", queued)
+			}
+		})
+	}
+}
+
+func TestConfirmedDraftWhileUnconfirmedDraftRuns(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("first", fullWeek...)
+	e.mustDraft(t, false)
+
+	// An unconfirmed redraft is running when the plan is synced; the
+	// household then confirms a redraft. With a second worker idle, a
+	// second job would draft alongside the first, so the confirmed draft
+	// is refused and only the first job runs draft_week.
+	reversed := slices.Clone(fullWeek)
+	slices.Reverse(reversed)
+	started, release := make(chan struct{}), make(chan struct{})
+	r := e.weekReply("unconfirmed", fullWeek...)
+	r.Started, r.Release = started, release
+	e.model.QueueGenerate(r)
+	e.reply("concurrent", reversed...)
+	unconfirmed, err := e.svc.StartDraft(t.Context(), week, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	<-started
+	e.setStatus(t, plan.StatusSynced)
+	if d, err := e.svc.StartDraft(t.Context(), week, true); !errors.Is(err, plan.ErrDraftRunning) {
+		t.Fatalf("confirmed draft = %+v, %v, want ErrDraftRunning", d, err)
+	}
+	close(release)
+	if job := e.waitJob(t, unconfirmed.JobID); job.Status != jobs.StatusFailed || *job.Error != plan.ReasonConfirmRequired {
+		t.Errorf("unconfirmed job %s %v, want failed %s", job.Status, job.Error, plan.ReasonConfirmRequired)
+	}
+	var queued int
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM jobs WHERE kind = ?`, plan.KindDraftWeek).Scan(&queued); err != nil {
+		t.Fatal(err)
+	}
+	if queued != 2 {
+		t.Errorf("%d draft jobs, want the first and the unconfirmed redraft", queued)
+	}
+	p, err := e.svc.Get(t.Context(), week)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Status != plan.StatusSynced || *p.AINote != "first" || !slices.Equal(dayNames(p), fullWeek) {
+		t.Errorf("plan = %s %q %v, want the synced first draft", p.Status, *p.AINote, dayNames(p))
+	}
+
+	// Asked again once the unconfirmed job has finished, the confirmed
+	// draft replaces the plan.
+	if p := e.mustDraft(t, true); p.Status != plan.StatusChanged || *p.AINote != "concurrent" || !slices.Equal(dayNames(p), reversed) {
+		t.Errorf("plan = %s %q %v, want the confirmed draft, changed", p.Status, *p.AINote, dayNames(p))
+	}
+}
+
+func TestDraftFailsWhenPlanSwappedWhileDrafting(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("first", fullWeek...)
+	e.mustDraft(t, false)
+
+	// The household swaps Wednesday while draft_week runs; the draft must
+	// not erase the swap.
+	reversed := slices.Clone(fullWeek)
+	slices.Reverse(reversed)
+	started, release := make(chan struct{}), make(chan struct{})
+	r := e.weekReply("second", reversed...)
+	r.Started, r.Release = started, release
+	e.model.QueueGenerate(r)
+	d, err := e.svc.StartDraft(t.Context(), week, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	<-started
+	e.ids["Fish Tacos"] = e.dinner(t, "Fish Tacos", "regular", "stovetop", 25)
+	if _, err := e.svc.Swap(t.Context(), week, "2026-10-14", e.ids["Fish Tacos"]); err != nil {
+		t.Fatal(err)
+	}
+	close(release)
+	job := e.waitJob(t, d.JobID)
+	if job.Status != jobs.StatusFailed || *job.Error != plan.ReasonPlanChanged {
+		t.Fatalf("job %s %v, want failed %s", job.Status, job.Error, plan.ReasonPlanChanged)
+	}
+	p, err := e.svc.Get(t.Context(), week)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := slices.Clone(fullWeek)
+	want[2] = "Fish Tacos"
+	if *p.AINote != "first" || !slices.Equal(dayNames(p), want) {
+		t.Errorf("plan = %q %v, want the first draft with the swap %v", *p.AINote, dayNames(p), want)
+	}
+
+	// A draft after the swap replaces the plan.
+	e.reply("third", reversed...)
+	if p := e.mustDraft(t, false); *p.AINote != "third" || !slices.Equal(dayNames(p), reversed) {
+		t.Errorf("redraft after the swap = %q %v, want the third draft", *p.AINote, dayNames(p))
+	}
+}
+
+func TestRedraftOverDraftNeedsNoConfirm(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("first", fullWeek...)
+	first := e.mustDraft(t, false)
+	reversed := slices.Clone(fullWeek)
+	slices.Reverse(reversed)
+	e.reply("second", reversed...)
+	second := e.mustDraft(t, false)
+	if second.ID != first.ID || second.Status != plan.StatusDraft || *second.AINote != "second" {
+		t.Errorf("redraft = %s %s %v, want plan %s draft \"second\"", second.ID, second.Status, *second.AINote, first.ID)
+	}
+	if got := dayNames(second); !slices.Equal(got, reversed) {
+		t.Errorf("days = %v, want %v", got, reversed)
+	}
+}
+
+func TestDraftOverSyncedOrChangedPlanNeedsConfirm(t *testing.T) {
+	for _, status := range []string{plan.StatusSynced, plan.StatusChanged} {
+		t.Run(status, func(t *testing.T) {
+			e := newEnv(t)
+			e.start(t)
+			e.reply("first", fullWeek...)
+			first := e.mustDraft(t, false)
+			e.setStatus(t, status)
+			// Push to Calendar records each day's event id.
+			if _, err := e.st.Writer.ExecContext(t.Context(), `UPDATE plan_days SET calendar_event_id = 'ev-' || date`); err != nil {
+				t.Fatal(err)
+			}
+
+			if _, err := e.svc.StartDraft(t.Context(), week, false); !errors.Is(err, plan.ErrConfirmRequired) {
+				t.Fatalf("StartDraft without confirm = %v, want ErrConfirmRequired", err)
+			}
+			var queued int
+			if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM jobs WHERE kind = ?`, plan.KindDraftWeek).Scan(&queued); err != nil {
+				t.Fatal(err)
+			}
+			if queued != 1 {
+				t.Errorf("%d draft jobs, want only the first", queued)
+			}
+
+			reversed := slices.Clone(fullWeek)
+			slices.Reverse(reversed)
+			e.reply("second", reversed...)
+			p := e.mustDraft(t, true)
+			if p.ID != first.ID || p.Status != plan.StatusChanged || p.CalendarSyncedAt == nil {
+				t.Errorf("confirmed redraft = %s %s synced %v, want plan %s changed, still synced once", p.ID, p.Status, p.CalendarSyncedAt, first.ID)
+			}
+			if got := dayNames(p); !slices.Equal(got, reversed) {
+				t.Errorf("days = %v, want %v", got, reversed)
+			}
+			var events int
+			if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM plan_days WHERE calendar_event_id = 'ev-' || date`).Scan(&events); err != nil {
+				t.Fatal(err)
+			}
+			if events != 7 {
+				t.Errorf("%d days kept their calendar event id, want 7", events)
+			}
+		})
+	}
+}
+
+func TestDraftFailsWhenPlanSyncedAfterAskingWithoutConfirm(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("first", fullWeek...)
+	e.mustDraft(t, false)
+
+	// The redraft is asked for while the plan is draft; the plan is synced
+	// while draft_week runs, so the draft must not replace it.
+	reversed := slices.Clone(fullWeek)
+	slices.Reverse(reversed)
+	started, release := make(chan struct{}), make(chan struct{})
+	r := e.weekReply("second", reversed...)
+	r.Started, r.Release = started, release
+	e.model.QueueGenerate(r)
+	d, err := e.svc.StartDraft(t.Context(), week, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	<-started
+	e.setStatus(t, plan.StatusSynced)
+	close(release)
+	job := e.waitJob(t, d.JobID)
+	if job.Status != jobs.StatusFailed || *job.Error != plan.ReasonConfirmRequired {
+		t.Fatalf("job %s %v, want failed %s", job.Status, job.Error, plan.ReasonConfirmRequired)
+	}
+	p, err := e.svc.Get(t.Context(), week)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Status != plan.StatusSynced || *p.AINote != "first" || !slices.Equal(dayNames(p), fullWeek) {
+		t.Errorf("plan = %s %q %v, want the synced first draft", p.Status, *p.AINote, dayNames(p))
+	}
+}
+
+func TestParseWeekStart(t *testing.T) {
+	if d, err := plan.ParseWeekStart("2026-10-12"); err != nil || d != week {
+		t.Errorf("ParseWeekStart(Monday) = %v, %v", d, err)
+	}
+	// 2026-02-30 and 2027-02-29 would be Mondays were they dates.
+	for _, s := range []string{"2026-10-13", "2026-10-18", "2026-10-5", "2026-02-30", "2027-02-29", "2026-13-05", "next-week", ""} {
+		var invalid *plan.InvalidWeekError
+		if _, err := plan.ParseWeekStart(s); !errors.As(err, &invalid) {
+			t.Errorf("ParseWeekStart(%q) = %v, want *InvalidWeekError", s, err)
+		}
+	}
+}
+
+func TestSwapDay(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("", fullWeek...)
+	e.mustDraft(t, false)
+	e.ids["Fish Tacos"] = e.dinner(t, "Fish Tacos", "regular", "stovetop", 25)
+	e.ids["Ramen"] = e.dinner(t, "Ramen", "quest_log", "crockpot", 300)
+
+	// A Quest log dinner is new, and a crock-pot one gets its start_by.
+	p, err := e.svc.Swap(t.Context(), week, "2026-10-14", e.ids["Ramen"])
+	if err != nil {
+		t.Fatal(err)
+	}
+	day := p.Days[2]
+	if day.Dinner.Name != "Ramen" || !day.IsNew || day.StartBy == nil || day.StartBy.Format("15:04") != "12:30" {
+		t.Errorf("Wednesday = %+v, want Ramen, new, start by 12:30", day)
+	}
+	if p.Status != plan.StatusDraft {
+		t.Errorf("status = %s, want a swapped draft to stay draft", p.Status)
+	}
+
+	// A Regular in place of a Quest log dinner is not new.
+	p, err = e.svc.Swap(t.Context(), week, "2026-10-14", e.ids["Fish Tacos"])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if day := p.Days[2]; day.Dinner.Name != "Fish Tacos" || day.IsNew || day.StartBy != nil {
+		t.Errorf("Wednesday = %+v, want Fish Tacos, not new, no start_by", day)
+	}
+	want := slices.Clone(fullWeek)
+	want[2] = "Fish Tacos"
+	if got := dayNames(p); !slices.Equal(got, want) {
+		t.Errorf("days = %v, want %v", got, want)
+	}
+	got, err := e.svc.Get(t.Context(), week)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !slices.Equal(dayNames(got), want) {
+		t.Errorf("Get days = %v, want %v", dayNames(got), want)
+	}
+}
+
+func TestSwapStatusTransitions(t *testing.T) {
+	for _, tc := range []struct{ from, want string }{
+		{plan.StatusDraft, plan.StatusDraft},
+		{plan.StatusSynced, plan.StatusChanged},
+		{plan.StatusChanged, plan.StatusChanged},
+	} {
+		t.Run(tc.from, func(t *testing.T) {
+			e := newEnv(t)
+			e.start(t)
+			e.reply("", fullWeek...)
+			e.mustDraft(t, false)
+			e.setStatus(t, tc.from)
+			fishTacos := e.dinner(t, "Fish Tacos", "regular", "stovetop", 25)
+			p, err := e.svc.Swap(t.Context(), week, "2026-10-12", fishTacos)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if p.Status != tc.want {
+				t.Errorf("status after swap = %s, want %s", p.Status, tc.want)
+			}
+		})
+	}
+}
+
+func TestSwapRefusals(t *testing.T) {
+	e := newEnv(t)
+	e.start(t)
+	e.reply("", fullWeek...)
+	e.mustDraft(t, false)
+	e.setStatus(t, plan.StatusSynced)
+	suggested := e.dinner(t, "Laksa", "suggested", "stovetop", 30)
+	archived := e.dinner(t, "Old Stew", "archived", "", 0)
+
+	var notPlannable *plan.DinnerNotPlannableError
+	var badDay *plan.InvalidDayError
+	for _, tc := range []struct {
+		name      string
+		week      store.LocalDate
+		date, id  string
+		wantError func(error) bool
+	}{
+		{"no plan", mustDate("2026-10-19"), "2026-10-19", e.ids["Pad Thai"], func(err error) bool { return errors.Is(err, plan.ErrNotFound) }},
+		{"unknown dinner", week, "2026-10-12", "no-such-dinner", func(err error) bool { return errors.Is(err, plan.ErrDinnerNotFound) }},
+		{"dinner on another day", week, "2026-10-12", e.ids["Pot Roast"], func(err error) bool { return errors.Is(err, plan.ErrDinnerAlreadyPlanned) }},
+		{"suggested dinner", week, "2026-10-12", suggested, func(err error) bool { return errors.As(err, &notPlannable) }},
+		{"archived dinner", week, "2026-10-12", archived, func(err error) bool { return errors.As(err, &notPlannable) }},
+		{"day of another week", week, "2026-10-19", e.ids["Pad Thai"], func(err error) bool { return errors.As(err, &badDay) }},
+		{"not a date", week, "monday", e.ids["Pad Thai"], func(err error) bool { return errors.As(err, &badDay) }},
+		{"impossible date", week, "2026-10-32", e.ids["Pad Thai"], func(err error) bool { return errors.As(err, &badDay) }},
+	} {
+		if _, err := e.svc.Swap(t.Context(), tc.week, tc.date, tc.id); !tc.wantError(err) {
+			t.Errorf("%s: Swap = %v", tc.name, err)
+		}
+	}
+	p, err := e.svc.Get(t.Context(), week)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Status != plan.StatusSynced || !slices.Equal(dayNames(p), fullWeek) {
+		t.Errorf("plan = %s %v, want it unchanged by refused swaps", p.Status, dayNames(p))
+	}
+}

internal/plan/rotation.go

@@ -0,0 +1,223 @@
+package plan
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"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/store"
+)
+
+// Rotation check decisions (the rotation_reviews.decision column), the
+// household's answer to "Keep it in rotation?" (D-021).
+const (
+	// DecisionKeep makes the tried dinner a Regular.
+	DecisionKeep = "keep"
+	// DecisionDrop ("Not for us") archives it; its name stays among the
+	// passed names, so it is never suggested again.
+	DecisionDrop = "drop"
+	// DecisionNotMade ("We didn't make it") returns it to the Quest log.
+	DecisionNotMade = "not_made"
+)
+
+// decisionStatus is the status each decision moves a tried dinner to. Keep
+// is the only way a tried dinner becomes a Regular: nothing automatic
+// promotes one (D-021).
+var decisionStatus = map[string]string{
+	DecisionKeep:    dinners.StatusRegular,
+	DecisionDrop:    dinners.StatusArchived,
+	DecisionNotMade: dinners.StatusQuestLog,
+}
+
+// ErrReviewNotFound is a decision on a dinner that has never had a
+// Rotation check: it was never tried.
+var ErrReviewNotFound = errors.New("the dinner has no Rotation check")
+
+// ErrNoPendingReview is a decision on a dinner whose Rotation checks are
+// all decided, such as a second decision.
+var ErrNoPendingReview = errors.New("the dinner has no pending Rotation check")
+
+// ErrDinnerNotTried is a decision on a pending Rotation check whose dinner
+// is no longer tried, such as one archived meanwhile.
+var ErrDinnerNotTried = errors.New("the dinner is no longer tried")
+
+// InvalidDecisionError is a decision that is not keep, drop or not_made.
+type InvalidDecisionError struct {
+	Value string
+}
+
+func (e *InvalidDecisionError) Error() string {
+	return fmt.Sprintf("decision %q is not one of keep, drop, not_made", e.Value)
+}
+
+// ReviewDinner is the dinner of a Rotation check.
+type ReviewDinner struct {
+	ID    string  `json:"id"`
+	Name  string  `json:"name"`
+	Photo *string `json:"photo"`
+}
+
+// Review is a pending Rotation check: the dinner tried and the plan date
+// it was planned on.
+type Review struct {
+	Dinner ReviewDinner `json:"dinner"`
+	// PlanDate is household-local, YYYY-MM-DD.
+	PlanDate string `json:"plan_date"`
+}
+
+// Decided is a Rotation check as decided.
+type Decided struct {
+	Dinner   ReviewDinner `json:"dinner"`
+	PlanDate string       `json:"plan_date"`
+	Decision string       `json:"decision"`
+	// DinnerStatus is the status the decision moved the dinner to.
+	DinnerStatus string `json:"dinner_status"`
+	DecidedAt    string `json:"decided_at"`
+	UpdatedBy    string `json:"updated_by"`
+}
+
+// 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.
+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 {
+		q := db.New(tx)
+		ids, err := q.ListTriedCandidates(ctx, date.String())
+		if err != nil {
+			return fmt.Errorf("plan: list Quest log dinners planned on %s: %w", date, err)
+		}
+		now := store.Now().String()
+		for _, id := range ids {
+			moved, err := q.MarkDinnerTried(ctx, db.MarkDinnerTriedParams{UpdatedAt: now, ID: id})
+			if err != nil {
+				return fmt.Errorf("plan: mark %s tried: %w", id, err)
+			}
+			if moved != 1 {
+				return fmt.Errorf("plan: dinner %s left the Quest log while marking it tried", id)
+			}
+			if err := q.CreateRotationReview(ctx, db.CreateRotationReviewParams{
+				ID: store.NewID(), DinnerID: id, PlanDate: date.String(), CreatedAt: now, UpdatedAt: now,
+			}); err != nil {
+				return fmt.Errorf("plan: open Rotation check of %s for %s: %w", id, date, err)
+			}
+		}
+		n = len(ids)
+		return nil
+	})
+	if err != nil {
+		return 0, err
+	}
+	return n, nil
+}
+
+// PendingReviews returns the pending Rotation checks, oldest plan date
+// first.
+func (s *Service) PendingReviews(ctx context.Context) ([]Review, error) {
+	rows, err := db.New(s.st.Reader).ListPendingRotationReviews(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("plan: list pending Rotation checks: %w", err)
+	}
+	out := make([]Review, len(rows))
+	for i, r := range rows {
+		out[i] = Review{Dinner: reviewDinner(r.Dinner), PlanDate: r.PlanDate}
+	}
+	return out, nil
+}
+
+// DecideReview applies decision to the pending Rotation check of dinnerID
+// and closes it, recording updatedBy: keep makes the dinner a Regular,
+// drop archives it and not_made returns it to the Quest log; its origin is
+// kept; a drop records the dinner's name on the check, so renaming the
+// dinner later never takes it off the passed names. An unknown dinner is
+// ErrDinnerNotFound, a dinner never checked ErrReviewNotFound, one whose
+// checks are all decided (such as a second decision) ErrNoPendingReview,
+// and one no longer tried ErrDinnerNotTried; none of them changes anything.
+func (s *Service) DecideReview(ctx context.Context, dinnerID, decision, updatedBy string) (Decided, error) {
+	status, ok := decisionStatus[decision]
+	if !ok {
+		return Decided{}, &InvalidDecisionError{Value: decision}
+	}
+	if updatedBy == "" {
+		return Decided{}, errors.New("plan: decide Rotation check: no member to record as updated_by")
+	}
+	var out Decided
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		d, err := q.GetDinner(ctx, dinnerID)
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrDinnerNotFound
+		}
+		if err != nil {
+			return fmt.Errorf("plan: read dinner %s: %w", dinnerID, err)
+		}
+		review, err := q.GetPendingRotationReview(ctx, d.ID)
+		if errors.Is(err, sql.ErrNoRows) {
+			checks, err := q.CountRotationReviews(ctx, d.ID)
+			if err != nil {
+				return fmt.Errorf("plan: count Rotation checks of %s: %w", d.ID, err)
+			}
+			if checks == 0 {
+				return ErrReviewNotFound
+			}
+			return ErrNoPendingReview
+		}
+		if err != nil {
+			return fmt.Errorf("plan: read Rotation check of %s: %w", d.ID, err)
+		}
+		now := store.Now().String()
+		moved, err := q.MoveTriedDinner(ctx, db.MoveTriedDinnerParams{
+			Status:    status,
+			UpdatedBy: sql.NullString{String: updatedBy, Valid: true},
+			UpdatedAt: now,
+			ID:        d.ID,
+		})
+		if err != nil {
+			return fmt.Errorf("plan: move %s to %s: %w", d.ID, status, err)
+		}
+		if moved != 1 {
+			return ErrDinnerNotTried
+		}
+		closed, err := q.DecideRotationReview(ctx, db.DecideRotationReviewParams{
+			Decision:  sql.NullString{String: decision, Valid: true},
+			Name:      sql.NullString{String: d.Name, Valid: decision == DecisionDrop},
+			Now:       sql.NullString{String: now, Valid: true},
+			UpdatedBy: sql.NullString{String: updatedBy, Valid: true},
+			ID:        review.ID,
+		})
+		if err != nil {
+			return fmt.Errorf("plan: close Rotation check %s: %w", review.ID, err)
+		}
+		if closed != 1 {
+			return fmt.Errorf("plan: Rotation check %s was decided while deciding it", review.ID)
+		}
+		out = Decided{
+			Dinner:       reviewDinner(d),
+			PlanDate:     review.PlanDate,
+			Decision:     decision,
+			DinnerStatus: status,
+			DecidedAt:    now,
+			UpdatedBy:    updatedBy,
+		}
+		return nil
+	})
+	if err != nil {
+		return Decided{}, err
+	}
+	return out, nil
+}
+
+func reviewDinner(d db.Dinner) ReviewDinner {
+	out := ReviewDinner{ID: d.ID, Name: d.Name}
+	if d.PhotoID.Valid {
+		u := dinners.PhotoURL(d.PhotoID.String)
+		out.Photo = &u
+	}
+	return out
+}

internal/plan/rotation_test.go

@@ -0,0 +1,379 @@
+package plan_test
+
+import (
+	"database/sql"
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/db"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/plan"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+const reviewer = "member-1"
+
+// Pad Thai and Shawarma Bowls, the seeded Quest log dinners, are planned
+// on these days of fullWeek.
+var (
+	padThaiDay  = mustDate("2026-10-14")
+	shawarmaDay = mustDate("2026-10-16")
+)
+
+// putWeek stores fullWeek as the plan of week with status, as a draft and
+// Push to Calendar would.
+func (e *env) putWeek(t *testing.T, status string) {
+	t.Helper()
+	q := db.New(e.st.Writer)
+	now := store.Now().String()
+	id := store.NewID()
+	if err := q.CreateWeekPlan(t.Context(), db.CreateWeekPlanParams{ID: id, WeekStart: week.String(), CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	for i, name := range fullWeek {
+		if err := q.PutPlanDay(t.Context(), db.PutPlanDayParams{ID: store.NewID(), PlanID: id, Date: weekDates[i],
+			DinnerID: sql.NullString{String: e.ids[name], Valid: true}, CreatedAt: now, UpdatedAt: now}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	e.setStatus(t, status)
+}
+
+func (e *env) dinnerRow(t *testing.T, name string) db.Dinner {
+	t.Helper()
+	d, err := db.New(e.st.Reader).GetDinner(t.Context(), e.ids[name])
+	if err != nil {
+		t.Fatal(err)
+	}
+	return d
+}
+
+// review is a rotation_reviews row as stored.
+type review struct {
+	planDate, status                     string
+	decision, name, decidedAt, updatedBy sql.NullString
+}
+
+func (e *env) reviews(t *testing.T, name string) []review {
+	t.Helper()
+	rows, err := e.st.Reader.QueryContext(t.Context(),
+		`SELECT plan_date, status, decision, name, decided_at, updated_by FROM rotation_reviews WHERE dinner_id = ? ORDER BY plan_date`, e.ids[name])
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rows.Close()
+	var out []review
+	for rows.Next() {
+		var r review
+		if err := rows.Scan(&r.planDate, &r.status, &r.decision, &r.name, &r.decidedAt, &r.updatedBy); err != nil {
+			t.Fatal(err)
+		}
+		out = append(out, r)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func (e *env) markTried(t *testing.T, date store.LocalDate, want int) {
+	t.Helper()
+	n, err := e.svc.MarkTried(t.Context(), date)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n != want {
+		t.Fatalf("MarkTried(%s) = %d, want %d", date, n, want)
+	}
+}
+
+func TestMarkTried(t *testing.T) {
+	e := newEnv(t)
+	// Any plan status: a plan pushed to Calendar and edited still counts.
+	e.putWeek(t, plan.StatusChanged)
+
+	e.markTried(t, padThaiDay, 1)
+	if got := e.dinnerRow(t, "Pad Thai").Status; got != "tried" {
+		t.Errorf("Pad Thai status = %s, want tried", got)
+	}
+	got := e.reviews(t, "Pad Thai")
+	if len(got) != 1 || got[0].planDate != padThaiDay.String() || got[0].status != "pending" ||
+		got[0].decision.Valid || got[0].name.Valid || got[0].decidedAt.Valid || got[0].updatedBy.Valid {
+		t.Fatalf("Pad Thai reviews = %+v, want one pending for %s", got, padThaiDay)
+	}
+	if got := e.dinnerRow(t, "Shawarma Bowls").Status; got != "quest_log" {
+		t.Errorf("Shawarma Bowls, planned on another day, status = %s, want quest_log", got)
+	}
+
+	// Idempotent: a second run moves nothing and opens no second check.
+	e.markTried(t, padThaiDay, 0)
+	if got := e.reviews(t, "Pad Thai"); len(got) != 1 || got[0].status != "pending" {
+		t.Errorf("Pad Thai reviews after a second run = %+v, want the one pending", got)
+	}
+
+	// A day planning a Regular, or with no plan, moves nothing.
+	e.markTried(t, week, 0)
+	e.markTried(t, mustDate("2026-10-20"), 0)
+	if got := e.dinnerRow(t, "Beef Chili").Status; got != "regular" {
+		t.Errorf("Beef Chili status = %s, want regular", got)
+	}
+	if got := e.reviews(t, "Beef Chili"); len(got) != 0 {
+		t.Errorf("Beef Chili reviews = %+v, want none", got)
+	}
+}
+
+// A dinner returned to the Quest log ("We didn't make it") is not marked
+// tried again for the same day.
+func TestMarkTriedAfterNotMade(t *testing.T) {
+	e := newEnv(t)
+	e.putWeek(t, plan.StatusDraft)
+	e.markTried(t, padThaiDay, 1)
+	if _, err := e.svc.DecideReview(t.Context(), e.ids["Pad Thai"], plan.DecisionNotMade, reviewer); err != nil {
+		t.Fatal(err)
+	}
+	e.markTried(t, padThaiDay, 0)
+	if got := e.dinnerRow(t, "Pad Thai").Status; got != "quest_log" {
+		t.Errorf("Pad Thai status = %s, want quest_log", got)
+	}
+	if got := e.reviews(t, "Pad Thai"); len(got) != 1 || got[0].status != "decided" {
+		t.Errorf("Pad Thai reviews = %+v, want the one decided", got)
+	}
+}
+
+func TestPendingReviews(t *testing.T) {
+	e := newEnv(t)
+	e.putWeek(t, plan.StatusDraft)
+	got, err := e.svc.PendingReviews(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 0 {
+		t.Fatalf("pending before MarkTried = %+v, want none", got)
+	}
+
+	e.markTried(t, shawarmaDay, 1)
+	e.markTried(t, padThaiDay, 1)
+	got, err = e.svc.PendingReviews(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []plan.Review{
+		{Dinner: plan.ReviewDinner{ID: e.ids["Pad Thai"], Name: "Pad Thai"}, PlanDate: padThaiDay.String()},
+		{Dinner: plan.ReviewDinner{ID: e.ids["Shawarma Bowls"], Name: "Shawarma Bowls"}, PlanDate: shawarmaDay.String()},
+	}
+	if !slices.Equal(got, want) {
+		t.Errorf("pending = %+v, want %+v", got, want)
+	}
+}
+
+func TestDecideReview(t *testing.T) {
+	for _, tc := range []struct {
+		decision, status string
+	}{
+		{plan.DecisionKeep, "regular"},
+		{plan.DecisionDrop, "archived"},
+		{plan.DecisionNotMade, "quest_log"},
+	} {
+		t.Run(tc.decision, func(t *testing.T) {
+			e := newEnv(t)
+			e.putWeek(t, plan.StatusDraft)
+			e.markTried(t, padThaiDay, 1)
+
+			d, err := e.svc.DecideReview(t.Context(), e.ids["Pad Thai"], tc.decision, reviewer)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if d.Dinner.ID != e.ids["Pad Thai"] || d.Dinner.Name != "Pad Thai" || d.PlanDate != padThaiDay.String() ||
+				d.Decision != tc.decision || d.DinnerStatus != tc.status || d.DecidedAt == "" || d.UpdatedBy != reviewer {
+				t.Errorf("decided = %+v", d)
+			}
+			row := e.dinnerRow(t, "Pad Thai")
+			if row.Status != tc.status || row.Origin != "side_quest" || row.Name != "Pad Thai" || row.UpdatedBy.String != reviewer {
+				t.Errorf("Pad Thai = status %s origin %s name %s updated_by %v, want %s side_quest Pad Thai %s",
+					row.Status, row.Origin, row.Name, row.UpdatedBy, tc.status, reviewer)
+			}
+			// Only a drop records the dinner's name.
+			wantPassed := tc.decision == plan.DecisionDrop
+			wantName := sql.NullString{}
+			if wantPassed {
+				wantName = sql.NullString{String: "Pad Thai", Valid: true}
+			}
+			got := e.reviews(t, "Pad Thai")
+			if len(got) != 1 || got[0].status != "decided" || got[0].decision.String != tc.decision ||
+				got[0].decidedAt.String != d.DecidedAt || got[0].updatedBy.String != reviewer ||
+				got[0].name != wantName {
+				t.Errorf("reviews = %+v, want one decided %s by %s at %s, named only by a drop", got, tc.decision, reviewer, d.DecidedAt)
+			}
+			if pending, err := e.svc.PendingReviews(t.Context()); err != nil || len(pending) != 0 {
+				t.Errorf("pending after deciding = %+v, %v, want none", pending, err)
+			}
+
+			// A second decision, of any kind, changes nothing.
+			for _, again := range []string{plan.DecisionKeep, plan.DecisionDrop, plan.DecisionNotMade} {
+				if _, err := e.svc.DecideReview(t.Context(), e.ids["Pad Thai"], again, reviewer); !errors.Is(err, plan.ErrNoPendingReview) {
+					t.Errorf("second decision %s: %v, want ErrNoPendingReview", again, err)
+				}
+			}
+			if got := e.dinnerRow(t, "Pad Thai").Status; got != tc.status {
+				t.Errorf("status after a second decision = %s, want %s", got, tc.status)
+			}
+
+			passed, err := db.New(e.st.Reader).ListPassedNames(t.Context())
+			if err != nil {
+				t.Fatal(err)
+			}
+			recent, err := db.New(e.st.Reader).ListRecentPassedNames(t.Context(), 10)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if slices.Contains(passed, "Pad Thai") != wantPassed || slices.Contains(recent, "Pad Thai") != wantPassed {
+				t.Errorf("passed names = %v, recent %v; want Pad Thai among them: %t", passed, recent, wantPassed)
+			}
+		})
+	}
+}
+
+func TestDecideReviewRefused(t *testing.T) {
+	e := newEnv(t)
+	e.putWeek(t, plan.StatusDraft)
+	e.markTried(t, padThaiDay, 1)
+	ctx := t.Context()
+
+	var invalid *plan.InvalidDecisionError
+	if _, err := e.svc.DecideReview(ctx, e.ids["Pad Thai"], "promote", reviewer); !errors.As(err, &invalid) {
+		t.Errorf("decision promote: %v, want *InvalidDecisionError", err)
+	}
+	if _, err := e.svc.DecideReview(ctx, "nope", plan.DecisionKeep, reviewer); !errors.Is(err, plan.ErrDinnerNotFound) {
+		t.Errorf("unknown dinner: %v, want ErrDinnerNotFound", err)
+	}
+	// Never tried: Shawarma Bowls is in the Quest log with no check.
+	if _, err := e.svc.DecideReview(ctx, e.ids["Shawarma Bowls"], plan.DecisionKeep, reviewer); !errors.Is(err, plan.ErrReviewNotFound) {
+		t.Errorf("dinner never tried: %v, want ErrReviewNotFound", err)
+	}
+	if got := e.dinnerRow(t, "Shawarma Bowls").Status; got != "quest_log" {
+		t.Errorf("Shawarma Bowls status = %s, want quest_log", got)
+	}
+	if _, err := e.svc.DecideReview(ctx, e.ids["Pad Thai"], plan.DecisionKeep, ""); err == nil {
+		t.Error("decision with no member succeeded")
+	}
+
+	// A tried dinner archived meanwhile is neither kept nor listed.
+	if _, err := e.st.Writer.ExecContext(ctx, `UPDATE dinners SET status = 'archived' WHERE id = ?`, e.ids["Pad Thai"]); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := e.svc.DecideReview(ctx, e.ids["Pad Thai"], plan.DecisionKeep, reviewer); !errors.Is(err, plan.ErrDinnerNotTried) {
+		t.Errorf("archived dinner: %v, want ErrDinnerNotTried", err)
+	}
+	if got := e.dinnerRow(t, "Pad Thai").Status; got != "archived" {
+		t.Errorf("Pad Thai status = %s, want archived", got)
+	}
+	if got := e.reviews(t, "Pad Thai"); len(got) != 1 || got[0].status != "pending" {
+		t.Errorf("Pad Thai reviews = %+v, want the one still pending", got)
+	}
+	if pending, err := e.svc.PendingReviews(ctx); err != nil || len(pending) != 0 {
+		t.Errorf("pending = %+v, %v, want none for an archived dinner", pending, err)
+	}
+}
+
+// TestOnlyKeepPromotesToRegular guards D-021: no code path but the Rotation
+// check's keep may make an existing dinner a Regular. Every query writing
+// dinners.status and every non-test use of the regular status must be one
+// of those reviewed below; a new one fails here until it is reviewed.
+func TestOnlyKeepPromotesToRegular(t *testing.T) {
+	// Each query writing dinners.status, and why it cannot promote.
+	statusWriters := map[string]string{
+		"CreateDinner":        "inserts a new dinner; only CreateRegular inserts one as a Regular",
+		"UpdateDinner":        "dinners.Service.Update writes the status it read back",
+		"ArchiveDinner":       "sets archived",
+		"MoveSuggestedDinner": "Try it / Pass move a suggested dinner to quest_log or archived",
+		"MarkDinnerTried":     "sets tried",
+		"MoveTriedDinner":     "DecideReview's decisionStatus: only keep maps to regular",
+	}
+	files, err := filepath.Glob("../../migrations/queries/*.sql")
+	if err != nil || len(files) == 0 {
+		t.Fatalf("no query files: %v", err)
+	}
+	writes := regexp.MustCompile(`(?is)^\s*(INSERT\s+INTO\s+dinners\b|UPDATE\s+dinners\s+SET\b.*\bstatus\s*=)`)
+	nameRe := regexp.MustCompile(`^\s*(\w+)`)
+	found := map[string]bool{}
+	for _, f := range files {
+		src, err := os.ReadFile(f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, stmt := range strings.Split(string(src), "-- name:")[1:] {
+			name := nameRe.FindStringSubmatch(stmt)[1]
+			var body []string
+			for _, line := range strings.Split(stmt, "\n")[1:] {
+				if !strings.HasPrefix(strings.TrimSpace(line), "--") {
+					body = append(body, line)
+				}
+			}
+			sqlText := strings.Join(body, "\n")
+			if !writes.MatchString(sqlText) {
+				continue
+			}
+			found[name] = true
+			if _, ok := statusWriters[name]; !ok {
+				t.Errorf("%s: query %s writes dinners.status; review it against D-021 and list it here", f, name)
+			}
+			if regexp.MustCompile(`(?i)\bstatus\s*=\s*'regular'`).MatchString(sqlText) {
+				t.Errorf("%s: query %s sets status regular outright", f, name)
+			}
+		}
+	}
+	for name := range statusWriters {
+		if !found[name] {
+			t.Errorf("reviewed query %s no longer writes dinners.status; drop it from the list", name)
+		}
+	}
+
+	// Each non-test Go file naming the regular status, and how often.
+	uses := map[string]int{
+		"dinners/dinners.go":      5, // the constant (2), listable, CreateRegular's status and origin
+		"plan/plan.go":            1, // plannable
+		"plan/rotation.go":        1, // decisionStatus[DecisionKeep]
+		"suggest/batch.go":        1, // reads which dinners are Regulars to cite
+		"ai/harness/context.go":   1, // reads the Regulars
+		"ai/skills/draft_week.go": 1, // KindRegular, a planned day's label
+	}
+	regular := regexp.MustCompile(`StatusRegular\b|"regular"`)
+	got := map[string]int{}
+	err = filepath.WalkDir("..", func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() && d.Name() == "db" {
+			return filepath.SkipDir // generated; the queries are checked above
+		}
+		if d.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+			return nil
+		}
+		src, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		if n := len(regular.FindAllIndex(src, -1)); n > 0 {
+			got[filepath.ToSlash(strings.TrimPrefix(path, ".."+string(filepath.Separator)))] = n
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for path, n := range got {
+		if uses[path] != n {
+			t.Errorf("%s names the regular status %d times, reviewed %d; review it against D-021", path, n, uses[path])
+		}
+	}
+	for path, n := range uses {
+		if got[path] == 0 {
+			t.Errorf("%s no longer names the regular status (reviewed %d); update the list", path, n)
+		}
+	}
+}

internal/server/aisettings_test.go

@@ -28,8 +28,8 @@ const (
 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), newTestDinners(t),
-		newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t),
+		newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/dinners.go

@@ -205,7 +205,8 @@ func actorOrFail(w http.ResponseWriter, r *http.Request, logger *slog.Logger) (a
 // an archived dinner is 409 dinner_archived and one changed while grounding
 // 409 ground_conflict. Any other grounding failure, by candidate, link or
 // manual recipe, wraps dinners.ErrGroundFailed and is 500, logged by reason
-// and dinner id only.
+// and dinner id only, as is any other failure finding candidates, which
+// wraps dinners.ErrCandidatesFailed.
 func writeDinnerError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
 	var invalid *dinners.ValidationError
 	var dup *dinners.DuplicateError
@@ -231,6 +232,12 @@ func writeDinnerError(w http.ResponseWriter, r *http.Request, logger *slog.Logge
 		// logged.
 		logger.ErrorContext(r.Context(), action, "reason", "ground_failed", "dinner_id", chi.URLParam(r, "id"))
 		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	case errors.Is(err, dinners.ErrCandidatesFailed):
+		// The error may quote a candidate's URL, which can carry a
+		// personal token, and dependency errors, so only the reason and
+		// dinner are logged.
+		logger.ErrorContext(r.Context(), action, "reason", "candidates_failed", "dinner_id", chi.URLParam(r, "id"))
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
 	case errors.Is(err, dinners.ErrArchived):
 		writeError(w, r, logger, http.StatusConflict, "dinner_archived", "the dinner is archived")
 	case errors.Is(err, dinners.ErrGroundConflict):

internal/server/dinners_test.go

@@ -11,9 +11,11 @@ import (
 	"sync"
 	"testing"
 	"testing/fstest"
+	"time"
 
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/ai/llm"
 	"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/recipes"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
@@ -66,6 +68,10 @@ func (b *logBuffer) String() string {
 func newDinnersEnv(t *testing.T) *dinnersEnv {
 	t.Helper()
 	st := newTestStore(t)
+	// The Quest log is read against the household's current week.
+	if err := household.SeedSettings(context.Background(), st, "America/New_York"); err != nil {
+		t.Fatal(err)
+	}
 	e := &dinnersEnv{
 		st:     st,
 		search: &recipestest.Search{Results: map[string][]recipes.Candidate{}},
@@ -86,7 +92,7 @@ func newDinnersEnv(t *testing.T) *dinnersEnv {
 		t.Fatal(err)
 	}
 	e.h, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
-		svc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		svc, newTestSuggest(t), newTestPlan(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -292,9 +298,11 @@ func TestDinnerResponsesHideTokenInLinkPath(t *testing.T) {
 	if rec.Code != http.StatusConflict {
 		t.Fatalf("same link again = %d, want 409: %s", rec.Code, rec.Body)
 	}
+	// Each secret holds a character no ULID has (Crockford base32 has no I,
+	// L, O, U, "-", "." or "/"), so the dinner's id never matches one.
 	for _, resp := range []struct{ name, body string }{{"create", created}, {"list", listed}, {"duplicate", rec.Body.String()}} {
 		lower := strings.ToLower(resp.body)
-		for _, secret := range []string{"c.example", "recipes", "key", "abcdefghijklmno"} {
+		for _, secret := range []string{link, "c.example", "recipes/stew", "stew-key", "abcdefghijklmno"} {
 			if strings.Contains(lower, secret) {
 				t.Errorf("%s response contains %q: %s", resp.name, secret, resp.body)
 			}
@@ -414,6 +422,61 @@ func TestListDinnersFiltersByStatus(t *testing.T) {
 	}
 }
 
+// The Quest log leaves out a dinner on the plan for the household's current
+// week or a later one: it is scheduled already. A dinner on an earlier
+// week's plan only, or on none, is listed.
+func TestQuestLogLeavesOutPlannedDinners(t *testing.T) {
+	t.Parallel()
+	router, st := newDinnersRouter(t)
+	ctx := context.Background()
+	names := []string{"Bibimbap", "Gumbo", "Pho", "Ramen", "Tagine"}
+	ids := map[string]string{}
+	for _, name := range names {
+		id := createDinner(t, router, `{"name":"`+name+`"}`)
+		if _, err := st.Writer.ExecContext(ctx, `UPDATE dinners SET status = 'quest_log', origin = 'side_quest' WHERE id = ?`, id); err != nil {
+			t.Fatal(err)
+		}
+		ids[name] = id
+	}
+
+	loc, err := time.LoadLocation("America/New_York")
+	if err != nil {
+		t.Fatal(err)
+	}
+	thisWeek := household.WeekStart(household.Today(time.Now(), loc))
+	// day is the date days after the Monday weeks after this week's.
+	day := func(weeks, days int) string {
+		y, m, d := thisWeek.Date()
+		return time.Date(y, m, d+7*weeks+days, 0, 0, 0, 0, time.UTC).Format(time.DateOnly)
+	}
+	// Gumbo is on last week's plan only; Pho on this week's; Ramen on the
+	// week after next; Tagine on last week's and this week's.
+	plan := func(weeks int, dinners ...string) {
+		t.Helper()
+		weekStart := day(weeks, 0)
+		planID := "plan-" + weekStart
+		if _, err := st.Writer.ExecContext(ctx,
+			`INSERT INTO week_plans (id, week_start, status, created_at, updated_at) VALUES (?, ?, 'draft', 't', 't')`,
+			planID, weekStart); err != nil {
+			t.Fatal(err)
+		}
+		for i, name := range dinners {
+			if _, err := st.Writer.ExecContext(ctx,
+				`INSERT INTO plan_days (id, plan_id, date, dinner_id, is_new, created_at, updated_at) VALUES (?, ?, ?, ?, 1, 't', 't')`,
+				planID+"-"+name, planID, day(weeks, i), ids[name]); err != nil {
+				t.Fatal(err)
+			}
+		}
+	}
+	plan(-1, "Gumbo", "Tagine")
+	plan(0, "Pho", "Tagine")
+	plan(2, "Ramen")
+
+	if got := strings.Join(listNames(t, router, "quest_log"), ","); got != "Bibimbap,Gumbo" {
+		t.Errorf("quest_log = %s, want Bibimbap,Gumbo", got)
+	}
+}
+
 func TestPatchDinner(t *testing.T) {
 	t.Parallel()
 	router, st := newDinnersRouter(t)

internal/server/grounding_test.go

@@ -68,6 +68,27 @@ func listedDinner(t *testing.T, h http.Handler, id string) map[string]any {
 	return nil
 }
 
+// candidateID returns the candidate_id GET recipe-candidates offers dinner
+// id for the page titled title.
+func candidateID(t *testing.T, h http.Handler, id, title string) string {
+	t.Helper()
+	rec, body := callDinners(t, h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET candidates = %d: %s", rec.Code, rec.Body)
+	}
+	for _, c := range body["candidates"].([]any) {
+		if c := c.(map[string]any); c["title"] == title {
+			cid := c["candidate_id"].(string)
+			if strings.Contains(cid, "://") {
+				t.Fatalf("candidate_id = %q, want an opaque id, not the page URL", cid)
+			}
+			return cid
+		}
+	}
+	t.Fatalf("candidates = %v, want one titled %q", body, title)
+	return ""
+}
+
 func TestPostDinnerReturnsBeforeGroundingCompletes(t *testing.T) {
 	t.Parallel()
 	e := newDinnersEnv(t).withRecipes(t)
@@ -138,8 +159,11 @@ func TestGetRecipeCandidates(t *testing.T) {
 		t.Fatalf("candidates = %v, want 2", body)
 	}
 	first := list[0].(map[string]any)
+	if cid, _ := first["candidate_id"].(string); cid == "" || strings.Contains(cid, "a.example") {
+		t.Errorf("candidate_id = %#v, want an opaque id", first["candidate_id"])
+	}
 	want := map[string]any{
-		"candidate_id": curryPage,
+		"candidate_id": first["candidate_id"],
 		"title":        "Chicken Curry",
 		"site_name":    "Curry House",
 		"photo_url":    nil,
@@ -180,13 +204,65 @@ func TestGetRecipeCandidatesSearchFails(t *testing.T) {
 	}
 }
 
+// TestGetRecipeCandidatesStoredLookupFailure: a candidate whose stored
+// recipe cannot be read, or is stored incomplete, is a 500 logged by reason
+// and dinner id, never with the candidate's URL, which can carry a personal
+// token, or the database error.
+func TestGetRecipeCandidatesStoredLookupFailure(t *testing.T) {
+	t.Parallel()
+	const (
+		token = "personal-token-abc123"
+		host  = "secret-candidate.example"
+		page  = "https://" + host + "/curry?access_token=" + token
+	)
+	for _, tc := range []struct {
+		name, sabotage string
+		leaks          []string
+	}{
+		// Renaming a column the lookup selects fails the read.
+		{"lookup", `ALTER TABLE recipes RENAME COLUMN yield TO yield_gone`, []string{"no such column", "yield"}},
+		// A recipe stored without its photo, method or difficulty is
+		// incomplete.
+		{"incomplete", `INSERT INTO recipes (id, source_url, title, raw_jsonld, fetched_at, created_at, updated_at)
+			VALUES ('r-incomplete', '` + page + `', 'Curry', '{}', 'now', 'now', 'now')`, []string{"r-incomplete", "no photo"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			e := newDinnersEnv(t)
+			e.search.Results["Chicken curry"] = []recipes.Candidate{{URL: page}}
+			id := createDinner(t, e.h, `{"name":"Chicken curry"}`) // runner not started: stays pending
+			if _, err := e.st.Writer.ExecContext(t.Context(), tc.sabotage); err != nil {
+				t.Fatal(err)
+			}
+
+			rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+			if rec.Code != http.StatusInternalServerError || errorCode(body) != "internal" {
+				t.Errorf("GET = %d %s, want 500 internal", rec.Code, rec.Body)
+			}
+			logs := e.logs.String()
+			for _, secret := range append([]string{page, host, token, "access_token"}, tc.leaks...) {
+				if strings.Contains(rec.Body.String(), secret) {
+					t.Errorf("response contains %q: %s", secret, rec.Body)
+				}
+				if strings.Contains(logs, secret) {
+					t.Errorf("logs contain %q: %s", secret, logs)
+				}
+			}
+			if !strings.Contains(logs, "reason=candidates_failed") || !strings.Contains(logs, "dinner_id="+id) {
+				t.Errorf("logs = %q, want reason=candidates_failed and the dinner id", logs)
+			}
+		})
+	}
+}
+
 func TestPostGroundViaCandidate(t *testing.T) {
 	t.Parallel()
 	e := newDinnersEnv(t).withRecipes(t)
 	id := createDinner(t, e.h, `{"name":"Chicken curry"}`)
 	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
 
-	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"candidate_id":"`+curry2Page+`"}`)
+	cid := candidateID(t, e.h, id, "Weeknight Curry")
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"candidate_id":"`+cid+`"}`)
 	if rec.Code != http.StatusOK {
 		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
 	}
@@ -198,12 +274,81 @@ func TestPostGroundViaCandidate(t *testing.T) {
 	// The candidate is now stored, so it is offered with its photo.
 	_, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
 	for _, c := range body["candidates"].([]any) {
-		if c := c.(map[string]any); c["candidate_id"] == curry2Page && c["photo_url"] != photo {
+		if c := c.(map[string]any); c["candidate_id"] == cid && c["photo_url"] != photo {
 			t.Errorf("grounded candidate photo_url = %v, want %s", c["photo_url"], photo)
 		}
 	}
 }
 
+// TestRecipeCandidatesHideTokenURLs: a candidate page whose URL carries a
+// token in its path or query is offered by an opaque id alone, which
+// grounds the dinner in that page.
+func TestRecipeCandidatesHideTokenURLs(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t)
+	const (
+		pathToken  = "path-token-abc123"
+		queryToken = "query-token-def456"
+		pathPage   = "https://secret-path.example/u/" + pathToken + "/chicken-curry"
+		queryPage  = "https://secret-query.example/curry?access_token=" + queryToken
+	)
+	e.search.Results["Chicken curry"] = []recipes.Candidate{{URL: pathPage}, {URL: queryPage}}
+	e.pages.Bodies[pathPage] = recipestest.RecipePage("Chicken Curry", "Curry House", "https://a.example/curry.jpg", 40)
+	e.pages.Bodies[queryPage] = recipestest.RecipePage("Weeknight Curry", "B Kitchen", "https://b.example/curry.jpg", 25)
+	e.images.JPEGs["https://b.example/curry.jpg"] = recipestest.JPEG(t, 400, 320, 2)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`) // runner not started: stays pending
+
+	rec, body := callDinners(t, e.h, http.MethodGet, dinnersPath+"/"+id+"/recipe-candidates", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET = %d: %s", rec.Code, rec.Body)
+	}
+	if list, _ := body["candidates"].([]any); len(list) != 2 {
+		t.Fatalf("candidates = %v, want 2", body)
+	}
+	for _, secret := range []string{pathPage, queryPage, "secret-path.example", "secret-query.example", pathToken, queryToken, "access_token"} {
+		if strings.Contains(rec.Body.String(), secret) {
+			t.Errorf("candidates response contains %q: %s", secret, rec.Body)
+		}
+	}
+
+	e.model.QueueGenerate(recipestest.NormalizedReply("stovetop", 25))
+	cid := candidateID(t, e.h, id, "Weeknight Curry")
+	rec, d := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+id+"/ground", `{"candidate_id":"`+cid+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+	}
+	if strings.Contains(rec.Body.String(), queryToken) {
+		t.Errorf("ground response contains the token: %s", rec.Body)
+	}
+	var source string
+	if err := e.st.Reader.QueryRow(`SELECT source_url FROM recipes WHERE id = ?`, d["recipe_id"]).Scan(&source); err != nil {
+		t.Fatal(err)
+	}
+	if d["grounding_status"] != "grounded" || source != queryPage {
+		t.Errorf("dinner = %v in recipe %s, want grounded in %s", d, source, queryPage)
+	}
+}
+
+// TestPostGroundRejectsCandidateNotOffered: a candidate_id is only one
+// offered for that dinner; a page URL, or another dinner's candidate, is
+// refused.
+func TestPostGroundRejectsCandidateNotOffered(t *testing.T) {
+	t.Parallel()
+	e := newDinnersEnv(t).withRecipes(t)
+	id := createDinner(t, e.h, `{"name":"Chicken curry"}`)
+	other := createDinner(t, e.h, `{"name":"Pad thai"}`)
+	cid := candidateID(t, e.h, id, "Weeknight Curry")
+	for _, tc := range []struct{ name, dinner, cid string }{
+		{"page URL", id, curry2Page},
+		{"another dinner's", other, cid},
+	} {
+		rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+tc.dinner+"/ground", `{"candidate_id":"`+tc.cid+`"}`)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_dinner" {
+			t.Errorf("%s: %d %v, want 400 invalid_dinner", tc.name, rec.Code, body)
+		}
+	}
+}
+
 func TestPostGroundViaRecipeURL(t *testing.T) {
 	t.Parallel()
 	e := newDinnersEnv(t).withRecipes(t)
@@ -365,7 +510,8 @@ func TestPostGroundRejects(t *testing.T) {
 	for _, tc := range []struct{ name, body, code string }{
 		{"empty", `{}`, "invalid_dinner"},
 		{"two kinds", `{"candidate_id":"https://a.example/x","recipe_url":"https://a.example/x"}`, "invalid_dinner"},
-		{"candidate not a link", `{"candidate_id":"c1"}`, "invalid_dinner"},
+		{"candidate not offered", `{"candidate_id":"c1"}`, "invalid_dinner"},
+		{"candidate a page URL", `{"candidate_id":"https://a.example/x"}`, "invalid_dinner"},
 		{"http link", `{"recipe_url":"http://a.example/x"}`, "invalid_dinner"},
 		{"null", `{"recipe_url":null}`, "invalid_request"},
 		{"unknown field", `{"url":"https://a.example/x"}`, "invalid_request"},

internal/server/jobs.go

@@ -30,7 +30,8 @@ type jobCreated struct {
 }
 
 // postJob serves POST /api/v1/jobs: it enqueues a job of a registered kind
-// and returns 202 with its id, which GET /api/v1/jobs/{id} reports on.
+// that is not service-only and returns 202 with its id, which
+// GET /api/v1/jobs/{id} reports on.
 func postJob(logger *slog.Logger, runner *jobs.Runner) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		req, err := decodeJobRequest(http.MaxBytesReader(w, r.Body, maxJobBody))
@@ -43,6 +44,9 @@ func postJob(logger *slog.Logger, runner *jobs.Runner) http.HandlerFunc {
 		case errors.Is(err, jobs.ErrUnknownKind):
 			writeError(w, r, logger, http.StatusBadRequest, "unknown_kind", "unknown job kind")
 			return
+		case errors.Is(err, jobs.ErrServiceOnly):
+			writeError(w, r, logger, http.StatusBadRequest, "service_only_kind", "job kind is started only by its own endpoint")
+			return
 		case errors.Is(err, jobs.ErrInvalidPayload):
 			writeError(w, r, logger, http.StatusBadRequest, "invalid_payload", "payload does not match the job kind")
 			return

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), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(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), newTestDinners(t), newTestRunner(t),
+	r, err = NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(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), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/plans.go

@@ -0,0 +1,137 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/plan"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// maxPlanBody bounds a POST /plans/{weekStart}/draft or PUT
+// /plans/{weekStart}/days/{date} body.
+const maxPlanBody = 4 << 10
+
+// planDraft is the POST /plans/{weekStart}/draft body. confirm is needed
+// to draft over a plan pushed to Calendar.
+type planDraft struct {
+	Confirm *bool `json:"confirm"`
+}
+
+// planDaySwap is the PUT /plans/{weekStart}/days/{date} body.
+type planDaySwap struct {
+	DinnerID *string `json:"dinner_id"`
+}
+
+// getPlan answers GET /plans/{weekStart} with the week's plan.
+func getPlan(logger *slog.Logger, svc *plan.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		week, ok := weekStartOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		p, err := svc.Get(r.Context(), week)
+		if err != nil {
+			writePlanError(w, r, logger, "read plan", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, p)
+	}
+}
+
+// postPlanDraft enqueues the draft of the week and answers 202 with the
+// jobId that GET /jobs/{id} reports on, without waiting for the job. When
+// a draft of the week is already queued or running, it answers 202 with
+// that job instead, or 409 when this draft is confirmed and that one is
+// not.
+func postPlanDraft(logger *slog.Logger, svc *plan.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		week, ok := weekStartOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		body, err := decodePatch[planDraft](http.MaxBytesReader(w, r.Body, maxPlanBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		d, err := svc.StartDraft(r.Context(), week, body.Confirm != nil && *body.Confirm)
+		if err != nil {
+			writePlanError(w, r, logger, "start plan draft", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusAccepted, d)
+	}
+}
+
+// putPlanDay swaps the dinner of one day of the week's plan and answers
+// with the plan as swapped.
+func putPlanDay(logger *slog.Logger, svc *plan.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		week, ok := weekStartOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		body, err := decodePatch[planDaySwap](http.MaxBytesReader(w, r.Body, maxPlanBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		if body.DinnerID == nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", "dinner_id: required")
+			return
+		}
+		p, err := svc.Swap(r.Context(), week, chi.URLParam(r, "date"), *body.DinnerID)
+		if err != nil {
+			writePlanError(w, r, logger, "swap plan day", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, p)
+	}
+}
+
+// weekStartOrFail parses the {weekStart} path parameter, or answers 400
+// when it is not a Monday date.
+func weekStartOrFail(w http.ResponseWriter, r *http.Request, logger *slog.Logger) (store.LocalDate, bool) {
+	week, err := plan.ParseWeekStart(chi.URLParam(r, "weekStart"))
+	if err != nil {
+		writeError(w, r, logger, http.StatusBadRequest, "invalid_week", err.Error())
+		return store.LocalDate{}, false
+	}
+	return week, true
+}
+
+// writePlanError maps a plan.Service error to its API error: a week with
+// no plan or an unknown dinner is 404, a date outside the week is 400, and
+// drafting over a synced plan without confirm, a confirmed draft while an
+// unconfirmed one runs, planning a dinner that is neither a Regular nor in
+// the Quest log, or one already on another day of the week, is 409.
+func writePlanError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
+	var day *plan.InvalidDayError
+	var week *plan.InvalidWeekError
+	var notPlannable *plan.DinnerNotPlannableError
+	switch {
+	case errors.As(err, &day):
+		writeError(w, r, logger, http.StatusBadRequest, "invalid_date", day.Error())
+	case errors.As(err, &week):
+		writeError(w, r, logger, http.StatusBadRequest, "invalid_week", week.Error())
+	case errors.As(err, &notPlannable):
+		writeError(w, r, logger, http.StatusConflict, "dinner_not_plannable", notPlannable.Error())
+	case errors.Is(err, plan.ErrDinnerAlreadyPlanned):
+		writeError(w, r, logger, http.StatusConflict, "dinner_already_planned", err.Error())
+	case errors.Is(err, plan.ErrConfirmRequired):
+		writeError(w, r, logger, http.StatusConflict, "confirm_required", err.Error())
+	case errors.Is(err, plan.ErrDraftRunning):
+		writeError(w, r, logger, http.StatusConflict, "draft_running", err.Error())
+	case errors.Is(err, plan.ErrNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "plan not found")
+	case errors.Is(err, plan.ErrDinnerNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "dinner not found")
+	default:
+		logger.ErrorContext(r.Context(), action, "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+}

internal/server/plans_test.go

@@ -0,0 +1,326 @@
+package server
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"testing/fstest"
+
+	"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/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/plan"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+const plansPath = "/api/v1/plans/"
+
+// plansEnv is a router whose plan service has an unstarted job runner, so
+// drafts stay queued, over a store holding a draft plan of the week of
+// 2026-10-12: Beef Chili (crock pot, 240 minutes) on Monday and a Regular
+// on every other day. questLog is the id of a Quest log dinner on no plan.
+type plansEnv struct {
+	h        http.Handler
+	st       *store.Store
+	svc      *plan.Service
+	questLog string
+}
+
+func newPlansRouter(t *testing.T) plansEnv {
+	t.Helper()
+	st := newTestStore(t)
+	ctx := t.Context()
+	if err := household.SeedSettings(ctx, 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)
+	}
+	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, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
+		newTestDinners(t), newTestSuggest(t), svc, runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	q := db.New(st.Writer)
+	now := store.Now().String()
+	dinner := func(name, status, method string, minutes int64) string {
+		d, err := q.CreateDinner(ctx, db.CreateDinnerParams{
+			ID: store.NewID(), Name: name, NormalizedName: harness.Normalize(name), Status: status, Origin: "regular",
+			Method:          sql.NullString{String: method, Valid: method != ""},
+			MinutesTotal:    sql.NullInt64{Int64: minutes, Valid: minutes > 0},
+			GroundingStatus: "manual", CreatedAt: now, UpdatedAt: now,
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return d.ID
+	}
+	planID := store.NewID()
+	if err := q.CreateWeekPlan(ctx, db.CreateWeekPlanParams{ID: planID, WeekStart: "2026-10-12",
+		AiNote: sql.NullString{String: "Mostly Regulars.", Valid: true}, CreatedAt: now, UpdatedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	for i, date := range []string{"2026-10-12", "2026-10-13", "2026-10-14", "2026-10-15", "2026-10-16", "2026-10-17", "2026-10-18"} {
+		id := dinner("Regular "+date, "regular", "stovetop", 30)
+		if i == 0 {
+			id = dinner("Beef Chili", "regular", "crockpot", 240)
+		}
+		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 plansEnv{h: h, st: st, svc: svc, questLog: dinner("Pad Thai", "quest_log", "stovetop", 35)}
+}
+
+func (e plansEnv) setStatus(t *testing.T, status string) {
+	t.Helper()
+	if _, err := e.st.Writer.ExecContext(t.Context(), `UPDATE week_plans SET status = ?`, status); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestGetPlan(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+
+	rec, body := callDinners(t, e.h, http.MethodGet, plansPath+"2026-10-12", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET plan = %d: %s", rec.Code, rec.Body)
+	}
+	if body["status"] != "draft" || body["week_start"] != "2026-10-12" || body["week_label"] != "Week 42 · Oct 12 – 18" ||
+		body["ai_note"] != "Mostly Regulars." || body["calendar_synced_at"] != nil {
+		t.Errorf("plan = %v", body)
+	}
+	days, _ := body["days"].([]any)
+	if len(days) != 7 {
+		t.Fatalf("days = %v, want 7", body["days"])
+	}
+	monday := days[0].(map[string]any)
+	if monday["date"] != "2026-10-12" || monday["is_new"] != false || monday["start_by"] != "2026-10-12T13:30:00-04:00" {
+		t.Errorf("Monday = %v", monday)
+	}
+	d := monday["dinner"].(map[string]any)
+	for _, key := range []string{"id", "name", "photo", "minutes", "method", "origin"} {
+		if _, ok := d[key]; !ok {
+			t.Errorf("dinner has no %s: %v", key, d)
+		}
+	}
+	if d["name"] != "Beef Chili" || d["minutes"] != 240.0 || d["method"] != "crockpot" || d["origin"] != "regular" || d["photo"] != nil {
+		t.Errorf("Monday dinner = %v", d)
+	}
+	if tuesday := days[1].(map[string]any); tuesday["start_by"] != nil {
+		t.Errorf("Tuesday start_by = %v, want null for a stovetop dinner", tuesday["start_by"])
+	}
+
+	rec, body = callDinners(t, e.h, http.MethodGet, plansPath+"2026-10-19", "")
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("GET week with no plan = %d %v, want 404 not_found", rec.Code, body)
+	}
+}
+
+func TestPlanWeekStartMustBeMonday(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+
+	for _, tc := range []struct{ method, target, body string }{
+		{http.MethodGet, plansPath + "2026-10-13", ""},
+		{http.MethodGet, plansPath + "not-a-date", ""},
+		{http.MethodGet, plansPath + "2026-02-30", ""},
+		{http.MethodPost, plansPath + "2027-02-29/draft", "{}"},
+		{http.MethodPost, plansPath + "2026-10-18/draft", "{}"},
+		{http.MethodPut, plansPath + "2026-10-14/days/2026-10-14", `{"dinner_id":"` + e.questLog + `"}`},
+	} {
+		rec, body := callDinners(t, e.h, tc.method, tc.target, tc.body)
+		if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_week" {
+			t.Errorf("%s %s = %d %v, want 400 invalid_week", tc.method, tc.target, rec.Code, body)
+		}
+	}
+}
+
+func TestPostPlanDraft(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+
+	rec, body := callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-12/draft", "{}")
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("POST draft = %d: %s", rec.Code, rec.Body)
+	}
+	jobID, _ := body["jobId"].(string)
+	if jobID == "" || len(body) != 1 {
+		t.Fatalf("POST draft = %v, want only a jobId", body)
+	}
+	rec, job := callDinners(t, e.h, http.MethodGet, "/api/v1/jobs/"+jobID, "")
+	if rec.Code != http.StatusOK || job["kind"] != plan.KindDraftWeek || job["status"] != "queued" {
+		t.Errorf("GET job = %d %v, want a queued %s job", rec.Code, job, plan.KindDraftWeek)
+	}
+	// A second draft of the week joins the queued one.
+	rec, body = callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-12/draft", `{"confirm":false}`)
+	if rec.Code != http.StatusAccepted || body["jobId"] != jobID {
+		t.Errorf("second POST draft = %d %v, want 202 with job %s", rec.Code, body, jobID)
+	}
+	// A week with no plan needs no confirm.
+	rec, body = callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-19/draft", "{}")
+	if rec.Code != http.StatusAccepted || body["jobId"] == jobID {
+		t.Errorf("POST draft of a new week = %d %v, want 202 with its own job", rec.Code, body)
+	}
+
+	// A confirmed draft does not join the unconfirmed one and enqueues
+	// nothing.
+	rec, body = callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-12/draft", `{"confirm":true}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "draft_running" {
+		t.Errorf("confirmed POST draft = %d %v, want 409 draft_running", rec.Code, body)
+	}
+	var queued int
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM jobs WHERE kind = ?`, plan.KindDraftWeek).Scan(&queued); err != nil {
+		t.Fatal(err)
+	}
+	if queued != 2 {
+		t.Errorf("%d draft jobs, want one per week", queued)
+	}
+
+	rec, body = callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-12/draft", `{"confirm":"yes"}`)
+	if rec.Code != http.StatusBadRequest || errorCode(body) != "invalid_request" {
+		t.Errorf("POST draft with a bad confirm = %d %v, want 400", rec.Code, body)
+	}
+}
+
+// TestDraftWeekNotEnqueuedThroughJobs checks POST /api/v1/jobs refuses a
+// draft_week job, so a confirmed draft cannot run beside the week's
+// unconfirmed one: POST /plans/{weekStart}/draft is the only way to start
+// a draft.
+func TestDraftWeekNotEnqueuedThroughJobs(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+
+	rec, _ := callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-12/draft", "{}")
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("POST draft = %d: %s", rec.Code, rec.Body)
+	}
+	rec, body := callDinners(t, e.h, http.MethodPost, "/api/v1/jobs",
+		`{"kind":"`+plan.KindDraftWeek+`","payload":{"week_start":"2026-10-12","confirm":true}}`)
+	if rec.Code != http.StatusBadRequest || errorCode(body) != "service_only_kind" {
+		t.Errorf("POST job %s = %d %v, want 400 service_only_kind", plan.KindDraftWeek, rec.Code, body)
+	}
+	var queued int
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM jobs WHERE kind = ?`, plan.KindDraftWeek).Scan(&queued); err != nil {
+		t.Fatal(err)
+	}
+	if queued != 1 {
+		t.Errorf("%d draft jobs, want only the one POST draft enqueued", queued)
+	}
+}
+
+func TestSimultaneousPostPlanDraftsShareOneJob(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+
+	const n = 10
+	recs := make([]*httptest.ResponseRecorder, n)
+	var wg sync.WaitGroup
+	for i := range n {
+		wg.Go(func() {
+			recs[i] = httptest.NewRecorder()
+			e.h.ServeHTTP(recs[i], signedIn(http.MethodPost, plansPath+"2026-10-12/draft", strings.NewReader("{}")))
+		})
+	}
+	wg.Wait()
+	jobIDs := map[any]int{}
+	for i, rec := range recs {
+		var body map[string]any
+		if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil || rec.Code != http.StatusAccepted {
+			t.Fatalf("POST draft %d = %d %s, want 202", i, rec.Code, rec.Body)
+		}
+		jobIDs[body["jobId"]]++
+	}
+	var queued int
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT COUNT(*) FROM jobs WHERE kind = ?`, plan.KindDraftWeek).Scan(&queued); err != nil {
+		t.Fatal(err)
+	}
+	if len(jobIDs) != 1 || jobIDs[nil] != 0 || queued != 1 {
+		t.Errorf("jobIds = %v, %d draft jobs; want one jobId for all %d drafts", jobIDs, queued, n)
+	}
+}
+
+func TestPostPlanDraftOverSyncedPlanNeedsConfirm(t *testing.T) {
+	t.Parallel()
+	for _, status := range []string{"synced", "changed"} {
+		e := newPlansRouter(t)
+		e.setStatus(t, status)
+		for _, b := range []string{"{}", `{"confirm":false}`} {
+			rec, body := callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-12/draft", b)
+			if rec.Code != http.StatusConflict || errorCode(body) != "confirm_required" {
+				t.Errorf("%s plan: POST draft %s = %d %v, want 409 confirm_required", status, b, rec.Code, body)
+			}
+		}
+		rec, body := callDinners(t, e.h, http.MethodPost, plansPath+"2026-10-12/draft", `{"confirm":true}`)
+		if rec.Code != http.StatusAccepted || body["jobId"] == nil {
+			t.Errorf("%s plan: POST draft with confirm = %d %v, want 202", status, rec.Code, body)
+		}
+	}
+}
+
+func TestPutPlanDay(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+	e.setStatus(t, "synced")
+
+	rec, body := callDinners(t, e.h, http.MethodPut, plansPath+"2026-10-12/days/2026-10-14", `{"dinner_id":"`+e.questLog+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("PUT day = %d: %s", rec.Code, rec.Body)
+	}
+	if body["status"] != "changed" {
+		t.Errorf("status = %v, want a swapped synced plan changed", body["status"])
+	}
+	wednesday := body["days"].([]any)[2].(map[string]any)
+	if wednesday["date"] != "2026-10-14" || wednesday["is_new"] != true || wednesday["dinner"].(map[string]any)["name"] != "Pad Thai" {
+		t.Errorf("Wednesday = %v, want Pad Thai, new", wednesday)
+	}
+
+	for _, tc := range []struct {
+		target, body string
+		status       int
+		code         string
+	}{
+		{"2026-10-12/days/2026-10-14", `{}`, http.StatusBadRequest, "invalid_request"},
+		{"2026-10-12/days/2026-10-14", `{"dinner_id":7}`, http.StatusBadRequest, "invalid_request"},
+		{"2026-10-12/days/2026-10-14", `{"dinner_id":"x","extra":1}`, http.StatusBadRequest, "invalid_request"},
+		{"2026-10-12/days/2026-10-20", `{"dinner_id":"` + e.questLog + `"}`, http.StatusBadRequest, "invalid_date"},
+		{"2026-10-12/days/2026-10-32", `{"dinner_id":"` + e.questLog + `"}`, http.StatusBadRequest, "invalid_date"},
+		{"2026-10-12/days/2026-10-14", `{"dinner_id":"no-such-dinner"}`, http.StatusNotFound, "not_found"},
+		{"2026-10-19/days/2026-10-20", `{"dinner_id":"` + e.questLog + `"}`, http.StatusNotFound, "not_found"},
+		{"2026-10-12/days/2026-10-15", `{"dinner_id":"` + e.questLog + `"}`, http.StatusConflict, "dinner_already_planned"},
+	} {
+		rec, body := callDinners(t, e.h, http.MethodPut, plansPath+tc.target, tc.body)
+		if rec.Code != tc.status || errorCode(body) != tc.code {
+			t.Errorf("PUT %s %s = %d %v, want %d %s", tc.target, tc.body, rec.Code, body, tc.status, tc.code)
+		}
+	}
+	if _, err := e.st.Writer.ExecContext(t.Context(), `UPDATE dinners SET status = 'archived' WHERE id = ?`, e.questLog); err != nil {
+		t.Fatal(err)
+	}
+	rec, body = callDinners(t, e.h, http.MethodPut, plansPath+"2026-10-12/days/2026-10-15", `{"dinner_id":"`+e.questLog+`"}`)
+	if rec.Code != http.StatusConflict || errorCode(body) != "dinner_not_plannable" {
+		t.Errorf("PUT archived dinner = %d %v, want 409 dinner_not_plannable", rec.Code, body)
+	}
+}

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), newTestDinners(t), newTestRunner(t),
+	r, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), search, newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestRunner(t),
 		newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)

internal/server/rotation.go

@@ -0,0 +1,87 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/plan"
+)
+
+// maxRotationReviewBody bounds a POST /dinners/{id}/rotation-review body.
+const maxRotationReviewBody = 1 << 10
+
+// rotationDecision is the POST /dinners/{id}/rotation-review body:
+// keep, drop ("Not for us") or not_made ("We didn't make it").
+type rotationDecision struct {
+	Decision *string `json:"decision"`
+}
+
+type rotationReviewList struct {
+	Reviews []plan.Review `json:"reviews"`
+}
+
+// getRotationReviews answers GET /rotation-reviews with the pending
+// Rotation checks, oldest plan date first.
+func getRotationReviews(logger *slog.Logger, svc *plan.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		list, err := svc.PendingReviews(r.Context())
+		if err != nil {
+			writeRotationError(w, r, logger, "list Rotation checks", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, rotationReviewList{Reviews: list})
+	}
+}
+
+// postRotationReview applies the household's answer to "Keep it in
+// rotation?" for a tried dinner, recording the session's actor as
+// updated_by, and answers with the Rotation check as decided.
+func postRotationReview(logger *slog.Logger, svc *plan.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		body, err := decodePatch[rotationDecision](http.MaxBytesReader(w, r.Body, maxRotationReviewBody))
+		if err != nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		if body.Decision == nil {
+			writeError(w, r, logger, http.StatusBadRequest, "invalid_request", "decision: required")
+			return
+		}
+		d, err := svc.DecideReview(r.Context(), chi.URLParam(r, "id"), *body.Decision, actor.Subject)
+		if err != nil {
+			writeRotationError(w, r, logger, "decide Rotation check", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// writeRotationError maps a Rotation check error to its API error: a
+// decision other than keep, drop or not_made is 400, an unknown dinner or
+// a dinner never checked 404, and a dinner whose checks are all decided
+// (such as a second decision) or no longer tried 409.
+func writeRotationError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
+	var invalid *plan.InvalidDecisionError
+	switch {
+	case errors.As(err, &invalid):
+		writeError(w, r, logger, http.StatusBadRequest, "invalid_decision", invalid.Error())
+	case errors.Is(err, plan.ErrDinnerNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "dinner not found")
+	case errors.Is(err, plan.ErrReviewNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "rotation check not found")
+	case errors.Is(err, plan.ErrNoPendingReview):
+		writeError(w, r, logger, http.StatusConflict, "no_pending_review", err.Error())
+	case errors.Is(err, plan.ErrDinnerNotTried):
+		writeError(w, r, logger, http.StatusConflict, "dinner_not_tried", err.Error())
+	default:
+		logger.ErrorContext(r.Context(), action, "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+}

internal/server/rotation_test.go

@@ -0,0 +1,147 @@
+package server
+
+import (
+	"net/http"
+	"testing"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+const rotationReviewsPath = "/api/v1/rotation-reviews"
+
+// triedPadThai plans the Quest log dinner Pad Thai on Wednesday 2026-10-14
+// and marks the day tried, so Pad Thai has a pending Rotation check.
+func triedPadThai(t *testing.T, e plansEnv) {
+	t.Helper()
+	rec, _ := callDinners(t, e.h, http.MethodPut, plansPath+"2026-10-12/days/2026-10-14", `{"dinner_id":"`+e.questLog+`"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("swap Pad Thai in = %d: %s", rec.Code, rec.Body)
+	}
+	day, err := store.ParseLocalDate("2026-10-14")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n, err := e.svc.MarkTried(t.Context(), day); err != nil || n != 1 {
+		t.Fatalf("MarkTried = %d, %v, want 1", n, err)
+	}
+}
+
+func TestGetRotationReviews(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+
+	rec, body := callDinners(t, e.h, http.MethodGet, rotationReviewsPath, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET = %d: %s", rec.Code, rec.Body)
+	}
+	if reviews, ok := body["reviews"].([]any); !ok || len(reviews) != 0 {
+		t.Errorf("GET before MarkTried = %v, want an empty reviews list", body)
+	}
+
+	triedPadThai(t, e)
+	rec, body = callDinners(t, e.h, http.MethodGet, rotationReviewsPath, "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET = %d: %s", rec.Code, rec.Body)
+	}
+	reviews, _ := body["reviews"].([]any)
+	if len(reviews) != 1 {
+		t.Fatalf("reviews = %v, want one", body)
+	}
+	r := reviews[0].(map[string]any)
+	d, _ := r["dinner"].(map[string]any)
+	if len(r) != 2 || r["plan_date"] != "2026-10-14" || len(d) != 3 ||
+		d["id"] != e.questLog || d["name"] != "Pad Thai" || d["photo"] != nil {
+		t.Errorf("review = %v, want {dinner {id, name, photo}, plan_date}", r)
+	}
+}
+
+func TestPostRotationReview(t *testing.T) {
+	t.Parallel()
+	for _, tc := range []struct{ decision, status string }{
+		{"keep", "regular"},
+		{"drop", "archived"},
+		{"not_made", "quest_log"},
+	} {
+		t.Run(tc.decision, func(t *testing.T) {
+			t.Parallel()
+			e := newPlansRouter(t)
+			triedPadThai(t, e)
+			target := dinnersPath + "/" + e.questLog + "/rotation-review"
+
+			rec, body := callDinners(t, e.h, http.MethodPost, target, `{"decision":"`+tc.decision+`"}`)
+			if rec.Code != http.StatusOK {
+				t.Fatalf("POST = %d: %s", rec.Code, rec.Body)
+			}
+			if body["decision"] != tc.decision || body["dinner_status"] != tc.status || body["plan_date"] != "2026-10-14" ||
+				body["updated_by"] != testSession.Subject || body["decided_at"] == "" {
+				t.Errorf("decided = %v", body)
+			}
+			var status, origin, updatedBy string
+			if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT status, origin, updated_by FROM dinners WHERE id = ?`, e.questLog).
+				Scan(&status, &origin, &updatedBy); err != nil {
+				t.Fatal(err)
+			}
+			if status != tc.status || origin != "regular" || updatedBy != testSession.Subject {
+				t.Errorf("dinner = %s %s %s, want %s regular %s", status, origin, updatedBy, tc.status, testSession.Subject)
+			}
+
+			rec, body = callDinners(t, e.h, http.MethodPost, target, `{"decision":"keep"}`)
+			if rec.Code != http.StatusConflict || errorCode(body) != "no_pending_review" {
+				t.Errorf("second decision = %d %v, want 409 no_pending_review", rec.Code, body)
+			}
+			rec, body = callDinners(t, e.h, http.MethodGet, rotationReviewsPath, "")
+			if reviews, _ := body["reviews"].([]any); rec.Code != http.StatusOK || len(reviews) != 0 {
+				t.Errorf("GET after deciding = %d %v, want no reviews", rec.Code, body)
+			}
+		})
+	}
+}
+
+// A dinner that has never had a Rotation check is 404; a second decision
+// on one already decided is 409 (TestPostRotationReview).
+func TestPostRotationReviewNeverChecked(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+	rec, body := callDinners(t, e.h, http.MethodPost, dinnersPath+"/"+e.questLog+"/rotation-review", `{"decision":"keep"}`)
+	if rec.Code != http.StatusNotFound || errorCode(body) != "not_found" {
+		t.Errorf("never checked = %d %v, want 404 not_found", rec.Code, body)
+	}
+	var status string
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT status FROM dinners WHERE id = ?`, e.questLog).Scan(&status); err != nil {
+		t.Fatal(err)
+	}
+	if status != "quest_log" {
+		t.Errorf("status after a refused decision = %s, want quest_log", status)
+	}
+}
+
+func TestPostRotationReviewRefused(t *testing.T) {
+	t.Parallel()
+	e := newPlansRouter(t)
+	triedPadThai(t, e)
+	target := dinnersPath + "/" + e.questLog + "/rotation-review"
+
+	for _, tc := range []struct {
+		name, target, body string
+		code               int
+		errCode            string
+	}{
+		{"no decision", target, `{}`, http.StatusBadRequest, "invalid_request"},
+		{"null decision", target, `{"decision":null}`, http.StatusBadRequest, "invalid_request"},
+		{"unknown field", target, `{"decision":"keep","status":"regular"}`, http.StatusBadRequest, "invalid_request"},
+		{"unknown decision", target, `{"decision":"promote"}`, http.StatusBadRequest, "invalid_decision"},
+		{"unknown dinner", dinnersPath + "/nope/rotation-review", `{"decision":"keep"}`, http.StatusNotFound, "not_found"},
+	} {
+		rec, body := callDinners(t, e.h, http.MethodPost, tc.target, tc.body)
+		if rec.Code != tc.code || errorCode(body) != tc.errCode {
+			t.Errorf("%s = %d %v, want %d %s", tc.name, rec.Code, body, tc.code, tc.errCode)
+		}
+	}
+	var status string
+	if err := e.st.Reader.QueryRowContext(t.Context(), `SELECT status FROM dinners WHERE id = ?`, e.questLog).Scan(&status); err != nil {
+		t.Fatal(err)
+	}
+	if status != "tried" {
+		t.Errorf("status after refused decisions = %s, want tried", status)
+	}
+}

internal/server/server.go

@@ -16,7 +16,9 @@ import (
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/frontend"
 	"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/plan"
 	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
 )
 
 // reservedPrefixes are owned by the API router and are never answered with the
@@ -38,12 +40,17 @@ type RouteMounter interface {
 // dinnerSvc serves GET and POST /api/v1/dinners, PATCH and DELETE
 // /api/v1/dinners/{id}, POST /api/v1/dinners/{id}/favorite, GET
 // /api/v1/dinners/{id}/recipe-candidates and POST /api/v1/dinners/{id}/ground;
-// runner serves
+// suggestSvc serves POST /api/v1/suggestions/batches, GET
+// /api/v1/suggestions/deck and POST /api/v1/suggestions/{id}/accept and
+// /decline; planSvc serves GET /api/v1/plans/{weekStart}, POST
+// /api/v1/plans/{weekStart}/draft, PUT
+// /api/v1/plans/{weekStart}/days/{date}, GET /api/v1/rotation-reviews and
+// POST /api/v1/dinners/{id}/rotation-review; 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, dinnerSvc *dinners.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, dinnerSvc *dinners.Service, suggestSvc *suggest.Service, planSvc *plan.Service, runner *jobs.Runner, photos PhotoFiles, assets fs.FS) (http.Handler, error) {
 	if settings == nil {
 		return nil, errors.New("server: nil household settings service")
 	}
@@ -56,6 +63,12 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	if dinnerSvc == nil {
 		return nil, errors.New("server: nil dinners service")
 	}
+	if suggestSvc == nil {
+		return nil, errors.New("server: nil suggestions service")
+	}
+	if planSvc == nil {
+		return nil, errors.New("server: nil plan service")
+	}
 	if runner == nil {
 		return nil, errors.New("server: nil job runner")
 	}
@@ -106,6 +119,15 @@ func NewRouter(logger *slog.Logger, version string, trusted forwarded.Trusted, a
 	apiV1.Post("/dinners/{id}/favorite", postDinnerFavorite(logger, dinnerSvc))
 	apiV1.Get("/dinners/{id}/recipe-candidates", getDinnerCandidates(logger, dinnerSvc))
 	apiV1.Post("/dinners/{id}/ground", postDinnerGround(logger, dinnerSvc))
+	apiV1.Post("/suggestions/batches", postSuggestionBatch(logger, suggestSvc))
+	apiV1.Get("/suggestions/deck", getSuggestionDeck(logger, suggestSvc))
+	apiV1.Post("/suggestions/{id}/accept", postSuggestionDecision(logger, suggestSvc, true))
+	apiV1.Post("/suggestions/{id}/decline", postSuggestionDecision(logger, suggestSvc, false))
+	apiV1.Get("/plans/{weekStart}", getPlan(logger, planSvc))
+	apiV1.Post("/plans/{weekStart}/draft", postPlanDraft(logger, planSvc))
+	apiV1.Put("/plans/{weekStart}/days/{date}", putPlanDay(logger, planSvc))
+	apiV1.Get("/rotation-reviews", getRotationReviews(logger, planSvc))
+	apiV1.Post("/dinners/{id}/rotation-review", postRotationReview(logger, planSvc))
 	apiV1.Post("/jobs", postJob(logger, runner))
 	apiV1.Get("/jobs/{id}", getJob(logger, runner))
 	media.Get("/photos/{name}", getPhoto(logger, photos))

internal/server/server_test.go

@@ -5,6 +5,7 @@ import (
 	"crypto/rand"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"io"
 	"log/slog"
 	"maps"
@@ -18,13 +19,16 @@ 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/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/plan"
 	"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/secretbox"
 	"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"
 )
 
@@ -46,7 +50,7 @@ func newTestRouterWith(t *testing.T, version string, settings *household.Setting
 		"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), newTestDinners(t), runner, newTestPhotos(t), assets)
+	r, err := NewRouter(logger, version, nil, stubAuth{}, stubSessions{}, settings, newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), runner, newTestPhotos(t), assets)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -160,6 +164,48 @@ func newTestDinners(t *testing.T) *dinners.Service {
 	return svc
 }
 
+// newTestSuggest returns a suggestions service over a migrated temp
+// database, with its own unstarted job runner, a grounder that finds
+// nothing and a suggester that always fails.
+func newTestSuggest(t *testing.T) *suggest.Service {
+	t.Helper()
+	st := newTestStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	fail := func(context.Context, string, skills.SideQuestsRequest) (skills.SideQuests, error) {
+		return skills.SideQuests{}, errors.New("no model in this test")
+	}
+	svc, err := suggest.NewService(st, g, fail, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return svc
+}
+
+// newTestPlan returns a plan service over a migrated temp database, with
+// its own unstarted job runner and a drafter that always fails.
+func newTestPlan(t *testing.T) *plan.Service {
+	t.Helper()
+	st := newTestStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	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, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return svc
+}
+
 // newTestBox returns a secret box under a random key.
 func newTestBox(t *testing.T) *secretbox.Box {
 	t.Helper()
@@ -191,7 +237,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, newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), nil, newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil AI settings service")
 	}
 }
@@ -200,7 +246,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), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), nil, newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil recipe search settings service")
 	}
 }
@@ -209,7 +255,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), newTestDinners(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestRunner(t), nil, fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted nil photo files")
 	}
 }
@@ -218,7 +264,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), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, nil, newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil settings service")
 	}
 }
@@ -227,16 +273,34 @@ 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), 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), nil, newTestSuggest(t), newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
 		t.Fatal("NewRouter accepted a nil dinners service")
 	}
 }
 
+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), newTestDinners(t), nil, newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil suggestions service")
+	}
+}
+
+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), newTestDinners(t), newTestSuggest(t), nil, newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+		t.Fatal("NewRouter accepted a nil plan service")
+	}
+}
+
 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), newTestDinners(t), nil, newTestPhotos(t), fstest.MapFS{"index.html": {}}); err == nil {
+	if _, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(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), newTestDinners(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+		newTestSearch(t), newTestAI(t), newTestDinners(t), newTestSuggest(t), newTestPlan(t), newTestRunner(t), newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
 	if err != nil {
 		t.Fatal(err)
 	}

internal/server/suggestions.go

@@ -0,0 +1,78 @@
+package server
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
+)
+
+// postSuggestionBatch starts a manual suggestion batch and answers 202 with
+// its batch_id and the job_id that GET /jobs/{id} reports on, without
+// waiting for the job. When a batch is already pending or running it
+// answers 202 with that batch instead of starting another.
+func postSuggestionBatch(logger *slog.Logger, svc *suggest.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		b, err := svc.StartBatch(r.Context(), suggest.TriggerManual)
+		if err != nil {
+			writeSuggestionError(w, r, logger, "start suggestion batch", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusAccepted, b)
+	}
+}
+
+// getSuggestionDeck answers GET /suggestions/deck with the pending
+// suggestions, oldest first, and the batch pending or running, or null.
+func getSuggestionDeck(logger *slog.Logger, svc *suggest.Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		d, err := svc.Deck(r.Context())
+		if err != nil {
+			writeSuggestionError(w, r, logger, "list suggestion deck", err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// postSuggestionDecision records Try it (accept) or Pass (decline) on a
+// suggestion, recording the session's actor as its dinner's updated_by.
+func postSuggestionDecision(logger *slog.Logger, svc *suggest.Service, accept bool) http.HandlerFunc {
+	decide, action := svc.Decline, "decline suggestion"
+	if accept {
+		decide, action = svc.Accept, "accept suggestion"
+	}
+	return func(w http.ResponseWriter, r *http.Request) {
+		actor, ok := actorOrFail(w, r, logger)
+		if !ok {
+			return
+		}
+		d, err := decide(r.Context(), chi.URLParam(r, "id"), actor.Subject)
+		if err != nil {
+			writeSuggestionError(w, r, logger, action, err)
+			return
+		}
+		writeJSON(w, r, logger, http.StatusOK, d)
+	}
+}
+
+// writeSuggestionError maps a suggest.Service error to its API error: an
+// unknown suggestion is 404, and a decision on one already decided the
+// other way, or whose dinner left the deck, is 409.
+func writeSuggestionError(w http.ResponseWriter, r *http.Request, logger *slog.Logger, action string, err error) {
+	var decided *suggest.DecidedError
+	switch {
+	case errors.As(err, &decided):
+		writeError(w, r, logger, http.StatusConflict, "suggestion_decided", decided.Error())
+	case errors.Is(err, suggest.ErrDinnerNotSuggested):
+		writeError(w, r, logger, http.StatusConflict, "dinner_not_suggested", err.Error())
+	case errors.Is(err, suggest.ErrNotFound):
+		writeError(w, r, logger, http.StatusNotFound, "not_found", "suggestion not found")
+	default:
+		logger.ErrorContext(r.Context(), action, "error", err)
+		writeError(w, r, logger, http.StatusInternalServerError, "internal", "internal error")
+	}
+}

internal/server/suggestions_test.go

@@ -0,0 +1,228 @@
+package server
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"testing/fstest"
+
+	"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/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes/recipestest"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/suggest"
+)
+
+const suggestionsPath = "/api/v1/suggestions"
+
+// newSuggestionsRouter returns a router whose suggestions service has an
+// unstarted job runner, so batches stay pending, and a deck seeded with
+// pending suggestions of dinners named names, in order, whose ids it
+// returns.
+func newSuggestionsRouter(t *testing.T, names ...string) (http.Handler, *store.Store, []string) {
+	t.Helper()
+	st := newTestStore(t)
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	runner, err := jobs.NewRunner(st, logger, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := recipestest.NewGrounder(t, st, t.TempDir(), &recipestest.Search{}, &recipestest.Pages{}, &recipestest.Images{}, &llm.Fake{})
+	fail := func(context.Context, string, skills.SideQuestsRequest) (skills.SideQuests, error) {
+		return skills.SideQuests{}, errors.New("no model in this test")
+	}
+	svc, err := suggest.NewService(st, g, fail, runner, logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h, err := NewRouter(logger, "dev", nil, stubAuth{}, stubSessions{}, newTestSettings(t), newTestSearch(t), newTestAI(t),
+		newTestDinners(t), svc, newTestPlan(t), runner, newTestPhotos(t), fstest.MapFS{"index.html": {Data: []byte(fixtureIndex)}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	q := db.New(st.Writer)
+	ctx := t.Context()
+	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)
+	}
+	var ids []string
+	for i, name := range names {
+		d, err := q.CreateDinner(ctx, db.CreateDinnerParams{
+			ID: store.NewID(), Name: name, NormalizedName: harness.Normalize(name), Status: "suggested", Origin: "side_quest",
+			Difficulty: sql.NullString{String: "easy", Valid: true}, GroundingStatus: "grounded", CreatedAt: now, UpdatedAt: now,
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		id := store.NewID()
+		if err := q.CreateSuggestion(ctx, db.CreateSuggestionParams{
+			ID: id, DinnerID: d.ID, BatchID: batch.ID, Name: name, Reason: fmt.Sprintf("Reason %d", i), CitedRegularIds: "[]",
+			CreatedAt: store.Now().String(), UpdatedAt: now,
+		}); err != nil {
+			t.Fatal(err)
+		}
+		ids = append(ids, id)
+	}
+	return h, st, ids
+}
+
+func TestSuggestionDeck(t *testing.T) {
+	t.Parallel()
+	h, _, ids := newSuggestionsRouter(t, "Pho", "Ramen")
+
+	rec, body := callDinners(t, h, http.MethodGet, suggestionsPath+"/deck", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET deck = %d: %s", rec.Code, rec.Body)
+	}
+	list, _ := body["suggestions"].([]any)
+	if len(list) != 2 {
+		t.Fatalf("deck = %v, want 2 suggestions", body)
+	}
+	for i, name := range []string{"Pho", "Ramen"} {
+		s := list[i].(map[string]any)
+		if s["id"] != ids[i] || s["name"] != name || s["difficulty"] != "easy" || s["reason"] != fmt.Sprintf("Reason %d", i) || s["status"] != "pending" {
+			t.Errorf("deck[%d] = %v, want %s", i, s, name)
+		}
+		if _, ok := s["photo_url"]; !ok {
+			t.Errorf("deck[%d] has no photo_url key", i)
+		}
+	}
+}
+
+func TestSuggestionDecisions(t *testing.T) {
+	t.Parallel()
+	h, _, ids := newSuggestionsRouter(t, "Pho", "Ramen", "Laksa", "Bibimbap", "Katsu", "Tonkatsu", "Udon")
+
+	for _, tc := range []struct {
+		target       string
+		status       int
+		code         string
+		sugStatus    string
+		dinnerStatus string
+	}{
+		{ids[0] + "/accept", http.StatusOK, "", "accepted", "quest_log"},
+		{ids[0] + "/accept", http.StatusOK, "", "accepted", "quest_log"},
+		{ids[0] + "/decline", http.StatusConflict, "suggestion_decided", "", ""},
+		{ids[1] + "/decline", http.StatusOK, "", "declined", "archived"},
+		{ids[1] + "/decline", http.StatusOK, "", "declined", "archived"},
+		{ids[1] + "/accept", http.StatusConflict, "suggestion_decided", "", ""},
+		{"nope/accept", http.StatusNotFound, "not_found", "", ""},
+		{"nope/decline", http.StatusNotFound, "not_found", "", ""},
+	} {
+		rec, body := callDinners(t, h, http.MethodPost, suggestionsPath+"/"+tc.target, "")
+		if rec.Code != tc.status {
+			t.Fatalf("POST %s = %d, want %d: %s", tc.target, rec.Code, tc.status, rec.Body)
+		}
+		if tc.code != "" {
+			if errorCode(body) != tc.code {
+				t.Errorf("POST %s error = %v, want %s", tc.target, body, tc.code)
+			}
+			continue
+		}
+		s, _ := body["suggestion"].(map[string]any)
+		if s["status"] != tc.sugStatus || s["dinner_status"] != tc.dinnerStatus {
+			t.Errorf("POST %s = %v, want %s with dinner %s", tc.target, body, tc.sugStatus, tc.dinnerStatus)
+		}
+		if body["replenish_job_id"] != nil {
+			t.Errorf("POST %s replenished with 5 left: %v", tc.target, body["replenish_job_id"])
+		}
+	}
+
+	// A third decision leaves 4: a replenish batch starts.
+	rec, body := callDinners(t, h, http.MethodPost, suggestionsPath+"/"+ids[2]+"/decline", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("decline = %d: %s", rec.Code, rec.Body)
+	}
+	replenish, _ := body["replenish_job_id"].(string)
+	if replenish == "" {
+		t.Fatalf("decline leaving 4 = %v, want a replenish_job_id", body)
+	}
+
+	// A fourth decision joins the batch already pending and reports its job.
+	rec, body = callDinners(t, h, http.MethodPost, suggestionsPath+"/"+ids[3]+"/accept", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("accept = %d: %s", rec.Code, rec.Body)
+	}
+	if body["replenish_job_id"] != replenish {
+		t.Errorf("accept leaving 3 = %v, want replenish_job_id %s", body, replenish)
+	}
+}
+
+func TestSuggestionDeckActiveBatch(t *testing.T) {
+	t.Parallel()
+	h, _, _ := newSuggestionsRouter(t, "Pho")
+
+	rec, body := callDinners(t, h, http.MethodGet, suggestionsPath+"/deck", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET deck = %d: %s", rec.Code, rec.Body)
+	}
+	if active, ok := body["active_batch"]; !ok || active != nil {
+		t.Fatalf("deck = %v, want active_batch null", body)
+	}
+	if failed, ok := body["failed_batch"]; !ok || failed != nil {
+		t.Fatalf("deck = %v, want failed_batch null", body)
+	}
+
+	rec, started := callDinners(t, h, http.MethodPost, suggestionsPath+"/batches", "")
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("POST batches = %d: %s", rec.Code, rec.Body)
+	}
+	rec, body = callDinners(t, h, http.MethodGet, suggestionsPath+"/deck", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET deck = %d: %s", rec.Code, rec.Body)
+	}
+	active, _ := body["active_batch"].(map[string]any)
+	if active == nil || active["batch_id"] != started["batch_id"] || active["job_id"] != started["job_id"] || active["status"] != "pending" {
+		t.Errorf("deck active_batch = %v, want the started batch %v", body["active_batch"], started)
+	}
+}
+
+func TestPostSuggestionBatch(t *testing.T) {
+	t.Parallel()
+	h, st, _ := newSuggestionsRouter(t)
+
+	rec, first := callDinners(t, h, http.MethodPost, suggestionsPath+"/batches", "")
+	if rec.Code != http.StatusAccepted {
+		t.Fatalf("POST batches = %d: %s", rec.Code, rec.Body)
+	}
+	if first["batch_id"] == nil || first["job_id"] == nil || first["trigger"] != "manual" || first["status"] != "pending" {
+		t.Errorf("POST batches = %v, want a pending manual batch with its job", first)
+	}
+	var kind string
+	if err := st.Reader.QueryRow(`SELECT kind FROM jobs WHERE id = ?`, first["job_id"]).Scan(&kind); err != nil || kind != suggest.KindSuggestionBatch {
+		t.Errorf("job kind = %q (%v), want %s", kind, err, suggest.KindSuggestionBatch)
+	}
+
+	rec, again := callDinners(t, h, http.MethodPost, suggestionsPath+"/batches", "")
+	if rec.Code != http.StatusAccepted || again["batch_id"] != first["batch_id"] || again["job_id"] != first["job_id"] {
+		t.Errorf("second POST batches = %d %v, want the pending batch %v", rec.Code, again, first)
+	}
+}
+
+func TestSuggestionWritesNeedCSRF(t *testing.T) {
+	t.Parallel()
+	h, _, ids := newSuggestionsRouter(t, "Pho")
+	for _, target := range []string{"/batches", "/" + ids[0] + "/accept", "/" + ids[0] + "/decline"} {
+		req := httptest.NewRequest(http.MethodPost, suggestionsPath+target, nil)
+		req.AddCookie(validSessionCookie)
+		rec, body := serve(t, h, req)
+		if rec.Code != http.StatusForbidden || errorCode(body) != "csrf" {
+			t.Errorf("POST %s without CSRF = %d %v, want 403 csrf", target, rec.Code, body)
+		}
+	}
+}

internal/store/migrate_test.go

@@ -3,6 +3,7 @@ package store
 import (
 	"context"
 	"io/fs"
+	"reflect"
 	"slices"
 	"strings"
 	"testing"
@@ -175,8 +176,8 @@ func TestMigrateEmbeddedMigrations(t *testing.T) {
 	if err := Migrate(context.Background(), s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name,0013_week_plan_revision,0014_rotation_review_name" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name,0013_week_plan_revision,0014_rotation_review_name", got)
 	}
 }
 
@@ -196,8 +197,8 @@ func TestMigrateBootstrapThenEmbeddedInitApplies(t *testing.T) {
 	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
 		t.Fatal(err)
 	}
-	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision" {
-		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision", got)
+	if got := versions(migrationRows(t, s)); got != "0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name,0013_week_plan_revision,0014_rotation_review_name" {
+		t.Errorf("versions = %q, want 0000_bootstrap,0001_init,0002_household_settings_updated_by,0003_jobs_status,0004_ai_provider_presets,0005_ai_provider_xai,0006_ai_runs_status,0007_recipe_grounding,0008_dinner_recipe_url,0009_dinner_grounding_error,0010_dinner_grounding_revision,0011_ground_dinner_job_revision,0012_suggestion_name,0013_week_plan_revision,0014_rotation_review_name", got)
 	}
 	if !tableExists(t, s, "dinners") {
 		t.Error("table from 0001_init was not created")
@@ -557,3 +558,163 @@ func TestMigrateAIRunsStatus(t *testing.T) {
 		})
 	}
 }
+
+// TestMigrateSuggestionName upgrades a database at 0011 holding a pending
+// and a declined suggestion and checks 0012 keeps both, gives each its
+// dinner's name, and refuses a suggestion with no name.
+func TestMigrateSuggestionName(t *testing.T) {
+	ctx := context.Background()
+	s := openTestStore(t)
+	before := fstest.MapFS{}
+	for _, name := range []string{
+		"0000_bootstrap.sql", "0001_init.sql", "0002_household_settings_updated_by.sql", "0003_jobs_status.sql",
+		"0004_ai_provider_presets.sql", "0005_ai_provider_xai.sql", "0006_ai_runs_status.sql", "0007_recipe_grounding.sql",
+		"0008_dinner_recipe_url.sql", "0009_dinner_grounding_error.sql", "0010_dinner_grounding_revision.sql",
+		"0011_ground_dinner_job_revision.sql",
+	} {
+		body, err := fs.ReadFile(migrations.FS, name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		before[name] = &fstest.MapFile{Data: body}
+	}
+	if err := Migrate(ctx, s.Writer, before); err != nil {
+		t.Fatal(err)
+	}
+	for _, stmt := range []string{
+		`INSERT INTO dinners (id, name, normalized_name, status, origin, is_favorite, grounding_status, created_at, updated_at)
+			VALUES ('dinner-1', 'Pho', 'pho', 'suggested', 'side_quest', 0, 'grounded', 'c', 'u'),
+			       ('dinner-2', 'Ramen', 'ramen', 'archived', 'side_quest', 0, 'grounded', 'c', 'u')`,
+		`INSERT INTO suggestion_batches (id, trigger, status, created_at, updated_at)
+			VALUES ('batch-1', 'manual', 'done', 'c', 'u')`,
+		`INSERT INTO suggestions (id, dinner_id, batch_id, reason, cited_regular_ids, status, decided_at, created_at, updated_at)
+			VALUES ('sugg-1', 'dinner-1', 'batch-1', 'why 1', '[]', 'pending', NULL, 'c1', 'u1'),
+			       ('sugg-2', 'dinner-2', 'batch-1', 'why 2', '["dinner-1"]', 'declined', 'd2', 'c2', 'u2')`,
+	} {
+		if _, err := s.Writer.Exec(stmt); err != nil {
+			t.Fatalf("seed: %v", err)
+		}
+	}
+
+	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+
+	rows, err := s.Reader.Query(`SELECT id, dinner_id, batch_id, name, reason, cited_regular_ids, status, COALESCE(decided_at, ''), created_at, updated_at
+		FROM suggestions ORDER BY id`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got [][]string
+	for rows.Next() {
+		r := make([]string, 10)
+		if err := rows.Scan(&r[0], &r[1], &r[2], &r[3], &r[4], &r[5], &r[6], &r[7], &r[8], &r[9]); err != nil {
+			t.Fatal(err)
+		}
+		got = append(got, r)
+	}
+	if err := rows.Close(); err != nil {
+		t.Fatal(err)
+	}
+	want := [][]string{
+		{"sugg-1", "dinner-1", "batch-1", "Pho", "why 1", "[]", "pending", "", "c1", "u1"},
+		{"sugg-2", "dinner-2", "batch-1", "Ramen", "why 2", `["dinner-1"]`, "declined", "d2", "c2", "u2"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("suggestions after 0012 =\n %v\nwant\n %v", got, want)
+	}
+	if _, err := s.Writer.Exec(`UPDATE suggestions SET name = '' WHERE id = 'sugg-1'`); err == nil || !strings.Contains(err.Error(), "CHECK constraint failed") {
+		t.Errorf("empty suggestion name: error %v, want CHECK constraint failure", err)
+	}
+	if _, err := s.Writer.Exec(`UPDATE suggestions SET dinner_id = 'nope' WHERE id = 'sugg-1'`); err == nil || !strings.Contains(err.Error(), "FOREIGN KEY constraint failed") {
+		t.Errorf("unknown dinner: error %v, want FOREIGN KEY constraint failure", err)
+	}
+	if tableExists(t, s, "suggestions_copy") {
+		t.Error("suggestions_copy left behind")
+	}
+}
+
+// TestMigrateRotationReviewName upgrades a database at 0013 holding a
+// pending, a kept and a dropped Rotation check and checks 0014 keeps all
+// three, gives only the drop its dinner's name, and refuses a drop with no
+// name or a name on any other check.
+func TestMigrateRotationReviewName(t *testing.T) {
+	ctx := context.Background()
+	s := openTestStore(t)
+	before := fstest.MapFS{}
+	for _, name := range []string{
+		"0000_bootstrap.sql", "0001_init.sql", "0002_household_settings_updated_by.sql", "0003_jobs_status.sql",
+		"0004_ai_provider_presets.sql", "0005_ai_provider_xai.sql", "0006_ai_runs_status.sql", "0007_recipe_grounding.sql",
+		"0008_dinner_recipe_url.sql", "0009_dinner_grounding_error.sql", "0010_dinner_grounding_revision.sql",
+		"0011_ground_dinner_job_revision.sql", "0012_suggestion_name.sql", "0013_week_plan_revision.sql",
+	} {
+		body, err := fs.ReadFile(migrations.FS, name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		before[name] = &fstest.MapFile{Data: body}
+	}
+	if err := Migrate(ctx, s.Writer, before); err != nil {
+		t.Fatal(err)
+	}
+	for _, stmt := range []string{
+		`INSERT INTO dinners (id, name, normalized_name, status, origin, is_favorite, grounding_status, created_at, updated_at)
+			VALUES ('dinner-1', 'Pho', 'pho', 'tried', 'side_quest', 0, 'grounded', 'c', 'u'),
+			       ('dinner-2', 'Ramen', 'ramen', 'regular', 'side_quest', 0, 'grounded', 'c', 'u'),
+			       ('dinner-3', 'Laksa', 'laksa', 'archived', 'side_quest', 0, 'grounded', 'c', 'u')`,
+		`INSERT INTO rotation_reviews (id, dinner_id, plan_date, status, decision, decided_at, updated_by, created_at, updated_at)
+			VALUES ('review-1', 'dinner-1', '2026-10-12', 'pending', NULL, NULL, NULL, 'c1', 'u1'),
+			       ('review-2', 'dinner-2', '2026-10-13', 'decided', 'keep', 'd2', 'member-1', 'c2', 'u2'),
+			       ('review-3', 'dinner-3', '2026-10-14', 'decided', 'drop', 'd3', 'member-1', 'c3', 'u3')`,
+	} {
+		if _, err := s.Writer.Exec(stmt); err != nil {
+			t.Fatalf("seed: %v", err)
+		}
+	}
+
+	if err := Migrate(ctx, s.Writer, migrations.FS); err != nil {
+		t.Fatal(err)
+	}
+
+	rows, err := s.Reader.Query(`SELECT id, dinner_id, plan_date, status, COALESCE(decision, ''), COALESCE(name, ''),
+		COALESCE(decided_at, ''), COALESCE(updated_by, ''), created_at, updated_at
+		FROM rotation_reviews ORDER BY id`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got [][]string
+	for rows.Next() {
+		r := make([]string, 10)
+		if err := rows.Scan(&r[0], &r[1], &r[2], &r[3], &r[4], &r[5], &r[6], &r[7], &r[8], &r[9]); err != nil {
+			t.Fatal(err)
+		}
+		got = append(got, r)
+	}
+	if err := rows.Close(); err != nil {
+		t.Fatal(err)
+	}
+	want := [][]string{
+		{"review-1", "dinner-1", "2026-10-12", "pending", "", "", "", "", "c1", "u1"},
+		{"review-2", "dinner-2", "2026-10-13", "decided", "keep", "", "d2", "member-1", "c2", "u2"},
+		{"review-3", "dinner-3", "2026-10-14", "decided", "drop", "Laksa", "d3", "member-1", "c3", "u3"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("rotation_reviews after 0014 =\n %v\nwant\n %v", got, want)
+	}
+	for _, tc := range []struct{ name, stmt, want string }{
+		{"drop with no name", `UPDATE rotation_reviews SET name = NULL WHERE id = 'review-3'`, "CHECK constraint failed"},
+		{"empty name", `UPDATE rotation_reviews SET name = '' WHERE id = 'review-3'`, "CHECK constraint failed"},
+		{"name on a keep", `UPDATE rotation_reviews SET name = 'Ramen' WHERE id = 'review-2'`, "CHECK constraint failed"},
+		{"name on a pending check", `UPDATE rotation_reviews SET name = 'Pho' WHERE id = 'review-1'`, "CHECK constraint failed"},
+		{"unknown dinner", `UPDATE rotation_reviews SET dinner_id = 'nope' WHERE id = 'review-1'`, "FOREIGN KEY constraint failed"},
+		{"second check of a dinner and date", `INSERT INTO rotation_reviews (id, dinner_id, plan_date, status, created_at, updated_at)
+			VALUES ('review-4', 'dinner-1', '2026-10-12', 'pending', 'c', 'u')`, "UNIQUE constraint failed"},
+	} {
+		if _, err := s.Writer.Exec(tc.stmt); err == nil || !strings.Contains(err.Error(), tc.want) {
+			t.Errorf("%s: error %v, want %s", tc.name, err, tc.want)
+		}
+	}
+	if tableExists(t, s, "rotation_reviews_copy") {
+		t.Error("rotation_reviews_copy left behind")
+	}
+}

internal/store/repository_test.go

@@ -95,7 +95,7 @@ func TestRepositoryInsertReadUpdate(t *testing.T) {
 			parents: []string{"dinners", "suggestion_batches"},
 			row: repoRow{"suggestions", map[string]any{
 				"id": "sugg-1", "dinner_id": "dinner-1", "batch_id": "batch-1",
-				"reason": "You make chili often.", "cited_regular_ids": `["dinner-1"]`,
+				"name": "White Chicken Chili", "reason": "You make chili often.", "cited_regular_ids": `["dinner-1"]`,
 				"status": "pending", "decided_at": nil,
 				"created_at": repoTime, "updated_at": repoTime,
 			}},

internal/store/schema_test.go

@@ -110,6 +110,7 @@ func testRow(table string, i int) map[string]any {
 	case "suggestions":
 		r["dinner_id"] = rowID("dinners", 0)
 		r["batch_id"] = rowID("suggestion_batches", 0)
+		r["name"] = fmt.Sprintf("Side quest %d", i)
 		r["reason"] = "Like your chili."
 		r["cited_regular_ids"] = "[]"
 		r["status"] = "pending"

internal/suggest/batch.go

@@ -0,0 +1,309 @@
+package suggest
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"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/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/store"
+)
+
+// BatchJob is the KindSuggestionBatch payload: the batch to run.
+type BatchJob struct {
+	BatchID string `json:"batch_id"`
+}
+
+// Batch stages, as the job's result reports them.
+const (
+	StageSuggesting = "suggesting"
+	StageGrounding  = "grounding"
+	StageDone       = "done"
+)
+
+// batchResult is the KindSuggestionBatch result, published as the batch
+// goes: its stage, the suggestions stored so far, and how many Side
+// quests were dropped, by suggest_side_quests' rules, because no recipe
+// grounds them, or because they repeat a dinner added meanwhile.
+type batchResult struct {
+	BatchID       string   `json:"batch_id"`
+	Stage         string   `json:"stage"`
+	SuggestionIDs []string `json:"suggestion_ids"`
+	Dropped       int      `json:"dropped"`
+}
+
+func (r batchResult) PublicJSON() ([]byte, error) { return json.Marshal(r) }
+
+// runBatch runs batch p.BatchID: it asks suggest_side_quests for BatchSize
+// Side quests given the household context, the deck and every passed
+// name, then grounds them in the model's order, at most the number still
+// 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.
+func (s *Service) runBatch(ctx context.Context, p BatchJob, publish func(batchResult) error) (batchResult, error) {
+	n, err := db.New(s.st.Writer).StartSuggestionBatch(ctx, db.StartSuggestionBatchParams{
+		UpdatedAt: store.Now().String(),
+		ID:        p.BatchID,
+	})
+	if err != nil {
+		return batchResult{}, fmt.Errorf("suggest: start batch %s: %w", p.BatchID, err)
+	}
+	if n == 0 {
+		return batchResult{}, fmt.Errorf("suggest: batch %s is not pending", p.BatchID)
+	}
+	res, err := s.fill(ctx, p.BatchID, publish)
+	if err == nil {
+		if err := s.finishBatch(ctx, p.BatchID, BatchDone); err != nil {
+			return batchResult{}, err
+		}
+		return res, nil
+	}
+	finishErr := s.finishBatch(ctx, p.BatchID, BatchFailed)
+	if ctx.Err() != nil {
+		return batchResult{}, errors.Join(ctx.Err(), finishErr)
+	}
+	var failure *jobs.Failure
+	if errors.As(err, &failure) {
+		// Only the code is logged: the error may quote a model's or
+		// search provider's response.
+		s.logger.InfoContext(ctx, "suggestion batch failed", "batch_id", p.BatchID, "reason", failure.Code)
+	}
+	return batchResult{}, errors.Join(err, finishErr)
+}
+
+// fill does runBatch's work, returning a *jobs.Failure for a failure the
+// household may see.
+func (s *Service) fill(ctx context.Context, batchID string, publish func(batchResult) error) (batchResult, error) {
+	res := batchResult{BatchID: batchID, Stage: StageSuggesting, SuggestionIDs: []string{}}
+	if err := publish(res); err != nil {
+		return batchResult{}, err
+	}
+	in, err := s.request(ctx)
+	if err != nil {
+		return batchResult{}, err
+	}
+	out, err := s.suggest(ctx, batchID, in)
+	if err != nil {
+		if ctx.Err() != nil {
+			return batchResult{}, ctx.Err()
+		}
+		return batchResult{}, &jobs.Failure{Code: ReasonAIFailed}
+	}
+	res.Stage = StageGrounding
+	res.Dropped = len(out.Dropped)
+	if err := publish(res); err != nil {
+		return batchResult{}, err
+	}
+	left := out.Suggestions
+	for len(res.SuggestionIDs) < BatchSize && len(left) > 0 {
+		round := left[:min(BatchSize-len(res.SuggestionIDs), 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, grounded)
+		if 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
+		}
+	}
+	res.Stage = StageDone
+	return res, 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.
+func (s *Service) request(ctx context.Context) (skills.SideQuestsRequest, error) {
+	hctx, err := harness.BuildContext(ctx, s.st, time.Now(), ContextBudget)
+	if err != nil {
+		return skills.SideQuestsRequest{}, fmt.Errorf("suggest: %w", err)
+	}
+	if len(hctx.Regulars) == 0 {
+		return skills.SideQuestsRequest{}, &jobs.Failure{Code: ReasonNoRegulars}
+	}
+	q := db.New(s.st.Reader)
+	deck, err := q.ListDeck(ctx)
+	if err != nil {
+		return skills.SideQuestsRequest{}, fmt.Errorf("suggest: list deck: %w", err)
+	}
+	pending := []string{}
+	for _, row := range deck {
+		pending = append(pending, row.Dinner.Name)
+	}
+	declined, err := q.ListPassedNames(ctx)
+	if err != nil {
+		return skills.SideQuestsRequest{}, fmt.Errorf("suggest: list passed names: %w", err)
+	}
+	return skills.SideQuestsRequest{Context: hctx, Needed: BatchSize, Pending: pending, Declined: declined}, nil
+}
+
+// groundedQuest is a Side quest with the recipe that grounds it.
+type groundedQuest struct {
+	quest    skills.SideQuest
+	grounded recipes.Grounded
+}
+
+// ground grounds quests by their search queries and returns those a
+// recipe grounds, in order. A Side quest no recipe grounds is left out;
+// any other failure fails the batch.
+func (s *Service) ground(ctx context.Context, quests []skills.SideQuest) ([]groundedQuest, error) {
+	reqs := make([]recipes.GroundRequest, len(quests))
+	for i, q := range quests {
+		reqs[i] = recipes.GroundRequest{DishName: q.Name, Query: q.SearchQuery}
+	}
+	results := s.grounder.GroundMany(ctx, reqs)
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	var out []groundedQuest
+	for i, r := range results {
+		var ungroundable *recipes.ErrUngroundable
+		switch {
+		case r.Err == nil:
+			out = append(out, groundedQuest{quest: quests[i], grounded: r.Grounded})
+		case errors.As(r.Err, &ungroundable):
+		case errors.Is(r.Err, recipes.ErrSearchNotConfigured):
+			return nil, &jobs.Failure{Code: ReasonSearchNotConfigured}
+		case errors.Is(r.Err, recipes.ErrSearchFailed):
+			return nil, &jobs.Failure{Code: ReasonSearchFailed}
+		case errors.Is(r.Err, recipes.ErrNormalizeFailed):
+			return nil, &jobs.Failure{Code: ReasonAIFailed}
+		default:
+			return nil, fmt.Errorf("suggest: ground %q: %w", quests[i].Name, r.Err)
+		}
+	}
+	return out, nil
+}
+
+// store stores each grounded Side quest of batchID as a dinner with status
+// suggested and origin side_quest, grounded in its recipe, and a pending
+// suggestion citing its Regulars by id, all in one transaction, and
+// returns the suggestion ids. A Side quest is left out when, since
+// suggest_side_quests ran, a dinner it repeats was added, a suggestion it
+// repeats passed or a Rotation check dropped, or a Regular it cites renamed
+// or archived. Passed names are read in the same transaction as the store,
+// so a Pass or drop committed before it is never missed.
+func (s *Service) store(ctx context.Context, batchID string, quests []groundedQuest) ([]string, error) {
+	ids := []string{}
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		existing, err := q.ListUnarchivedDinners(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: list dinners for dedupe: %w", err)
+		}
+		names, err := q.ListPassedNames(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: list passed names for dedupe: %w", err)
+		}
+		regulars := map[string][]string{}
+		for _, row := range existing {
+			names = append(names, row.Dinner.Name)
+			if row.Dinner.Status == dinners.StatusRegular {
+				regulars[row.Dinner.Name] = append(regulars[row.Dinner.Name], row.Dinner.ID)
+			}
+		}
+		for _, gq := range quests {
+			cited, ok := citedIDs(gq.quest.CitedRegulars, regulars)
+			if !ok || repeats(gq.quest.Name, names) {
+				s.logger.InfoContext(ctx, "suggested dinner dropped: changed while grounding", "batch_id", batchID)
+				continue
+			}
+			citedJSON, err := json.Marshal(cited)
+			if err != nil {
+				return fmt.Errorf("suggest: encode cited Regulars: %w", err)
+			}
+			now := store.Now().String()
+			gr := gq.grounded
+			d, err := q.CreateDinner(ctx, db.CreateDinnerParams{
+				ID:              store.NewID(),
+				Name:            gq.quest.Name,
+				NormalizedName:  harness.Normalize(gq.quest.Name),
+				Status:          dinners.StatusSuggested,
+				Origin:          "side_quest",
+				Method:          sql.NullString{String: gr.Method, Valid: true},
+				MinutesTotal:    nullInt(gr.MinutesTotal),
+				Difficulty:      sql.NullString{String: gr.Difficulty, Valid: true},
+				Cuisine:         sql.NullString{String: gq.quest.Cuisine, Valid: true},
+				RecipeID:        sql.NullString{String: gr.RecipeID, Valid: true},
+				PhotoID:         sql.NullString{String: gr.PhotoID, Valid: true},
+				GroundingStatus: dinners.GroundingGrounded,
+				CreatedAt:       now,
+				UpdatedAt:       now,
+			})
+			if err != nil {
+				return fmt.Errorf("suggest: create dinner: %w", err)
+			}
+			id := store.NewID()
+			if err := q.CreateSuggestion(ctx, db.CreateSuggestionParams{
+				ID:              id,
+				DinnerID:        d.ID,
+				BatchID:         batchID,
+				Name:            d.Name,
+				Reason:          gq.quest.Reason,
+				CitedRegularIds: string(citedJSON),
+				CreatedAt:       now,
+				UpdatedAt:       now,
+			}); err != nil {
+				return fmt.Errorf("suggest: create suggestion: %w", err)
+			}
+			names = append(names, d.Name)
+			ids = append(ids, id)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+// citedIDs returns the ids of the Regulars named cited, false when one
+// names no Regular or more than one.
+func citedIDs(cited []string, regulars map[string][]string) ([]string, bool) {
+	ids := make([]string, len(cited))
+	for i, name := range cited {
+		if len(regulars[name]) != 1 {
+			return nil, false
+		}
+		ids[i] = regulars[name][0]
+	}
+	return ids, true
+}
+
+// repeats reports whether name is harness.Similar to any of names.
+func repeats(name string, names []string) bool {
+	for _, n := range names {
+		if harness.Similar(name, n) {
+			return true
+		}
+	}
+	return false
+}
+
+func nullInt(v *int) sql.NullInt64 {
+	if v == nil {
+		return sql.NullInt64{}
+	}
+	return sql.NullInt64{Int64: int64(*v), Valid: true}
+}

internal/suggest/suggest.go

@@ -0,0 +1,482 @@
+// Package suggest keeps the household's Side quest deck: batches of new
+// dinners the AI suggests, each grounded in a recipe, and the household's
+// Try it / Pass decision on each. A batch runs as a job: suggest_side_quests
+// proposes Side quests, each is grounded with the recipe grounding pipeline
+// (dropping those no recipe grounds), and every one kept is stored as a
+// dinner with status suggested and origin side_quest and a pending
+// suggestion. Only one batch is pending or running at a time.
+package suggest
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"slices"
+
+	"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/jobs"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/recipes"
+	"code.cubecraftlabs.com/Maniacs_Mansion/Meal-Quest/internal/store"
+)
+
+// KindSuggestionBatch is the job that runs a suggestion batch.
+const KindSuggestionBatch = "suggestion_batch"
+
+const (
+	// BatchSize is how many Side quests a batch keeps at most.
+	BatchSize = 5
+	// ReplenishBelow is the deck size under which a decision starts a
+	// replenish batch.
+	ReplenishBelow = 5
+	// ContextBudget is the character budget of the household context
+	// suggest_side_quests is given (see harness.BuildContext).
+	ContextBudget = 16000
+)
+
+// Batch triggers (the suggestion_batches.trigger column).
+const (
+	TriggerScheduled = "scheduled"
+	TriggerManual    = "manual"
+	TriggerReplenish = "replenish"
+)
+
+// Batch statuses (the suggestion_batches.status column).
+const (
+	BatchPending = "pending"
+	BatchRunning = "running"
+	BatchDone    = "done"
+	BatchFailed  = "failed"
+)
+
+// Suggestion statuses (the suggestions.status column).
+const (
+	StatusPending  = "pending"
+	StatusAccepted = "accepted"
+	StatusDeclined = "declined"
+)
+
+// Reasons a batch failed, stored as the KindSuggestionBatch job's failure
+// code. Any other failure, such as the database's, is the runner's
+// internal_error.
+const (
+	// ReasonNoRegulars: the household has no Regulars for Side quests to
+	// be based on.
+	ReasonNoRegulars = "no_regulars"
+	// ReasonAIFailed: suggest_side_quests, or normalize_recipe while
+	// grounding, failed; no Side quest is made up instead (D-017).
+	ReasonAIFailed = "ai_failed"
+	// ReasonSearchNotConfigured: recipe search is not set up.
+	ReasonSearchNotConfigured = "search_not_configured"
+	// ReasonSearchFailed: the search provider failed.
+	ReasonSearchFailed = "search_failed"
+)
+
+// Reasons are every batch failure reason.
+var Reasons = []string{ReasonNoRegulars, ReasonAIFailed, ReasonSearchNotConfigured, ReasonSearchFailed}
+
+var triggers = []string{TriggerScheduled, TriggerManual, TriggerReplenish}
+
+// ErrNotFound is returned for an unknown suggestion id.
+var ErrNotFound = errors.New("suggestion not found")
+
+// ErrDinnerNotSuggested is a decision on a pending suggestion whose dinner
+// was archived or moved out of the deck some other way.
+var ErrDinnerNotSuggested = errors.New("the suggestion's dinner is no longer suggested")
+
+// DecidedError is a decision on a suggestion already decided the other
+// way.
+type DecidedError struct {
+	// Status is the suggestion's decision: accepted or declined.
+	Status string
+}
+
+func (e *DecidedError) Error() string {
+	return "the suggestion was already " + e.Status
+}
+
+// Suggester runs suggest_side_quests on in; scope names the batch. In
+// production it is skills.SuggestSideQuests with the household's
+// harness.Config.
+type Suggester func(ctx context.Context, scope string, in skills.SideQuestsRequest) (skills.SideQuests, error)
+
+// Service runs suggestion batches and records decisions.
+type Service struct {
+	st       *store.Store
+	grounder *recipes.Grounder
+	suggest  Suggester
+	logger   *slog.Logger
+	batchJob *jobs.Kind[BatchJob]
+}
+
+// NewService returns a service over st that suggests with suggest, grounds
+// with grounder and registers the KindSuggestionBatch job on runner, which
+// must not have started yet.
+func NewService(st *store.Store, grounder *recipes.Grounder, suggest Suggester, runner *jobs.Runner, logger *slog.Logger) (*Service, error) {
+	switch {
+	case st == nil:
+		return nil, errors.New("suggest: nil store")
+	case grounder == nil:
+		return nil, errors.New("suggest: nil grounder")
+	case suggest == nil:
+		return nil, errors.New("suggest: nil suggester")
+	case runner == nil:
+		return nil, errors.New("suggest: nil job runner")
+	case logger == nil:
+		return nil, errors.New("suggest: nil logger")
+	}
+	s := &Service{st: st, grounder: grounder, suggest: suggest, logger: logger}
+	kind, err := jobs.Register(runner, KindSuggestionBatch, s.runBatch, Reasons...)
+	if err != nil {
+		return nil, err
+	}
+	s.batchJob = kind
+	return s, nil
+}
+
+// Batch is a suggestion batch with the id of the job running it.
+type Batch struct {
+	ID      string `json:"batch_id"`
+	JobID   string `json:"job_id"`
+	Trigger string `json:"trigger"`
+	Status  string `json:"status"`
+	// Created says whether this call created the batch rather than found
+	// it already pending or running.
+	Created bool `json:"-"`
+}
+
+// StartBatch creates a batch with trigger and enqueues the
+// KindSuggestionBatch job that runs it, unless a batch is already pending
+// or running, which it returns instead with Created false.
+func (s *Service) StartBatch(ctx context.Context, trigger string) (Batch, error) {
+	if !slices.Contains(triggers, trigger) {
+		return Batch{}, fmt.Errorf("suggest: unknown batch trigger %q", trigger)
+	}
+	var b Batch
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		var err error
+		b, err = s.startBatch(ctx, tx, trigger)
+		return err
+	})
+	if err != nil {
+		return Batch{}, err
+	}
+	if b.Created {
+		s.batchJob.Wake()
+	}
+	return b, nil
+}
+
+// activeBatch returns the batch pending or running in q's transaction, or
+// nil when there is none. A batch still pending or running whose job is no
+// longer queued or running is failed first, so a batch whose job ended
+// without recording its end (the process stopped, or the write failed) is
+// never reported as active and never blocks a later one.
+func (s *Service) activeBatch(ctx context.Context, q *db.Queries) (*Batch, error) {
+	n, err := q.FailOrphanedSuggestionBatches(ctx, db.FailOrphanedSuggestionBatchesParams{
+		UpdatedAt: store.Now().String(),
+		Kind:      KindSuggestionBatch,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("suggest: fail orphaned batches: %w", err)
+	}
+	if n > 0 {
+		s.logger.WarnContext(ctx, "failed suggestion batches whose job ended", "count", n)
+	}
+	cur, err := q.GetActiveSuggestionBatch(ctx)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read active batch: %w", err)
+	}
+	jobID, err := q.GetSuggestionBatchJobID(ctx, db.GetSuggestionBatchJobIDParams{Kind: KindSuggestionBatch, BatchID: cur.ID})
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read job of batch %s: %w", cur.ID, err)
+	}
+	return &Batch{ID: cur.ID, JobID: jobID, Trigger: cur.Trigger, Status: cur.Status}, nil
+}
+
+// failedBatch returns the newest batch in q's transaction when it failed,
+// or nil when it did not or there is none: a later batch, done or under
+// way, supersedes an earlier failure. Run after activeBatch, so a batch
+// whose job ended without recording its end reads as failed.
+func failedBatch(ctx context.Context, q *db.Queries) (*Batch, error) {
+	cur, err := q.GetLatestSuggestionBatch(ctx)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read latest batch: %w", err)
+	}
+	if cur.Status != BatchFailed {
+		return nil, nil
+	}
+	jobID, err := q.GetSuggestionBatchJobID(ctx, db.GetSuggestionBatchJobIDParams{Kind: KindSuggestionBatch, BatchID: cur.ID})
+	if err != nil {
+		return nil, fmt.Errorf("suggest: read job of batch %s: %w", cur.ID, err)
+	}
+	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) {
+	q := db.New(tx)
+	cur, err := s.activeBatch(ctx, q)
+	if err != nil {
+		return Batch{}, err
+	}
+	if cur != nil {
+		return *cur, nil
+	}
+	now := store.Now().String()
+	row, err := q.CreateSuggestionBatch(ctx, db.CreateSuggestionBatchParams{
+		ID:        store.NewID(),
+		Trigger:   trigger,
+		CreatedAt: now,
+		UpdatedAt: now,
+	})
+	if err != nil {
+		return Batch{}, fmt.Errorf("suggest: create batch: %w", err)
+	}
+	jobID, err := s.batchJob.EnqueueTx(ctx, tx, BatchJob{BatchID: row.ID})
+	if err != nil {
+		return Batch{}, fmt.Errorf("suggest: enqueue batch %s: %w", row.ID, err)
+	}
+	return Batch{ID: row.ID, JobID: jobID, Trigger: row.Trigger, Status: row.Status, Created: true}, nil
+}
+
+// finishBatch records running batch id as status, with
+// jobs.FinalWriteContext: the write is made even when ctx has been
+// cancelled, but a writer that stays busy cannot hold its worker past
+// jobs.FinalWriteTimeout. Its job's handler returns any error, so the job
+// never ends succeeded with the batch still running; the runner keeps only
+// a code, so the error is logged too.
+func (s *Service) finishBatch(ctx context.Context, id, status string) error {
+	write, cancel := jobs.FinalWriteContext(ctx)
+	defer cancel()
+	n, err := db.New(s.st.Writer).FinishSuggestionBatch(write, db.FinishSuggestionBatchParams{
+		Status:    status,
+		UpdatedAt: store.Now().String(),
+		ID:        id,
+	})
+	if err == nil && n != 1 {
+		err = errors.New("batch is not running")
+	}
+	if err != nil {
+		s.logger.ErrorContext(ctx, "record suggestion batch status", "batch_id", id, "status", status, "error", err)
+		return fmt.Errorf("suggest: record batch %s %s: %w", id, status, err)
+	}
+	return nil
+}
+
+// Suggestion is a Side quest suggestion as the API shows it, with its
+// dinner.
+type Suggestion struct {
+	ID           string  `json:"id"`
+	DinnerID     string  `json:"dinner_id"`
+	Name         string  `json:"name"`
+	PhotoURL     *string `json:"photo_url"`
+	Difficulty   *string `json:"difficulty"`
+	Method       *string `json:"method"`
+	MinutesTotal *int64  `json:"minutes_total"`
+	Cuisine      *string `json:"cuisine"`
+	// Reason is the "Why this?".
+	Reason          string   `json:"reason"`
+	CitedRegularIDs []string `json:"cited_regular_ids"`
+	Status          string   `json:"status"`
+	DinnerStatus    string   `json:"dinner_status"`
+	DecidedAt       *string  `json:"decided_at"`
+	CreatedAt       string   `json:"created_at"`
+}
+
+// Deck is the household's deck: the pending suggestions whose dinner is
+// still suggested, oldest first; the batch pending or running, if any, so
+// a client can follow the job producing more; and the newest batch when it
+// failed, so a client that was not following its job still learns of the
+// failure. At most one of ActiveBatch and FailedBatch is set: a batch is
+// only started when none is pending or running, so the active batch is
+// always the newest.
+type Deck struct {
+	Suggestions []Suggestion `json:"suggestions"`
+	ActiveBatch *Batch       `json:"active_batch"`
+	FailedBatch *Batch       `json:"failed_batch"`
+}
+
+// Deck reads the deck and its active and failed batches in one
+// transaction, so all come from the same snapshot. It is a write
+// transaction because reading the active batch first fails any batch whose
+// job has ended (see activeBatch), which is then the failed batch.
+func (s *Service) Deck(ctx context.Context) (Deck, error) {
+	var deck Deck
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		rows, err := q.ListDeck(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: list deck: %w", err)
+		}
+		deck.Suggestions = make([]Suggestion, len(rows))
+		for i, row := range rows {
+			deck.Suggestions[i], err = fromRow(row.Suggestion, row.Dinner)
+			if err != nil {
+				return err
+			}
+		}
+		deck.ActiveBatch, err = s.activeBatch(ctx, q)
+		if err != nil || deck.ActiveBatch != nil {
+			return err
+		}
+		deck.FailedBatch, err = failedBatch(ctx, q)
+		return err
+	})
+	if err != nil {
+		return Deck{}, err
+	}
+	return deck, 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.
+type Decision struct {
+	Suggestion     Suggestion `json:"suggestion"`
+	ReplenishJobID *string    `json:"replenish_job_id"`
+}
+
+// Accept records Try it on suggestion id, moving its dinner to the Quest
+// log and recording updatedBy on it.
+func (s *Service) Accept(ctx context.Context, id, updatedBy string) (Decision, error) {
+	return s.decide(ctx, id, StatusAccepted, dinners.StatusQuestLog, updatedBy)
+}
+
+// Decline records Pass on suggestion id, archiving its dinner and
+// recording updatedBy on it. The suggestion keeps the name its dish was
+// suggested under, whatever the dinner is later renamed, and every later
+// batch reads it as declined, so the dish is never suggested again.
+func (s *Service) Decline(ctx context.Context, id, updatedBy string) (Decision, error) {
+	return s.decide(ctx, id, StatusDeclined, dinners.StatusArchived, updatedBy)
+}
+
+// decide records decision on suggestion id and moves its dinner to
+// dinnerStatus. Repeating a decision changes nothing and returns the
+// suggestion as it is; the opposite decision is a *DecidedError. A
+// decision that leaves the deck under ReplenishBelow starts a replenish
+// batch, or joins the one already pending or running, in the decision's own
+// transaction, and returns its job id either way: the decision is never recorded without the replenish it
+// calls for, and a failure to start the batch records neither.
+func (s *Service) decide(ctx context.Context, id, decision, dinnerStatus, updatedBy string) (Decision, error) {
+	if updatedBy == "" {
+		return Decision{}, errors.New("suggest: decide: no member to record as updated_by")
+	}
+	var row db.GetSuggestionRow
+	var replenish *Batch
+	err := s.st.WithTx(ctx, func(tx *sql.Tx) error {
+		q := db.New(tx)
+		cur, err := q.GetSuggestion(ctx, id)
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrNotFound
+		}
+		if err != nil {
+			return fmt.Errorf("suggest: read suggestion %s: %w", id, err)
+		}
+		switch cur.Suggestion.Status {
+		case decision:
+			row = cur
+			return nil
+		case StatusPending:
+		default:
+			return &DecidedError{Status: cur.Suggestion.Status}
+		}
+		if cur.Dinner.Status != dinners.StatusSuggested {
+			return ErrDinnerNotSuggested
+		}
+		now := store.Now().String()
+		if _, err := q.DecideSuggestion(ctx, db.DecideSuggestionParams{
+			Status: decision,
+			Now:    sql.NullString{String: now, Valid: true},
+			ID:     id,
+		}); err != nil {
+			return fmt.Errorf("suggest: decide %s: %w", id, err)
+		}
+		if _, err := q.MoveSuggestedDinner(ctx, db.MoveSuggestedDinnerParams{
+			Status:    dinnerStatus,
+			UpdatedBy: sql.NullString{String: updatedBy, Valid: true},
+			UpdatedAt: now,
+			ID:        cur.Dinner.ID,
+		}); err != nil {
+			return fmt.Errorf("suggest: move dinner %s: %w", cur.Dinner.ID, err)
+		}
+		row, err = q.GetSuggestion(ctx, id)
+		if err != nil {
+			return fmt.Errorf("suggest: read suggestion %s: %w", id, err)
+		}
+		left, err := q.CountDeck(ctx)
+		if err != nil {
+			return fmt.Errorf("suggest: count deck: %w", err)
+		}
+		if left >= ReplenishBelow {
+			return nil
+		}
+		b, err := s.startBatch(ctx, tx, TriggerReplenish)
+		if err != nil {
+			return err
+		}
+		replenish = &b
+		return nil
+	})
+	if err != nil {
+		return Decision{}, err
+	}
+	if replenish != nil && replenish.Created {
+		s.batchJob.Wake()
+	}
+	sug, err := fromRow(row.Suggestion, row.Dinner)
+	if err != nil {
+		return Decision{}, err
+	}
+	d := Decision{Suggestion: sug}
+	if replenish != nil {
+		d.ReplenishJobID = &replenish.JobID
+	}
+	return d, nil
+}
+
+func fromRow(sg db.Suggestion, d db.Dinner) (Suggestion, error) {
+	out := Suggestion{
+		ID:           sg.ID,
+		DinnerID:     d.ID,
+		Name:         d.Name,
+		Difficulty:   nullString(d.Difficulty),
+		Method:       nullString(d.Method),
+		Cuisine:      nullString(d.Cuisine),
+		Reason:       sg.Reason,
+		Status:       sg.Status,
+		DinnerStatus: d.Status,
+		DecidedAt:    nullString(sg.DecidedAt),
+		CreatedAt:    sg.CreatedAt,
+	}
+	if err := json.Unmarshal([]byte(sg.CitedRegularIds), &out.CitedRegularIDs); err != nil || out.CitedRegularIDs == nil {
+		return Suggestion{}, fmt.Errorf("suggest: suggestion %s cited_regular_ids is not a JSON array: %q", sg.ID, sg.CitedRegularIds)
+	}
+	if d.MinutesTotal.Valid {
+		out.MinutesTotal = &d.MinutesTotal.Int64
+	}
+	if d.PhotoID.Valid {
+		u := dinners.PhotoURL(d.PhotoID.String)
+		out.PhotoURL = &u
+	}
+	return out, nil
+}
+
+func nullString(s sql.NullString) *string {
+	if !s.Valid {
+		return nil
+	}
+	return &s.String
+}

migrations/0012_suggestion_name.sql

@@ -0,0 +1,37 @@
+-- 0012_suggestion_name: a suggestion keeps the name its dish was suggested
+-- under. Its dinner can be renamed, even once archived by a Pass, so the
+-- declined names every later batch refuses are read from here, never from
+-- the dinner. A suggestion stored before this takes its dinner's name now.
+-- SQLite cannot add a NOT NULL column without a default, so the table is
+-- rebuilt as 0005 does: copy the rows aside, drop the table, create it
+-- again, copy the rows back and drop the copy. Nothing references
+-- suggestions.
+
+CREATE TABLE suggestions_copy AS SELECT * FROM suggestions;
+
+DROP TABLE suggestions;
+
+CREATE TABLE suggestions (
+	id                TEXT NOT NULL PRIMARY KEY,
+	dinner_id         TEXT NOT NULL REFERENCES dinners (id),
+	batch_id          TEXT NOT NULL REFERENCES suggestion_batches (id),
+	name              TEXT NOT NULL CHECK (name <> ''),
+	reason            TEXT NOT NULL,
+	cited_regular_ids TEXT NOT NULL, -- JSON array of dinner ids
+	status            TEXT NOT NULL CHECK (status IN ('pending', 'accepted', 'declined')),
+	decided_at        TEXT,
+	created_at        TEXT NOT NULL,
+	updated_at        TEXT NOT NULL
+);
+
+INSERT INTO suggestions (
+	id, dinner_id, batch_id, name, reason, cited_regular_ids, status, decided_at, created_at, updated_at
+)
+SELECT
+	suggestions_copy.id, suggestions_copy.dinner_id, suggestions_copy.batch_id, dinners.name,
+	suggestions_copy.reason, suggestions_copy.cited_regular_ids, suggestions_copy.status,
+	suggestions_copy.decided_at, suggestions_copy.created_at, suggestions_copy.updated_at
+FROM suggestions_copy
+JOIN dinners ON dinners.id = suggestions_copy.dinner_id;
+
+DROP TABLE suggestions_copy;

migrations/0013_week_plan_revision.sql

@@ -0,0 +1,6 @@
+-- 0013_week_plan_revision: every edit of a week's plan — a swap or a
+-- stored draft — raises its revision. A draft_week job reads the revision
+-- before draft_week runs and stores its week only while the plan still
+-- has it, so a draft never overwrites an edit made while the AI ran.
+
+ALTER TABLE week_plans ADD COLUMN revision INTEGER NOT NULL DEFAULT 0;

migrations/0014_rotation_review_name.sql

@@ -0,0 +1,43 @@
+-- 0014_rotation_review_name: a Rotation check decided drop ("Not for us")
+-- keeps the name its dinner had when the household dropped it. The dinner
+-- can be renamed, even once archived, so the passed names every later
+-- batch refuses are read from here, never from the dinner, as 0012 does
+-- for a Pass. Only a drop has a name. A check dropped before this takes
+-- its dinner's name now.
+-- SQLite cannot add a column with a CHECK that existing drops would fail
+-- before they are filled in, so the table is rebuilt as 0012 does: copy
+-- the rows aside, drop the table, create it again, copy the rows back and
+-- drop the copy. Nothing references rotation_reviews.
+
+CREATE TABLE rotation_reviews_copy AS SELECT * FROM rotation_reviews;
+
+DROP TABLE rotation_reviews;
+
+CREATE TABLE rotation_reviews (
+	id         TEXT NOT NULL PRIMARY KEY,
+	dinner_id  TEXT NOT NULL REFERENCES dinners (id),
+	plan_date  TEXT NOT NULL,
+	status     TEXT NOT NULL CHECK (status IN ('pending', 'decided')),
+	decision   TEXT CHECK (decision IN ('keep', 'drop', 'not_made')),
+	name       TEXT CHECK (name <> ''), -- the dinner's name when dropped
+	decided_at TEXT,
+	updated_by TEXT,
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL,
+	UNIQUE (dinner_id, plan_date),
+	CHECK ((decision IS 'drop') = (name IS NOT NULL))
+);
+
+INSERT INTO rotation_reviews (
+	id, dinner_id, plan_date, status, decision, name, decided_at, updated_by, created_at, updated_at
+)
+SELECT
+	rotation_reviews_copy.id, rotation_reviews_copy.dinner_id, rotation_reviews_copy.plan_date,
+	rotation_reviews_copy.status, rotation_reviews_copy.decision,
+	CASE WHEN rotation_reviews_copy.decision = 'drop' THEN dinners.name END,
+	rotation_reviews_copy.decided_at, rotation_reviews_copy.updated_by,
+	rotation_reviews_copy.created_at, rotation_reviews_copy.updated_at
+FROM rotation_reviews_copy
+JOIN dinners ON dinners.id = rotation_reviews_copy.dinner_id;
+
+DROP TABLE rotation_reviews_copy;

migrations/queries/dinners.sql

@@ -19,6 +19,19 @@ SELECT * FROM dinners
 WHERE status = ?
 ORDER BY normalized_name, id;
 
+-- name: ListUnplannedQuestLogDinners :many
+-- The Quest log: dinners with status quest_log that no plan for the week
+-- starting from_week_start or later has on any day.
+SELECT * FROM dinners
+WHERE status = 'quest_log'
+  AND NOT EXISTS (
+	SELECT 1 FROM plan_days
+	JOIN week_plans ON week_plans.id = plan_days.plan_id
+	WHERE plan_days.dinner_id = dinners.id
+	  AND week_plans.week_start >= sqlc.arg(from_week_start)
+  )
+ORDER BY normalized_name, id;
+
 -- name: CountRegularDinners :one
 -- How many Regulars the household has; archived dinners are not counted.
 SELECT COUNT(*) FROM dinners
@@ -118,9 +131,11 @@ RETURNING *;
 -- 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,
 -- minutes_total or difficulty already set is kept: a pending dinner has
--- them only when a member edited them while it was grounding.
+-- them only when a member edited them while it was grounding. Like
+-- GroundDinner it clears the pasted recipe_url: the recipe replaces the link.
 UPDATE dinners
 SET recipe_id = sqlc.arg(recipe_id),
+	recipe_url = NULL,
 	photo_id = sqlc.arg(photo_id),
 	method = COALESCE(method, sqlc.arg(method)),
 	minutes_total = COALESCE(minutes_total, sqlc.arg(minutes_total)),

migrations/queries/household_context.sql

@@ -1,12 +1,18 @@
 -- Reads for the AI household context block (internal/ai/harness).
 
--- name: ListRecentDeclinedNames :many
--- The names of the most recently declined suggestions, newest first.
-SELECT dinners.name
-FROM suggestions
-JOIN dinners ON dinners.id = suggestions.dinner_id
-WHERE suggestions.status = 'declined'
-ORDER BY suggestions.decided_at DESC, suggestions.id DESC
+-- name: ListRecentPassedNames :many
+-- The most recent names the household turned down, newest first, as
+-- ListPassedNames has them.
+SELECT name FROM (
+	SELECT name, decided_at, id
+	FROM suggestions
+	WHERE status = 'declined'
+	UNION ALL
+	SELECT name, decided_at, id
+	FROM rotation_reviews
+	WHERE decision = 'drop'
+)
+ORDER BY decided_at DESC, id DESC
 LIMIT ?;
 
 -- name: ListPlannedDinners :many

migrations/queries/plans.sql

@@ -0,0 +1,86 @@
+-- name: GetWeekPlan :one
+-- The plan of the week starting week_start. Returns sql.ErrNoRows when
+-- there is none.
+SELECT * FROM week_plans
+WHERE week_start = ?;
+
+-- name: ListPlanDays :many
+-- The days of plan plan_id with their dinners, Monday first. A day with
+-- no dinner is left out.
+SELECT plan_days.date, plan_days.is_new, sqlc.embed(dinners)
+FROM plan_days
+JOIN dinners ON dinners.id = plan_days.dinner_id
+WHERE plan_days.plan_id = ?
+ORDER BY plan_days.date;
+
+-- name: CreateWeekPlan :exec
+INSERT INTO week_plans (id, week_start, status, ai_note, created_at, updated_at)
+VALUES (?, ?, 'draft', ?, ?, ?);
+
+-- name: RedraftWeekPlan :exec
+-- Records a new draft over plan id: its status and note, raising its
+-- revision.
+UPDATE week_plans
+SET status = ?, ai_note = ?, revision = revision + 1, updated_at = ?
+WHERE id = ?;
+
+-- name: PutPlanDay :exec
+-- Plans dinner_id on date of plan_id, keeping the day's calendar event id
+-- when the day exists.
+INSERT INTO plan_days (id, plan_id, date, dinner_id, is_new, created_at, updated_at)
+VALUES (?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT (plan_id, date) DO UPDATE
+SET dinner_id = excluded.dinner_id, is_new = excluded.is_new, updated_at = excluded.updated_at;
+
+-- name: SwapPlanDay :execrows
+-- Plans dinner_id on an existing day of plan_id; a date the plan does not
+-- have is left as it is (0 rows).
+UPDATE plan_days
+SET dinner_id = ?, is_new = ?, updated_at = ?
+WHERE plan_id = ? AND date = ?;
+
+-- name: MarkWeekPlanEdited :exec
+-- Records an edit of plan id, raising its revision: a synced plan becomes
+-- changed, any other keeps its status.
+UPDATE week_plans
+SET status = CASE WHEN status = 'synced' THEN 'changed' ELSE status END,
+	revision = revision + 1,
+	updated_at = ?
+WHERE id = ?;
+
+-- name: ListDraftPool :many
+-- The dinners a draft of the week starting week_start may plan: every
+-- Regular, and every Quest log dinner no other plan for the week starting
+-- from_week_start or later has on any day.
+SELECT * FROM dinners
+WHERE status = 'regular'
+	OR (status = 'quest_log' AND NOT EXISTS (
+		SELECT 1 FROM plan_days
+		JOIN week_plans ON week_plans.id = plan_days.plan_id
+		WHERE plan_days.dinner_id = dinners.id
+			AND week_plans.week_start >= sqlc.arg(from_week_start)
+			AND week_plans.week_start <> sqlc.arg(week_start)
+	))
+ORDER BY normalized_name, id;
+
+-- name: ListWeekPlanDinnerIDs :many
+-- The ids of the dinners planned in the week starting week_start, Monday
+-- first.
+SELECT plan_days.dinner_id
+FROM plan_days
+JOIN week_plans ON week_plans.id = plan_days.plan_id
+WHERE week_plans.week_start = ? AND plan_days.dinner_id IS NOT NULL
+ORDER BY plan_days.date;
+
+-- name: GetActiveDraftJob :one
+-- The job of kind queued or running for the week starting week_start,
+-- with whether its payload has confirm. StartDraft enqueues a draft only
+-- when there is none, so there is at most one. Returns sql.ErrNoRows when
+-- there is none.
+SELECT id, CAST(json_extract(payload, '$.confirm') = 1 AS INTEGER) AS confirmed
+FROM jobs
+WHERE kind = sqlc.arg(kind)
+	AND status IN ('queued', 'running')
+	AND json_extract(payload, '$.week_start') = sqlc.arg(week_start)
+ORDER BY id
+LIMIT 1;

migrations/queries/rotation_reviews.sql

@@ -0,0 +1,66 @@
+-- name: ListTriedCandidates :many
+-- The ids of the dinners with status quest_log planned on date, on a plan
+-- of any status, that have no Rotation check for date yet.
+SELECT DISTINCT dinners.id
+FROM plan_days
+JOIN dinners ON dinners.id = plan_days.dinner_id
+WHERE plan_days.date = sqlc.arg(date)
+	AND dinners.status = 'quest_log'
+	AND NOT EXISTS (
+		SELECT 1 FROM rotation_reviews
+		WHERE rotation_reviews.dinner_id = dinners.id
+			AND rotation_reviews.plan_date = plan_days.date
+	)
+ORDER BY dinners.id;
+
+-- name: MarkDinnerTried :execrows
+-- Moves a dinner still in the Quest log to tried; a dinner with any other
+-- status is left as it is (0 rows).
+UPDATE dinners
+SET status = 'tried', updated_at = ?
+WHERE id = ? AND status = 'quest_log';
+
+-- name: CreateRotationReview :exec
+INSERT INTO rotation_reviews (id, dinner_id, plan_date, status, created_at, updated_at)
+VALUES (?, ?, ?, 'pending', ?, ?);
+
+-- name: ListPendingRotationReviews :many
+-- The pending Rotation checks whose dinner is still tried, oldest plan
+-- date first, with their dinners.
+SELECT rotation_reviews.plan_date, sqlc.embed(dinners)
+FROM rotation_reviews
+JOIN dinners ON dinners.id = rotation_reviews.dinner_id
+WHERE rotation_reviews.status = 'pending' AND dinners.status = 'tried'
+ORDER BY rotation_reviews.plan_date, rotation_reviews.id;
+
+-- name: GetPendingRotationReview :one
+-- The pending Rotation check of dinner_id. MarkTried makes one only for a
+-- dinner in the Quest log, which it moves to tried, so a dinner has at
+-- most one. Returns sql.ErrNoRows when there is none.
+SELECT * FROM rotation_reviews
+WHERE dinner_id = ? AND status = 'pending';
+
+-- name: CountRotationReviews :one
+-- How many Rotation checks dinner_id has had, pending or decided.
+SELECT COUNT(*) FROM rotation_reviews WHERE dinner_id = ?;
+
+-- name: DecideRotationReview :execrows
+-- Records the household's decision on a pending Rotation check, with the
+-- dinner's name for a drop and NULL otherwise; one already decided is left
+-- as it is (0 rows).
+UPDATE rotation_reviews
+SET status = 'decided',
+	decision = sqlc.arg(decision),
+	name = sqlc.narg(name),
+	decided_at = sqlc.arg(now),
+	updated_by = sqlc.arg(updated_by),
+	updated_at = sqlc.arg(now)
+WHERE id = sqlc.arg(id) AND status = 'pending';
+
+-- name: MoveTriedDinner :execrows
+-- Moves a dinner still tried to status (regular, archived or quest_log)
+-- by a Rotation check decision, recording updated_by; its origin is kept.
+-- A dinner no longer tried is left as it is (0 rows).
+UPDATE dinners
+SET status = sqlc.arg(status), updated_by = sqlc.arg(updated_by), updated_at = sqlc.arg(updated_at)
+WHERE id = sqlc.arg(id) AND status = 'tried';

migrations/queries/suggestions.sql

@@ -0,0 +1,118 @@
+-- name: CreateSuggestionBatch :one
+INSERT INTO suggestion_batches (id, trigger, status, created_at, updated_at)
+VALUES (?, ?, 'pending', ?, ?)
+RETURNING *;
+
+-- name: GetActiveSuggestionBatch :one
+-- The batch still pending or running, oldest first. Returns sql.ErrNoRows
+-- when there is none.
+SELECT * FROM suggestion_batches
+WHERE status IN ('pending', 'running')
+ORDER BY id
+LIMIT 1;
+
+-- name: GetLatestSuggestionBatch :one
+-- The newest batch, whatever its status. Returns sql.ErrNoRows when there
+-- is none.
+SELECT * FROM suggestion_batches
+ORDER BY id DESC
+LIMIT 1;
+
+-- name: GetSuggestionBatchJobID :one
+-- The id of the job that runs batch batch_id.
+SELECT id FROM jobs
+WHERE kind = sqlc.arg(kind)
+	AND json_extract(payload, '$.batch_id') = sqlc.arg(batch_id)
+ORDER BY id
+LIMIT 1;
+
+-- name: StartSuggestionBatch :execrows
+-- Marks a pending batch running; a batch in any other status is left as
+-- it is (0 rows).
+UPDATE suggestion_batches
+SET status = 'running', updated_at = ?
+WHERE id = ? AND status = 'pending';
+
+-- name: FinishSuggestionBatch :execrows
+-- Records a pending or running batch as done or failed; a batch already
+-- finished is left as it is (0 rows).
+UPDATE suggestion_batches
+SET status = ?, updated_at = ?
+WHERE id = ? AND status IN ('pending', 'running');
+
+-- name: FailOrphanedSuggestionBatches :execrows
+-- Fails every batch still pending or running whose job is no longer queued
+-- or running: the process stopped, or recording the batch's end failed,
+-- before its handler recorded a result. Run before reading the active batch.
+UPDATE suggestion_batches
+SET status = 'failed', updated_at = sqlc.arg(updated_at)
+WHERE status IN ('pending', 'running')
+	AND NOT EXISTS (
+		SELECT 1 FROM jobs
+		WHERE jobs.kind = sqlc.arg(kind)
+			AND jobs.status IN ('queued', 'running')
+			AND json_extract(jobs.payload, '$.batch_id') = suggestion_batches.id
+	);
+
+-- name: CreateSuggestion :exec
+-- name is the name the dish is suggested under, kept whatever its dinner is
+-- later renamed.
+INSERT INTO suggestions (
+	id, dinner_id, batch_id, name, reason, cited_regular_ids, status, created_at, updated_at
+) VALUES (
+	?, ?, ?, ?, ?, ?, 'pending', ?, ?
+);
+
+-- name: GetSuggestion :one
+-- A suggestion with its dinner. Returns sql.ErrNoRows for an unknown id.
+SELECT sqlc.embed(suggestions), sqlc.embed(dinners)
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.id = ?;
+
+-- name: ListDeck :many
+-- The pending suggestions whose dinner is still suggested, oldest first,
+-- with their dinners.
+SELECT sqlc.embed(suggestions), sqlc.embed(dinners)
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.status = 'pending' AND dinners.status = 'suggested'
+ORDER BY suggestions.created_at, suggestions.id;
+
+-- name: CountDeck :one
+-- How many suggestions ListDeck returns.
+SELECT COUNT(*)
+FROM suggestions
+JOIN dinners ON dinners.id = suggestions.dinner_id
+WHERE suggestions.status = 'pending' AND dinners.status = 'suggested';
+
+-- name: ListPassedNames :many
+-- Every name the household turned down, oldest decision first: the name
+-- each declined suggestion was suggested under, which renaming its dinner
+-- does not change, and the name each dinner a Rotation check dropped
+-- ("Not for us") had when dropped, which renaming it does not change.
+SELECT name FROM (
+	SELECT name, decided_at, id
+	FROM suggestions
+	WHERE status = 'declined'
+	UNION ALL
+	SELECT name, decided_at, id
+	FROM rotation_reviews
+	WHERE decision = 'drop'
+)
+ORDER BY decided_at, id;
+
+-- name: DecideSuggestion :execrows
+-- Records the household's decision on a pending suggestion; one already
+-- decided is left as it is (0 rows).
+UPDATE suggestions
+SET status = sqlc.arg(status), decided_at = sqlc.arg(now), updated_at = sqlc.arg(now)
+WHERE id = sqlc.arg(id) AND status = 'pending';
+
+-- name: MoveSuggestedDinner :execrows
+-- Moves a dinner still suggested to status (quest_log or archived),
+-- recording updated_by; a dinner no longer suggested is left as it is
+-- (0 rows).
+UPDATE dinners
+SET status = sqlc.arg(status), updated_by = sqlc.arg(updated_by), updated_at = sqlc.arg(updated_at)
+WHERE id = sqlc.arg(id) AND status = 'suggested';

web/src/App.test.tsx

@@ -1,4 +1,4 @@
-import { act, render, screen } from '@testing-library/react'
+import { act, cleanup, render, screen } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createApiClient, createVerifiedSession } from './api/index.ts'
 import { createNetworkStatus } from './pwa/networkStatus.ts'
@@ -30,6 +30,8 @@ function renderAppAt(path: string, location = fakeLocation(path)) {
 // The routes that render a built screen rather than a placeholder page.
 const SCREENS = {
   '/onboarding': true,
+  '/plan': true,
+  '/discover': true,
   '/settings': true,
   '/settings/ai': true,
   '/settings/household': true,
@@ -102,6 +104,19 @@ describe('App routes', () => {
     expect(await screen.findByText('••••••••3f9a')).toBeInTheDocument()
   })
 
+  it('/discover renders the Side quests deck inside the shell', async () => {
+    mockViewport(390)
+    stubFetchByPath({
+      ...SIGNED_IN,
+      '/api/v1/suggestions/deck': () => jsonResponse(200, { suggestions: [], active_batch: null, failed_batch: null }),
+      '/api/v1/dinners?status=quest_log': () => jsonResponse(200, { dinners: [] }),
+    })
+    renderAt('/discover')
+    const heading = await screen.findByRole('heading', { level: 1, name: 'Side quests' })
+    expect(screen.getByRole('main')).toContainElement(heading)
+    expect(await screen.findByText('Quest log · 0')).toBeInTheDocument()
+  })
+
   it('/settings/household renders the household settings screen inside the shell', async () => {
     mockViewport(390)
     stubFetchByPath(SIGNED_IN)
@@ -151,19 +166,19 @@ describe('App first-run redirect', () => {
   it('opens the routes once onboarding is finished', async () => {
     mockViewport(390)
     stubFetchByPath(SIGNED_IN)
-    renderAt('/plan')
-    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    renderAt('/quick')
+    expect(await screen.findByRole('heading', { level: 1, name: 'Quick dinners' })).toBeInTheDocument()
   })
 
   it('reports a household settings failure with a retry instead of rendering the routes', async () => {
     mockViewport(390)
     stubFetch(jsonResponse(200, ME), errorResponse(500, 'internal'), jsonResponse(200, HOUSEHOLD_SETTINGS))
-    renderAt('/plan')
+    renderAt('/quick')
 
     expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: internal message')
     expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
     screen.getByRole('button', { name: 'Retry' }).click()
-    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(await screen.findByRole('heading', { level: 1, name: 'Quick dinners' })).toBeInTheDocument()
   })
 })
 
@@ -171,12 +186,12 @@ describe('App bootstrap', () => {
   it('shows the skeleton until /me loads, then the routes', async () => {
     mockViewport(390)
     const fetchMock = stubFetch(jsonResponse(200, ME), jsonResponse(200, HOUSEHOLD_SETTINGS))
-    renderAt('/plan')
+    renderAt('/quick')
 
     expect(screen.getByRole('main', { name: 'Loading MealQuest' })).toHaveAttribute('aria-busy', 'true')
     expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
 
-    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(await screen.findByRole('heading', { level: 1, name: 'Quick dinners' })).toBeInTheDocument()
     expect(screen.queryByRole('main', { name: 'Loading MealQuest' })).not.toBeInTheDocument()
     expect(request(fetchMock, 0)).toMatchObject({ path: '/api/v1/me', method: 'GET', credentials: 'same-origin' })
   })
@@ -236,8 +251,15 @@ describe('App offline bootstrap', () => {
     vi.spyOn(navigator, 'onLine', 'get').mockImplementation(() => onLine)
   })
 
+  // A test that emits an offline event leaves TanStack Query's online
+  // manager, shared by every test, offline until an online event.
+  afterEach(() => {
+    cleanup()
+    window.dispatchEvent(new Event('online'))
+  })
+
   it.each([
-    ['/plan', 'Plan'],
+    ['/quick', 'Quick dinners'],
     ['/dinner/01J9ZK', 'Dinner'],
   ])('an offline reload of %s after an online visit opens the saved page', async (path, title) => {
     await visitOnline()
@@ -250,18 +272,43 @@ describe('App offline bootstrap', () => {
     expect(screen.queryByRole('alert')).not.toBeInTheDocument()
   })
 
+  it('opens the saved page when the browser has emitted an offline event', async () => {
+    await visitOnline()
+    // /me is still loading, with the app mounted, when the browser emits
+    // its offline event; only then does /me fail.
+    let failMe!: () => void
+    vi.stubGlobal(
+      'fetch',
+      vi.fn<typeof fetch>().mockImplementationOnce(
+        () => new Promise((_, reject) => (failMe = () => reject(new TypeError('Failed to fetch')))),
+      ).mockRejectedValue(new TypeError('Failed to fetch')),
+    )
+    renderAt('/quick')
+    await vi.waitFor(() => expect(failMe).toBeDefined())
+    onLine = false
+    act(() => {
+      window.dispatchEvent(new Event('offline'))
+    })
+    act(() => failMe())
+
+    expect(await screen.findByRole('heading', { level: 1, name: 'Quick dinners' })).toBeInTheDocument()
+    expect(screen.queryByRole('main', { name: 'Loading MealQuest' })).not.toBeInTheDocument()
+    expect(screen.getByRole('status')).toHaveTextContent('Offline — showing saved data')
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
   it('opens the saved pages when the server is unreachable but the browser reports online', async () => {
     await visitOnline()
     vi.stubGlobal('fetch', vi.fn<typeof fetch>().mockRejectedValue(new TypeError('Failed to fetch')))
-    renderAt('/plan')
+    renderAt('/quick')
 
-    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(await screen.findByRole('heading', { level: 1, name: 'Quick dinners' })).toBeInTheDocument()
     expect(screen.getByRole('status')).toHaveTextContent('Offline — showing saved data')
   })
 
   it('reports the failure offline when this device never verified a session', async () => {
     goOffline()
-    renderAt('/plan')
+    renderAt('/quick')
 
     expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: Failed to fetch')
     expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
@@ -270,12 +317,12 @@ describe('App offline bootstrap', () => {
   it('reports the failure offline after the session was refused', async () => {
     await visitOnline()
     stubFetch(errorResponse(401, 'unauthenticated'))
-    const { location, unmount } = renderAt('/plan')
+    const { location, unmount } = renderAt('/quick')
     await vi.waitFor(() => expect(location.assign).toHaveBeenCalled())
     unmount()
 
     goOffline()
-    renderAt('/plan')
+    renderAt('/quick')
     expect(await screen.findByRole('alert')).toHaveTextContent('MealQuest could not load: Failed to fetch')
     expect(screen.queryByRole('navigation', { name: 'Primary' })).not.toBeInTheDocument()
   })
@@ -283,13 +330,13 @@ describe('App offline bootstrap', () => {
   it('loads /me again on reconnect and refuses writes until it has', async () => {
     await visitOnline()
     goOffline()
-    const api = createApiClient(fakeLocation('/plan'), createNetworkStatus(window), createVerifiedSession(localStorage))
+    const api = createApiClient(fakeLocation('/quick'), createNetworkStatus(window), createVerifiedSession(localStorage))
     render(
-      <InDataRouter path="/plan">
+      <InDataRouter path="/quick">
         <App api={api} serviceWorker={undefined} />
       </InDataRouter>,
     )
-    expect(await screen.findByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(await screen.findByRole('heading', { level: 1, name: 'Quick dinners' })).toBeInTheDocument()
     await expect(api.apiFetch('/api/v1/plans', { method: 'POST', body: {} })).rejects.toThrow(/no CSRF token/)
 
     const fetchMock = stubFetchByPath(SIGNED_IN)
@@ -304,6 +351,6 @@ describe('App offline bootstrap', () => {
       ]),
     )
     await vi.waitFor(() => expect(screen.queryByRole('status')).toBeNull())
-    expect(screen.getByRole('heading', { level: 1, name: 'Plan' })).toBeInTheDocument()
+    expect(screen.getByRole('heading', { level: 1, name: 'Quick dinners' })).toBeInTheDocument()
   })
 })

web/src/App.tsx

@@ -3,9 +3,11 @@ import { QueryClientProvider } from '@tanstack/react-query'
 import { Route, Routes } from 'react-router'
 import { ApiProvider, createQueryClient, type ApiClient } from './api/index.ts'
 import { AuthBootstrap } from './AuthBootstrap.tsx'
+import { DiscoverPage } from './discover/DiscoverPage.tsx'
 import { ONBOARDING_PATH, OnboardingGate } from './onboarding/OnboardingGate.tsx'
 import { OnboardingPage } from './onboarding/OnboardingPage.tsx'
 import { PlaceholderPage } from './pages/PlaceholderPage.tsx'
+import { PlanPage } from './plan/PlanPage.tsx'
 import { OfflinePill } from './pwa/OfflinePill.tsx'
 import { UpdatePrompt, type UpdateContainer } from './pwa/UpdatePrompt.tsx'
 import { AISettingsPage } from './settings/AISettingsPage.tsx'
@@ -35,6 +37,8 @@ export const routes = [
 
 // The screens built so far; every other route shows its placeholder page.
 const screens: Partial<Record<(typeof routes)[number]['path'], ReactNode>> = {
+  '/plan': <PlanPage />,
+  '/discover': <DiscoverPage />,
   '/settings': <SettingsPage />,
   '/settings/ai': <AISettingsPage />,
   '/settings/household': <HouseholdSettingsPage />,

web/src/api/client.test.ts

@@ -225,4 +225,14 @@ describe('network status', () => {
     await expect(api.apiFetch('/api/v1/recipes/01J9ZR')).resolves.toEqual({ id: '01J9ZR' })
     expect(api.network.offline()).toBe(false)
   })
+
+  it('says whether a read is the service worker\'s cached copy', async () => {
+    const cached = jsonResponse(200, { id: '01J9ZR' })
+    cached.headers.set(cacheFallbackHeader, '1')
+    stubFetch(cached, jsonResponse(200, { id: '01J9ZR' }))
+    const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
+
+    await expect(api.apiRead('/api/v1/recipes/01J9ZR')).resolves.toEqual({ body: { id: '01J9ZR' }, cached: true })
+    await expect(api.apiRead('/api/v1/recipes/01J9ZR')).resolves.toEqual({ body: { id: '01J9ZR' }, cached: false })
+  })
 })

web/src/api/client.ts

@@ -43,11 +43,18 @@ export type ApiRequest = {
   body?: unknown
 }
 
+// ApiRead is a GET's decoded response body, and whether the service worker
+// answered it from its cache because the server could not be reached in time.
+export type ApiRead<T> = { body: T; cached: boolean }
+
 export type ApiClient = {
   // apiFetch sends a same-origin JSON request to path, which must be under
   // /api/v1/, and resolves with the decoded response body, or rejects with an
   // ApiError.
   apiFetch<T>(path: string, request?: ApiRequest): Promise<T>
+  // apiRead is apiFetch's GET that also says whether the body is the service
+  // worker's cached copy rather than the server's answer.
+  apiRead<T>(path: string): Promise<ApiRead<T>>
   // loadMe fetches GET /api/v1/me and caches its CSRF token.
   loadMe(): Promise<Me>
   // forbidden reports whether a request was refused because the signed-in
@@ -114,6 +121,16 @@ export function createApiClient(location: ApiLocation, network: NetworkStatus, s
   }
 
   async function apiFetch<T>(path: string, request: ApiRequest = {}): Promise<T> {
+    return (await exchange<T>(path, request)).body
+  }
+
+  function apiRead<T>(path: string): Promise<ApiRead<T>> {
+    return exchange<T>(path, {})
+  }
+
+  // exchange sends request to path and decodes the response, noting whether
+  // it is the service worker's cached copy.
+  async function exchange<T>(path: string, request: ApiRequest): Promise<ApiRead<T>> {
     const method = request.method ?? 'GET'
     const url = apiURL(location.origin, method, path)
     // fetch refuses a GET with a body by rejecting with a TypeError, the same
@@ -131,7 +148,7 @@ export function createApiClient(location: ApiLocation, network: NetworkStatus, s
       response = await send(method, url, request.body)
       if (response.status === 403) throw await parseForbidden(method, path, response)
     }
-    return decode<T>(method, path, response)
+    return { body: await decode<T>(method, path, response), cached: response.headers.has(cacheFallbackHeader) }
   }
 
   // parseForbidden reads a 403. Any API error other than csrf means the
@@ -179,6 +196,7 @@ export function createApiClient(location: ApiLocation, network: NetworkStatus, s
 
   return {
     apiFetch,
+    apiRead,
     loadMe,
     forbidden: () => forbidden,
     subscribe(listener) {

web/src/api/index.ts

@@ -1,5 +1,5 @@
 export { ApiProvider, useApi } from './ApiContext.tsx'
-export { createApiClient, CSRF_HEADER, ME_PATH, type ApiClient, type ApiLocation, type ApiRequest, type Me } from './client.ts'
+export { createApiClient, CSRF_HEADER, ME_PATH, type ApiClient, type ApiRead, type ApiLocation, type ApiRequest, type Me } from './client.ts'
 export { ApiError } from './errors.ts'
 export { createQueryClient, shouldRetry } from './queryClient.ts'
 export { createVerifiedSession, VERIFIED_SESSION_KEY, type VerifiedSession } from './verifiedSession.ts'

web/src/api/useJob.test.tsx

@@ -14,7 +14,7 @@ function job(status: string, result: Draft | null, error: string | null = null)
 function renderJob(jobId: string | null) {
   const api = createApiClient(fakeLocation(), createNetworkStatus(window), createVerifiedSession(localStorage))
   const wrapper = ({ children }: { children: ReactNode }) => <ApiProvider client={api}>{children}</ApiProvider>
-  return renderHook(({ id }) => useJob<Draft>(id), { wrapper, initialProps: { id: jobId } })
+  return renderHook(({ id }) => useJob<Draft>('plan.draft', id), { wrapper, initialProps: { id: jobId } })
 }
 
 // advance runs the timers due in ms and lets the polls they start answer.
@@ -42,7 +42,7 @@ describe('useJob', () => {
       job('succeeded', { dinners: ['Tacos', 'Chili', 'Soup'] }),
     )
     const { result } = renderJob('j1')
-    expect(result.current).toEqual({ status: undefined, result: null, error: null })
+    expect(result.current).toMatchObject({ status: undefined, result: null, error: null })
 
     await advance(0)
     expect(result.current.status).toBe('queued')
@@ -51,7 +51,7 @@ describe('useJob', () => {
     await advance(499)
     expect(fetchMock).toHaveBeenCalledTimes(1)
     await advance(1)
-    expect(result.current).toEqual({ status: 'running', result: { dinners: ['Tacos'] }, error: null })
+    expect(result.current).toMatchObject({ status: 'running', result: { dinners: ['Tacos'] }, error: null })
 
     await advance(999)
     expect(fetchMock).toHaveBeenCalledTimes(2)
@@ -62,7 +62,7 @@ describe('useJob', () => {
     expect(fetchMock).toHaveBeenCalledTimes(4)
     await advance(2000)
     expect(fetchMock).toHaveBeenCalledTimes(5)
-    expect(result.current).toEqual({
+    expect(result.current).toMatchObject({
       status: 'succeeded',
       result: { dinners: ['Tacos', 'Chili', 'Soup'] },
       error: null,
@@ -106,10 +106,76 @@ describe('useJob', () => {
     expect(fetchMock).toHaveBeenCalledTimes(2)
     await advance(1)
     expect(fetchMock).toHaveBeenCalledTimes(3)
-    expect(result.current).toEqual({ status: 'succeeded', result: { dinners: ['Tacos', 'Chili'] }, error: null })
+    expect(result.current).toMatchObject({ status: 'succeeded', result: { dinners: ['Tacos', 'Chili'] }, error: null })
     expect(vi.getTimerCount()).toBe(0)
   })
 
+  it.each([
+    ['an unknown status', { id: 'j1', kind: 'plan.draft', status: 'stuck', result: null, error: null }],
+    ['another job', { id: 'j2', kind: 'plan.draft', status: 'running', result: null, error: null }],
+    ['another kind', { id: 'j1', kind: 'suggestion_batch', status: 'running', result: null, error: null }],
+    ['no result', { id: 'j1', kind: 'plan.draft', status: 'running', error: null }],
+    ['an error that is not text', { id: 'j1', kind: 'plan.draft', status: 'failed', result: null, error: 500 }],
+    ['not a job', ['j1']],
+  ])('exposes an answer with %s as the error and stops, keeping the last status', async (_, body) => {
+    const fetchMock = stubFetch(job('running', { dinners: ['Tacos'] }), jsonResponse(200, body))
+    const { result } = renderJob('j1')
+
+    await advance(0)
+    await advance(500)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    expect(result.current).toMatchObject({ status: 'running', result: { dinners: ['Tacos'] } })
+    expect(result.current.error?.message).toBe('GET /api/v1/jobs/j1: response is not the plan.draft job j1')
+    expect(vi.getTimerCount()).toBe(0)
+    await advance(10_000)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('polls again at once on poll after stopping on an answer that is not the job, then keeps polling', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(200, { id: 'j1', kind: 'plan.draft', status: 'stuck', result: null, error: null }),
+      job('running', { dinners: ['Tacos'] }),
+      job('succeeded', { dinners: ['Tacos', 'Chili'] }),
+    )
+    const { result } = renderJob('j1')
+    await advance(0)
+    expect(result.current.error).not.toBeNull()
+    expect(vi.getTimerCount()).toBe(0)
+
+    act(() => result.current.poll())
+    await advance(0)
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    expect(result.current).toMatchObject({ status: 'running', result: { dinners: ['Tacos'] }, error: null })
+    await advance(500)
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+    expect(result.current).toMatchObject({ status: 'succeeded', error: null })
+  })
+
+  it('polls at once on poll during the backoff after a failed poll, starting the backoff again', async () => {
+    const fetchMock = stubFetch(
+      job('running', null),
+      errorResponse(503, 'unavailable', true),
+      errorResponse(503, 'unavailable', true),
+      job('running', { dinners: ['Tacos'] }),
+      job('succeeded', { dinners: ['Tacos'] }),
+    )
+    const { result } = renderJob('j1')
+    await advance(0)
+    await advance(500)
+    await advance(1000)
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+
+    // The next poll was due 2 s later; poll asks now.
+    act(() => result.current.poll())
+    await advance(0)
+    expect(fetchMock).toHaveBeenCalledTimes(4)
+    expect(result.current).toMatchObject({ status: 'running', result: { dinners: ['Tacos'] }, error: null })
+    expect(vi.getTimerCount()).toBe(1)
+    await advance(500)
+    expect(fetchMock).toHaveBeenCalledTimes(5)
+    expect(result.current.status).toBe('succeeded')
+  })
+
   it('stops polling on unmount after a failed poll', async () => {
     const fetchMock = stubFetch(errorResponse(503, 'unavailable', true))
     const { result, unmount } = renderJob('j1')
@@ -125,12 +191,15 @@ describe('useJob', () => {
   })
 
   it('stops polling the old job when the job id changes', async () => {
-    const fetchMock = stubFetch(job('running', null), job('running', null))
+    const fetchMock = stubFetch(
+      job('running', null),
+      jsonResponse(200, { id: 'j2', kind: 'plan.draft', status: 'running', result: null, error: null }),
+    )
     const { result, rerender } = renderJob('j1')
 
     await advance(0)
     rerender({ id: 'j2' })
-    expect(result.current).toEqual({ status: undefined, result: null, error: null })
+    expect(result.current).toMatchObject({ status: undefined, result: null, error: null })
     await advance(0)
     expect(request(fetchMock, 1).path).toBe('/api/v1/jobs/j2')
     expect(vi.getTimerCount()).toBe(1)
@@ -165,6 +234,6 @@ describe('useJob', () => {
     const { result } = renderJob(null)
     await advance(5000)
     expect(fetchMock).not.toHaveBeenCalled()
-    expect(result.current).toEqual({ status: undefined, result: null, error: null })
+    expect(result.current).toMatchObject({ status: undefined, result: null, error: null })
   })
 })

web/src/api/useJob.ts

@@ -1,8 +1,11 @@
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import { useApi } from './ApiContext.tsx'
+import { isRecord } from './errors.ts'
 
 export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed'
 
+const STATUSES: readonly string[] = ['queued', 'running', 'succeeded', 'failed'] satisfies JobStatus[]
+
 // Job is the GET /api/v1/jobs/{id} response. result may be set while the job
 // is running (a partial result); error is set only when it failed.
 export type Job<R> = {
@@ -18,28 +21,56 @@ export type JobState<R> = {
   status: JobStatus | undefined
   // The latest result, partial while the job runs.
   result: R | null
-  // The job's failure, or the latest polling request's own failure (cleared
-  // by the next poll that answers).
+  // The job's failure, the latest polling request's own failure (cleared
+  // by the next poll that answers), or an answer that is not this job.
   error: Error | null
+  // poll asks for the job now, starting the backoff again — also after
+  // polling stopped on an answer that is not this job.
+  poll: () => void
 }
 
 // Polling starts at FIRST_DELAY_MS and doubles up to MAX_DELAY_MS.
 export const FIRST_DELAY_MS = 500
 export const MAX_DELAY_MS = 2000
 
+type JobData<R> = Omit<JobState<R>, 'poll'>
+
 const idle = { status: undefined, result: null, error: null }
 
+// parseJob checks a GET /api/v1/jobs/{id} answer is the kind of job asked
+// for, with a known status. result is passed on unread for the caller to
+// check.
+function parseJob<R>(where: string, kind: string, jobId: string, body: unknown): Job<R> {
+  if (
+    !isRecord(body) ||
+    body.id !== jobId ||
+    body.kind !== kind ||
+    typeof body.status !== 'string' ||
+    !STATUSES.includes(body.status) ||
+    !('result' in body) ||
+    (body.error !== null && typeof body.error !== 'string')
+  ) {
+    throw new Error(`${where}: response is not the ${kind} job ${jobId}`)
+  }
+  return { id: jobId, kind, status: body.status as JobStatus, result: body.result as R | null, error: body.error as string | null }
+}
+
 function isTerminal(status: JobStatus): boolean {
   return status === 'succeeded' || status === 'failed'
 }
 
-// useJob polls GET /api/v1/jobs/{jobId} until the job succeeds or fails,
-// backing off from 500 ms to 2 s. A failed poll is exposed as the error and
-// polling continues. Polling stops only at a terminal status, when jobId
-// changes and on unmount. A null jobId polls nothing.
-export function useJob<R>(jobId: string | null): JobState<R> {
+// useJob polls GET /api/v1/jobs/{jobId}, a job of the given kind, until it
+// succeeds or fails, backing off from 500 ms to 2 s. A failed poll is
+// exposed as the error and polling continues. An answer that is not this
+// job is exposed as the error and stops polling until poll is called.
+// Polling also stops at a terminal status, when jobId changes and on
+// unmount. A null jobId polls nothing.
+export function useJob<R>(kind: string, jobId: string | null): JobState<R> {
   const { apiFetch } = useApi()
-  const [state, setState] = useState<{ jobId: string | null; job: JobState<R> }>({ jobId, job: idle })
+  const [state, setState] = useState<{ jobId: string | null; job: JobData<R> }>({ jobId, job: idle })
+  // Each poll call bumps round, which restarts the polling effect.
+  const [round, setRound] = useState(0)
+  const poll = useCallback(() => setRound((r) => r + 1), [])
 
   useEffect(() => {
     if (jobId === null) return
@@ -47,37 +78,51 @@ export function useJob<R>(jobId: string | null): JobState<R> {
     let timer: ReturnType<typeof setTimeout> | undefined
     let delay = FIRST_DELAY_MS
 
-    function next() {
-      timer = setTimeout(poll, delay)
-      delay = Math.min(delay * 2, MAX_DELAY_MS)
-    }
-
-    async function poll() {
+    async function fetchJob() {
+      const path = `/api/v1/jobs/${encodeURIComponent(jobId!)}`
+      let body: unknown
       try {
-        const job = await apiFetch<Job<R>>(`/api/v1/jobs/${encodeURIComponent(jobId!)}`)
-        if (!active) return
-        const error = job.status === 'failed' ? new Error(job.error ?? `job ${job.id} failed without an error message`) : null
-        setState({ jobId, job: { status: job.status, result: job.result, error } })
-        if (isTerminal(job.status)) return
+        body = await apiFetch<unknown>(path)
       } catch (error) {
         if (!active) return
         // A failed poll is not the job's end: keep the last known status and
         // result, expose the request's error, and poll again.
-        setState((prev) => ({
-          jobId,
-          job: { ...(prev.jobId === jobId ? prev.job : idle), error: error instanceof Error ? error : new Error(String(error)) },
-        }))
+        fail(error instanceof Error ? error : new Error(String(error)))
+        next()
+        return
       }
-      next()
+      if (!active) return
+      let job: Job<R>
+      try {
+        job = parseJob<R>(`GET ${path}`, kind, jobId!, body)
+      } catch (error) {
+        // An answer that is not this job will not become one by asking
+        // again: expose it and stop.
+        fail(error as Error)
+        return
+      }
+      const error = job.status === 'failed' ? new Error(job.error ?? `job ${job.id} failed without an error message`) : null
+      setState({ jobId, job: { status: job.status, result: job.result, error } })
+      if (!isTerminal(job.status)) next()
     }
 
-    void poll()
+    // fail keeps the last known status and result, with error.
+    function fail(error: Error) {
+      setState((prev) => ({ jobId, job: { ...(prev.jobId === jobId ? prev.job : idle), error } }))
+    }
+
+    function next() {
+      timer = setTimeout(fetchJob, delay)
+      delay = Math.min(delay * 2, MAX_DELAY_MS)
+    }
+
+    void fetchJob()
     return () => {
       active = false
       clearTimeout(timer)
     }
-  }, [apiFetch, jobId])
+  }, [apiFetch, kind, jobId, round])
 
   // State left from a previous jobId is not this job's.
-  return state.jobId === jobId ? state.job : idle
+  return { ...(state.jobId === jobId ? state.job : idle), poll }
 }

web/src/dinners/api.ts

@@ -79,7 +79,7 @@ export const REGULARS_KEY = ['dinners', 'regular'] as const
 const REGULARS_LIST_KEY = [...REGULARS_KEY, 'list'] as const
 const REGULARS_MUTATION_KEY = ['dinners', 'regular', 'change'] as const
 
-function oneOf<T extends string>(where: string, field: string, values: readonly T[], value: unknown): T {
+export function oneOf<T extends string>(where: string, field: string, values: readonly T[], value: unknown): T {
   if (typeof value !== 'string' || !(values as readonly string[]).includes(value)) {
     throw new Error(`${where}: ${field} ${JSON.stringify(value)} is not one of ${values.join(', ')}`)
   }
@@ -99,14 +99,15 @@ const PHOTO_URL = /^\/media\/photos\/([^/]+)-400\.jpg$/
 
 // photoId reads the photo id out of a photo_url, which the server always
 // sends as /media/photos/{id}-400.jpg or null.
-function photoId(where: string, value: unknown): string | undefined {
+export function photoId(where: string, value: unknown): string | undefined {
   if (value === null) return undefined
   const match = typeof value === 'string' ? PHOTO_URL.exec(value) : null
   if (!match?.[1]) throw new Error(`${where}: photo_url ${JSON.stringify(value)} is not a stored photo`)
   return decodeURIComponent(match[1])
 }
 
-function parseDinner(where: string, body: unknown): Regular {
+// parseDinner checks a dinner as the dinners API sends it.
+export function parseDinner(where: string, body: unknown): Regular {
   if (!isRecord(body) || typeof body.id !== 'string' || typeof body.name !== 'string') {
     throw new Error(`${where}: response is not a dinner`)
   }
@@ -141,7 +142,7 @@ function parseCandidate(where: string, body: unknown): RecipeCandidate {
   }
 }
 
-function dinnerPath(id: string): string {
+export function dinnerPath(id: string): string {
   return `${DINNERS_PATH}/${encodeURIComponent(id)}`
 }
 

web/src/dinners/names.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import cases from '../../../internal/ai/harness/testdata/dedupe_cases.json'
+import cases from './testdata/dedupe_cases.json'
 import { normalizeName, similarNames } from './names.ts'
 
 // The cases internal/ai/harness's tests run against Normalize and Similar.

web/src/dinners/names.ts

@@ -1,7 +1,7 @@
 // The PWA's copy of the server's dinner-name rules (internal/ai/harness
 // Normalize and Similar), so a screen can tell beforehand that the dinners
 // API would refuse a name as a duplicate. The server still decides.
-// internal/ai/harness/testdata/dedupe_cases.json is run against both.
+// web/src/dinners/testdata/dedupe_cases.json is run against both.
 
 import folds from './letterFolds.json'
 

web/src/discover/DeckCard.tsx

@@ -0,0 +1,75 @@
+import type { DOMAttributes } from 'react'
+import { DIFFICULTIES, type Difficulty } from '../dinners/api.ts'
+import { Photo } from '../ui/Photo.tsx'
+import type { SideQuest } from './api.ts'
+import styles from './DiscoverPage.module.css'
+
+// DECK_DEPTH is the depths the deck shows, top card first.
+export const DECK_DEPTH = [0, 1, 2] as const
+
+export const DIFFICULTY_LABEL: Record<Difficulty, string> = { easy: 'Easy', medium: 'Medium', hard: 'Hard' }
+
+// SwipeHandlers are the pointer handlers that drag the top card.
+export type SwipeHandlers = Pick<
+  DOMAttributes<HTMLElement>,
+  'onPointerDown' | 'onPointerMove' | 'onPointerUp' | 'onPointerCancel' | 'onLostPointerCapture'
+>
+
+export type DeckCardProps = {
+  quest: SideQuest
+  // 0 is the top card; 1 and 2 stack behind it.
+  depth: number
+  // swipe makes the card draggable; only the top card gets it.
+  swipe?: SwipeHandlers
+}
+
+// DeckCard is one Side quest in the deck. Only the top card is read out and
+// reachable; the cards behind it are the stack's edge, kept rendered so they
+// can be promoted. Its "Try it!" and "Pass" stamps stay hidden until a
+// decision or a drag shows them, and its shade until Pass folds it (see
+// motion.ts).
+export function DeckCard({ quest, depth, swipe }: DeckCardProps) {
+  const top = depth === 0
+  const titleId = `side-quest-${quest.id}`
+  return (
+    <article
+      className={`${styles.card} ${styles[`depth${depth}`]}${swipe === undefined ? '' : ` ${styles.draggable}`}`}
+      aria-labelledby={top ? titleId : undefined}
+      aria-hidden={top ? undefined : true}
+      inert={!top}
+      {...swipe}
+    >
+      <Photo id={quest.photo_id} name={quest.name} radius="24px" inset="10px" sizes="400px" className={styles.photo} />
+      <div className={styles.content}>
+        <h2 id={titleId} className={styles.name}>
+          {quest.name}
+        </h2>
+        {quest.difficulty !== null && <DifficultyDots difficulty={quest.difficulty} />}
+        <p className={styles.why}>
+          <strong>Why this?</strong> {quest.reason}
+        </p>
+      </div>
+      <span className={`${styles.stamp} ${styles.tryStamp}`} data-part="try-stamp" aria-hidden="true">
+        Try it!
+      </span>
+      <span className={`${styles.stamp} ${styles.passStamp}`} data-part="pass-stamp" aria-hidden="true">
+        Pass
+      </span>
+      <span className={styles.shade} data-part="shade" />
+    </article>
+  )
+}
+
+function DifficultyDots({ difficulty }: { difficulty: Difficulty }) {
+  const level = DIFFICULTIES.indexOf(difficulty) + 1
+  return (
+    <p className={styles.difficulty}>
+      <span className={styles.dots} aria-hidden="true">
+        {DIFFICULTIES.map((d, i) => (
+          <span key={d} data-filled={i < level} className={i < level ? styles.dotFilled : styles.dot} />
+        ))}
+      </span>
+      {DIFFICULTY_LABEL[difficulty]}
+    </p>
+  )
+}

web/src/discover/DiscoverPage.module.css

@@ -0,0 +1,249 @@
+/* Discover · Side quests (mock 1a). */
+.page {
+  box-sizing: border-box;
+  max-width: 440px;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  padding-top: 8px;
+}
+
+.header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.kicker {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--color-accent-700);
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 30px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+/* The Quest log count pill, in a 44 px tall hit box. */
+.questLogButton {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: transparent;
+  cursor: pointer;
+}
+
+.questLog {
+  flex: none;
+  padding: 7px 12px;
+  border-radius: var(--radius-pill);
+  background: var(--color-accent-2-200);
+  color: var(--color-accent-2-800);
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+}
+
+/* The deck: three cards stacked in the same box, the top one in front. */
+.deck {
+  position: relative;
+  height: 440px;
+  perspective: 1000px;
+}
+
+.card {
+  position: absolute;
+  inset: 0;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--radius-card);
+  overflow: hidden;
+  color: var(--color-text);
+}
+
+.depth0 {
+  z-index: 3;
+  transform: none;
+  background: var(--color-neutral-100);
+  box-shadow: var(--shadow-lg);
+}
+
+/* The top card follows a drag instead of scrolling the page. */
+.draggable {
+  touch-action: none;
+  cursor: grab;
+}
+
+.depth1 {
+  z-index: 2;
+  transform: translateY(8px) scale(0.95);
+  background: var(--color-surface);
+}
+
+.depth2 {
+  z-index: 1;
+  transform: translateY(16px) scale(0.9);
+  background: var(--color-neutral-300);
+}
+
+.photo {
+  flex: none;
+  width: calc(100% - 20px);
+  height: 220px;
+}
+
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 4px 20px 0;
+}
+
+.name {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 24px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+.difficulty {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.dots {
+  display: flex;
+  gap: 3px;
+}
+
+.dot,
+.dotFilled {
+  width: 8px;
+  height: 8px;
+  border-radius: var(--radius-pill);
+  background: var(--color-neutral-300);
+}
+
+.dotFilled {
+  background: var(--color-accent);
+}
+
+/* The "Why this?" box. */
+.why {
+  margin: 0;
+  padding: 12px 14px;
+  border-radius: 18px;
+  background: var(--color-accent-2-100);
+  color: var(--color-accent-2-900);
+  font-family: var(--font-body);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+/* The decision stamps, hidden until a decision shows them. */
+.stamp {
+  position: absolute;
+  top: 26px;
+  padding: 6px 14px;
+  border: 3px solid;
+  border-radius: 14px;
+  font-family: var(--font-heading);
+  font-size: 24px;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.tryStamp {
+  left: 22px;
+  transform: rotate(-12deg);
+  border-color: var(--color-accent-2-700);
+  background: var(--color-accent-2-100);
+  color: var(--color-accent-2-800);
+}
+
+.passStamp {
+  right: 22px;
+  transform: rotate(12deg);
+  border-color: var(--color-neutral-800);
+  background: var(--color-neutral-100);
+  color: var(--color-neutral-900);
+}
+
+/* The shade Pass darkens the card with as it folds. */
+.shade {
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background: var(--color-text);
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* Pass and Try it: IconButtons with their 11 px labels shown. */
+.actions {
+  display: flex;
+  justify-content: center;
+  gap: 28px;
+  margin-top: 4px;
+}
+
+/* Skeleton cards while the deck loads or a batch finds Side quests. */
+.loading {
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+}
+
+.deck > .skeletonCard {
+  position: absolute;
+  inset: 0;
+  height: auto;
+  border-radius: var(--radius-card);
+}
+
+/* A blank card holds a depth a short deck has no card for, as the stack's
+   edge, in that depth's place and colour. */
+.blankCard {
+  position: absolute;
+  inset: 0;
+  border-radius: var(--radius-card);
+}
+
+.skeletonCard.depth0,
+.skeletonCard.depth1,
+.skeletonCard.depth2 {
+  background: var(--color-surface);
+  box-shadow: none;
+}
+
+.finding {
+  margin: 0;
+  text-align: center;
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}

web/src/discover/DiscoverPage.tsx

@@ -0,0 +1,434 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { Heart, X } from 'lucide-react'
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type PointerEvent, type Ref } from 'react'
+import { useJob } from '../api/index.ts'
+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 { Skeleton } from '../ui/Skeleton.tsx'
+import {
+  BATCH_JOB_KIND,
+  DECK_KEY,
+  parseBatchResult,
+  stillPending,
+  useDeciding,
+  useDeck,
+  useDecide,
+  useQuestLog,
+  useStartBatch,
+  type Choice,
+  type QuestLogDinner,
+  type SideQuest,
+} from './api.ts'
+import { DeckCard, DECK_DEPTH, type SwipeHandlers } from './DeckCard.tsx'
+import {
+  bump,
+  fadeOut,
+  follow,
+  isAbort,
+  pass,
+  prefersReducedMotion,
+  promote,
+  snapBack,
+  tryIt,
+  unfollow,
+  type Exit,
+} from './motion.ts'
+import { QuestLogSheet } from './QuestLogSheet.tsx'
+import styles from './DiscoverPage.module.css'
+
+// SWIPE_THRESHOLD is how far, in px, the top card must be dragged left or
+// right for its release to Pass or Try it.
+const SWIPE_THRESHOLD = 110
+
+// A Drag is the pointer dragging the top card: where it went down, and the
+// card's drag transform so far.
+type Drag = { pointerId: number; x: number; y: number; dx: number; transform: string | null }
+
+// isEditable says whether a key press belongs to a field being typed in,
+// which the deck's ← / → keys leave alone.
+function isEditable(target: EventTarget | null): boolean {
+  return (
+    target instanceof HTMLElement &&
+    (target.isContentEditable || target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement)
+  )
+}
+
+// QuestLogPill is the "Quest log · N" pill, which opens the Quest log
+// sheet. ref is the visible pill, which Try it bumps.
+function QuestLogPill({ dinners, ref }: { dinners: QuestLogDinner[]; ref: Ref<HTMLSpanElement> }) {
+  const [open, setOpen] = useState(false)
+  return (
+    <>
+      <button
+        type="button"
+        className={styles.questLogButton}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        onClick={() => setOpen(true)}
+      >
+        <span ref={ref} className={styles.questLog}>Quest log · {dinners.length}</span>
+      </button>
+      <QuestLogSheet open={open} dinners={dinners} onClose={() => setOpen(false)} />
+    </>
+  )
+}
+
+// DiscoverPage is mock 1a: the deck of Side quests to Try it or Pass, one
+// at a time from the top card. A decision from the buttons, the ← / → keys
+// or a swipe of the top card throws it out (motion.ts) and sends the
+// decision once it is gone, taking the card off the deck at once (see
+// useDecide); Retry sends a failed one again while the deck's newest read
+// still has its Side quest pending. Input is locked from the press
+// until the decision settles, which is once the deck and the Quest log have
+// been read again after it, so no decision starts under those reads. The lock is a
+// ref, set before anything starts, so a second press before the next render
+// does nothing, and busy mirrors it to disable the buttons.
+export function DiscoverPage() {
+  const queryClient = useQueryClient()
+  const deck = useDeck()
+  // The deck shown: the deck's newest read, less the Side quests being
+  // decided, which a read landing mid-decision may still have pending.
+  const inFlight = useDeciding()
+  const cards = deck.data?.suggestions.filter((quest) => !inFlight.has(quest.id))
+  const questLog = useQuestLog()
+  const decision = useDecide()
+  const startBatch = useStartBatch()
+  // The job of the batch last known to be finding Side quests, or to have
+  // failed to: the one Get more now started or joined, the replenish a
+  // decision started or joined, or the deck's active or failed batch, which
+  // may have been started elsewhere or before the page opened.
+  const [batchJobId, setBatchJobId] = useState<string | null>(null)
+  const job = useJob<unknown>(BATCH_JOB_KIND, batchJobId)
+  // A read of the deck reporting a new active or failed batch follows its
+  // job from that render on. One reporting neither leaves the last job
+  // followed, so its end stays shown — unless that job is known to have
+  // failed, by its poll or the deck's last read: the deck reports the newest
+  // batch's failure, so a later batch has superseded it, and it goes.
+  const failedJobId = deck.data?.failedBatch?.job_id ?? null
+  const deckJobId = deck.data?.activeBatch?.job_id ?? failedJobId
+  const [seenRead, setSeenRead] = useState({ at: 0, jobId: null as string | null, failedJobId: null as string | null })
+  if (deck.dataUpdatedAt !== seenRead.at) {
+    setSeenRead({ at: deck.dataUpdatedAt, jobId: deckJobId, failedJobId })
+    if (deckJobId !== null && deckJobId !== seenRead.jobId) setBatchJobId(deckJobId)
+    else if (deckJobId === null && batchJobId !== null && (job.status === 'failed' || batchJobId === seenRead.failedJobId)) setBatchJobId(null)
+  }
+
+  const top = cards?.[0]
+  const [busy, setBusy] = useState(false)
+  // The deck's failed batch is not finding anything, even before its job's
+  // first poll says why it failed.
+  const jobRunning = batchJobId !== null && batchJobId !== failedJobId && job.status !== 'succeeded' && job.status !== 'failed'
+  const finding = startBatch.isPending || jobRunning
+  const { mutate: mutateStartBatch } = startBatch
+  const getMore = useCallback(() => mutateStartBatch(undefined, { onSuccess: (b) => setBatchJobId(b.job_id) }), [mutateStartBatch])
+
+  // The batch's result as far as it has gone, or why it cannot be read.
+  const batch = useMemo(() => {
+    if (job.result === null) return { stored: 0, error: null }
+    try {
+      return { stored: parseBatchResult(`GET /api/v1/jobs/${batchJobId}`, job.result).suggestion_ids.length, error: null }
+    } catch (error) {
+      return { stored: 0, error: error as Error }
+    }
+  }, [job.result, batchJobId])
+  // The job's failure, the latest poll's failure, an answer that is not the
+  // batch's job, or an unreadable result.
+  const batchError = job.error ?? batch.error
+
+  const deckRef = useRef<HTMLDivElement>(null)
+  const passRef = useRef<HTMLButtonElement>(null)
+  const tryRef = useRef<HTMLButtonElement>(null)
+  const questLogRef = useRef<HTMLSpanElement>(null)
+  // The top card's exit until its decision settles, and the Side quest the
+  // last decision sent was for, until the deck moves past it.
+  const exit = useRef<Exit | null>(null)
+  const leaving = useRef<string | null>(null)
+  const drag = useRef<Drag | null>(null)
+  // The top card's snap-back while it may still run; a new drag or a
+  // decision stops it so it does not fight the card's new motion.
+  const springing = useRef<Animation | null>(null)
+  const stopSpring = useCallback(() => {
+    springing.current?.cancel()
+    springing.current = null
+  }, [])
+
+  const { mutate: mutateDecision } = decision
+  const deciding = useRef(false)
+  const lock = useCallback(() => {
+    if (deciding.current) return false
+    deciding.current = true
+    setBusy(true)
+    return true
+  }, [])
+  // send records a decision. A failed one stops the card's exit, so a card
+  // useDecide put back on the deck is at rest; a saved one that started or
+  // joined a replenish batch follows its job.
+  const send = useCallback(
+    (variables: { quest: SideQuest; choice: Choice }) => {
+      leaving.current = variables.quest.id
+      mutateDecision(variables, {
+        onSuccess: (replenishJobId) => {
+          if (replenishJobId !== null) setBatchJobId(replenishJobId)
+        },
+        onError: () => {
+          exit.current?.cancel()
+          leaving.current = null
+        },
+        onSettled: () => {
+          exit.current = null
+          deciding.current = false
+          setBusy(false)
+        },
+      })
+    },
+    [mutateDecision],
+  )
+  const submit = useCallback(
+    (variables: { quest: SideQuest; choice: Choice }) => {
+      if (lock()) send(variables)
+    },
+    [lock, send],
+  )
+  // decide bumps the button, throws the top card out — or, motion reduced,
+  // fades it — then sends the decision; Try it bumps the Quest log pill too.
+  // A swipe's decision comes from the card's drag transform: it is thrown
+  // from there without a bump or wiggle. A button or key decision ends a
+  // drag in progress, putting the card back first.
+  const decide = useCallback(
+    (choice: Choice, from?: string) => {
+      if (top === undefined || !lock()) return
+      stopSpring()
+      const card = deckRef.current!.querySelector('article')!
+      if (from === undefined && drag.current !== null) {
+        drag.current = null
+        unfollow(card)
+      }
+      const reduced = prefersReducedMotion()
+      let run: Exit
+      if (reduced) {
+        run = fadeOut(card)
+      } else if (from === undefined) {
+        bump((choice === 'try' ? tryRef : passRef).current!)
+        run = choice === 'try' ? tryIt(card) : pass(card)
+      } else {
+        run = choice === 'try' ? tryIt(card, from) : pass(card, from)
+      }
+      if (from !== undefined) {
+        // Putting a swiped card back puts it back at rest.
+        const thrown = run
+        run = {
+          finished: thrown.finished,
+          cancel: () => {
+            thrown.cancel()
+            unfollow(card)
+          },
+        }
+      }
+      exit.current = run
+      run.finished.then(
+        () => {
+          // The Quest log pill is missing while the Quest log fails to load.
+          if (choice === 'try' && !reduced && questLogRef.current !== null) bump(questLogRef.current)
+          send({ quest: top, choice })
+        },
+        (error: unknown) => {
+          if (!isAbort(error)) throw error
+        },
+      )
+    },
+    [top, lock, send, stopSpring],
+  )
+
+  // swipe drags the top card: it follows the pointer, captured from the
+  // press, until the release decides past the threshold or springs it back
+  // short of it. The release decides from where the pointer let go, which
+  // may differ from its last move. A cancel, or losing the capture before
+  // the release, springs it back from its last move. One pointer drags at
+  // a time: a press while a drag is in progress is ignored, as is input
+  // while busy, and a drag held into a busy spell (a Retry) is put back on
+  // release.
+  const swipe = useMemo<SwipeHandlers>(() => {
+    function track(card: HTMLElement, current: Drag, event: PointerEvent<HTMLElement>) {
+      current.dx = event.clientX - current.x
+      current.transform = follow(card, current.dx, event.clientY - current.y)
+    }
+    function release(event: PointerEvent<HTMLElement>, decides: boolean) {
+      const card = event.currentTarget
+      const current = drag.current
+      if (current === null || current.pointerId !== event.pointerId) return
+      drag.current = null
+      const moved = current.transform !== null || event.clientX !== current.x || event.clientY !== current.y
+      if (decides && moved && !deciding.current) track(card, current, event)
+      if (current.transform === null) return
+      if (deciding.current) unfollow(card)
+      else if (decides && current.dx > SWIPE_THRESHOLD) decide('try', current.transform)
+      else if (decides && current.dx < -SWIPE_THRESHOLD) decide('pass', current.transform)
+      else if (prefersReducedMotion()) unfollow(card)
+      else springing.current = snapBack(card, current.transform)
+    }
+    return {
+      onPointerDown: (event) => {
+        if (drag.current !== null || deciding.current || !event.isPrimary || event.button !== 0) return
+        stopSpring()
+        event.currentTarget.setPointerCapture(event.pointerId)
+        drag.current = { pointerId: event.pointerId, x: event.clientX, y: event.clientY, dx: 0, transform: null }
+      },
+      onPointerMove: (event) => {
+        const current = drag.current
+        if (current === null || current.pointerId !== event.pointerId || deciding.current) return
+        track(event.currentTarget, current, event)
+      },
+      onPointerUp: (event) => release(event, true),
+      onPointerCancel: (event) => release(event, false),
+      // After a release the drag is already over, so this only ends a drag
+      // whose capture was lost before it.
+      onLostPointerCapture: (event) => release(event, false),
+    }
+  }, [decide, stopSpring])
+
+  // Leaving the page stops an exit before its decision is sent.
+  useEffect(() => () => exit.current?.cancel(), [])
+
+  const topId = top?.id
+  // A drag belongs to the card it started on, which a new top card ends.
+  useLayoutEffect(() => {
+    drag.current = null
+  }, [topId])
+
+  // Once the deck moves past the card a decision was sent for, the cards
+  // behind it move up a depth.
+  useLayoutEffect(() => {
+    if (leaving.current === null || leaving.current === topId) return
+    leaving.current = null
+    if (topId === undefined || prefersReducedMotion()) return
+    promote([...deckRef.current!.querySelectorAll<HTMLElement>(':scope > article')])
+  }, [topId])
+
+  useEffect(() => {
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return
+      if (isEditable(event.target)) return
+      // A modal over the page (the Quest log sheet or its confirmation) makes
+      // the deck inert: its keys are the modal's, not the deck's.
+      if (deckRef.current === null || deckRef.current.closest('[inert]') !== null) return
+      if (event.key === 'ArrowLeft') decide('pass')
+      else if (event.key === 'ArrowRight') decide('try')
+      else return
+      event.preventDefault()
+    }
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [decide])
+
+  // The batch stores its Side quests as it goes, so the deck is read again
+  // whenever it reports more, and once it ends. A read already out may be a
+  // decision's, which must not be cut short: the batch's read waits for it,
+  // then goes out after it, as it may predate what the batch reported.
+  const { stored } = batch
+  useEffect(() => {
+    if (job.status === undefined) return
+    const after = queryClient.isFetching({ queryKey: DECK_KEY }) > 0
+    void queryClient
+      .invalidateQueries({ queryKey: DECK_KEY }, { cancelRefetch: false })
+      .then(() => (after ? queryClient.invalidateQueries({ queryKey: DECK_KEY }, { cancelRefetch: false }) : undefined))
+  }, [queryClient, job.status, stored])
+
+  // A failed decision can be retried only while the deck's newest read
+  // still has its Side quest pending: anything else decided it already.
+  const pending = decision.isError ? stillPending(deck, decision.variables.quest.id) : undefined
+  const retryable = pending !== undefined && pending !== null
+
+  // What went wrong asking for or finding more Side quests, shown whatever
+  // the deck has: a replenish can fail while cards remain. While Get more now
+  // is asking again, the last batch's failure is not the news.
+  const batchFailure = startBatch.isPending ? null : startBatch.isError ? (
+    <ErrorBanner onRetry={getMore}>Couldn't ask for more side quests. {startBatch.error.message}</ErrorBanner>
+  ) : batchError === null ? null : jobRunning ? (
+    <ErrorBanner onRetry={job.poll}>Couldn't check on new side quests. {batchError.message}</ErrorBanner>
+  ) : (
+    <ErrorBanner onRetry={getMore}>Couldn't find new side quests. {batchError.message}</ErrorBanner>
+  )
+
+  let body
+  if (deck.isError) {
+    body = <ErrorBanner onRetry={() => void deck.refetch()}>Couldn't load your side quests. {deck.error.message}</ErrorBanner>
+  } else if (deck.isPending || (cards!.length === 0 && (finding || decision.isPending))) {
+    // An empty deck is not caught up while a batch finds more Side quests,
+    // or while the last decision may yet start one or come back refused.
+    body = (
+      <section aria-busy="true" aria-label="Side quests loading" className={styles.loading}>
+        <div className={styles.deck}>
+          {DECK_DEPTH.map((depth) => (
+            <Skeleton key={depth} data-testid="skeleton-card" className={`${styles.skeletonCard} ${styles[`depth${depth}`]}`} />
+          ))}
+        </div>
+        {finding && <p className={styles.finding}>Finding new side quests…</p>}
+      </section>
+    )
+  } else if (top === undefined) {
+    body = (
+      <EmptyState title="All caught up" action={{ label: 'Get more now', onClick: getMore }}>
+        New side quests arrive Sunday.
+      </EmptyState>
+    )
+  } else {
+    const shown = cards!.slice(0, DECK_DEPTH.length)
+    body = (
+      <>
+        {/* The deck keeps all three depths: a short deck fills those it has
+            no card for with skeleton cards while a batch finds more Side
+            quests, and with blank cards, the stack's edge, while none is
+            coming. */}
+        <div ref={deckRef} className={styles.deck}>
+          {shown.map((quest, depth) => (
+            <DeckCard key={quest.id} quest={quest} depth={depth} swipe={depth === 0 ? swipe : undefined} />
+          ))}
+          {DECK_DEPTH.slice(shown.length).map((depth) =>
+            finding ? (
+              <Skeleton key={depth} data-testid="skeleton-card" className={`${styles.skeletonCard} ${styles[`depth${depth}`]}`} />
+            ) : (
+              <div key={depth} data-testid="blank-card" aria-hidden="true" className={`${styles.blankCard} ${styles[`depth${depth}`]}`} />
+            ),
+          )}
+        </div>
+        <div className={styles.actions}>
+          <IconButton ref={passRef} label="Pass" size={62} tone="neutral" showLabel disabled={busy} onClick={() => decide('pass')}>
+            <Icon icon={X} size="nav" />
+          </IconButton>
+          <IconButton ref={tryRef} label="Try it" size={62} tone="teal" showLabel disabled={busy} onClick={() => decide('try')}>
+            <Icon icon={Heart} size="nav" />
+          </IconButton>
+        </div>
+        {finding && <p className={styles.finding}>Finding new side quests…</p>}
+      </>
+    )
+  }
+
+  return (
+    <div className={styles.page}>
+      <header className={styles.header}>
+        <div>
+          <p className={styles.kicker}>Discover</p>
+          <h1 className={styles.title}>Side quests</h1>
+        </div>
+        {questLog.isSuccess && <QuestLogPill ref={questLogRef} dinners={questLog.data} />}
+      </header>
+      {questLog.isError && (
+        <ErrorBanner onRetry={() => void questLog.refetch()}>Couldn't load the Quest log. {questLog.error.message}</ErrorBanner>
+      )}
+      {body}
+      {batchFailure}
+      {/* A failed decision is shown whatever the deck has come to since. */}
+      {decision.isError &&
+        (retryable ? (
+          <ErrorBanner onRetry={() => submit(decision.variables)}>Couldn't save that choice. {decision.error.message}</ErrorBanner>
+        ) : pending === undefined ? (
+          <ErrorBanner>Couldn't save that choice. {decision.error.message}</ErrorBanner>
+        ) : (
+          <ErrorBanner>That side quest has been decided already. {decision.error.message}</ErrorBanner>
+        ))}
+    </div>
+  )
+}

web/src/discover/QuestLogSheet.module.css

@@ -0,0 +1,38 @@
+/* The Quest log sheet (mock 1a's "Quest log · N" pill opens it). */
+.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);
+}
+
+/* The 48 px washed photo; Photo applies the washed filter. */
+.photo {
+  width: 48px;
+  height: 48px;
+}
+
+.empty {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--color-neutral-700);
+}

web/src/discover/QuestLogSheet.tsx

@@ -0,0 +1,147 @@
+import { Trash2 } from 'lucide-react'
+import { useEffect, useId, useRef, useState } from 'react'
+import { useNavigate } from 'react-router'
+import { Confirm } from '../settings/LeaveGuard.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import { ListRow } from '../ui/ListRow.tsx'
+import { Photo } from '../ui/Photo.tsx'
+import { Sheet } from '../ui/Sheet.tsx'
+import { useRemoveFromQuestLog, type QuestLogDinner } from './api.ts'
+import { DIFFICULTY_LABEL } from './DeckCard.tsx'
+import styles from './QuestLogSheet.module.css'
+
+export type QuestLogSheetProps = {
+  open: boolean
+  // The Quest log, as useQuestLog reads it.
+  dinners: QuestLogDinner[]
+  onClose: () => void
+}
+
+// details is a Quest-log dinner's "difficulty · minutes" line, or null when
+// neither is known.
+export function details(dinner: QuestLogDinner): string | null {
+  const parts = [
+    dinner.difficulty !== null && DIFFICULTY_LABEL[dinner.difficulty],
+    dinner.minutes_total !== null && `${dinner.minutes_total} min`,
+  ].filter((part): part is string => typeof part === 'string')
+  return parts.length === 0 ? null : parts.join(' · ')
+}
+
+// QuestLogSheet is the Quest log as a bottom sheet: each dinner with its
+// washed photo, name, difficulty and minutes. A row opens the dinner; its
+// remove button, once confirmed, archives the dinner.
+export function QuestLogSheet({ open, dinners, onClose }: QuestLogSheetProps) {
+  const titleId = useId()
+  const navigate = useNavigate()
+  const remove = useRemoveFromQuestLog()
+  // The dinner whose removal is being confirmed.
+  const [removing, setRemoving] = useState<QuestLogDinner | null>(null)
+  // The dinner just removed and its place in the list, until focus has
+  // moved on from it.
+  const removed = useRef<{ id: string; index: number } | null>(null)
+  const removeButtons = useRef(new Map<string, HTMLButtonElement>())
+  const sheetRef = useRef<HTMLDivElement>(null)
+  // Whether a removal has been sent and not yet settled. The ref is set as
+  // Remove is activated, so a dismissal or a second Remove that arrives before
+  // the next render is already refused; the state renders it.
+  const sending = useRef(false)
+  const [sendingShown, setSendingShown] = useState(false)
+
+  // Once a removal's confirmation has closed and the dinner has left the list,
+  // focus goes to the remove button of the dinner now in its place, or of the
+  // one before it when it was the last, or to the Quest log sheet itself when
+  // none is left. Otherwise it would be left on the removed dinner's button,
+  // which the confirmation hands it back to, and which is then gone.
+  useEffect(() => {
+    const done = removed.current
+    if (removing !== null || done === null || dinners.some((d) => d.id === done.id)) return
+    removed.current = null
+    const next = dinners[Math.min(done.index, dinners.length - 1)]
+    if (next) removeButtons.current.get(next.id)!.focus()
+    else sheetRef.current!.closest<HTMLElement>('[role="dialog"]')!.focus()
+  }, [removing, dinners])
+
+  function setSending(value: boolean) {
+    sending.current = value
+    setSendingShown(value)
+  }
+
+  function cancelRemove() {
+    if (sending.current) return
+    remove.reset()
+    setRemoving(null)
+  }
+
+  function confirmRemove() {
+    if (sending.current) return
+    setSending(true)
+    remove.mutate(removing!, {
+      onSuccess: (_data, dinner) => {
+        removed.current = { id: dinner.id, index: dinners.findIndex((d) => d.id === dinner.id) }
+        setRemoving(null)
+      },
+      onSettled: () => setSending(false),
+    })
+  }
+
+  return (
+    <>
+      <Sheet open={open} onClose={onClose} aria-labelledby={titleId}>
+        <div ref={sheetRef} className={styles.sheet}>
+          <h2 id={titleId} className={styles.title}>
+            Quest log
+          </h2>
+          {dinners.length === 0 ? (
+            <p className={styles.empty}>Your Quest log is empty — swipe right on a side quest to add one.</p>
+          ) : (
+            <ul aria-label="Quest log" className={styles.rows}>
+              {dinners.map((dinner) => (
+                <li key={dinner.id}>
+                  <ListRow
+                    leading={
+                      // The row's name already says what the photo shows.
+                      <span aria-hidden="true">
+                        <Photo id={dinner.photo_id} name={dinner.name} radius="var(--radius-md)" sizes="48px" className={styles.photo} />
+                      </span>
+                    }
+                    title={dinner.name}
+                    meta={details(dinner)}
+                    onClick={() => navigate(`/dinner/${encodeURIComponent(dinner.id)}`)}
+                    trailing={
+                      <IconButton
+                        ref={(button) => {
+                          if (button) removeButtons.current.set(dinner.id, button)
+                          else removeButtons.current.delete(dinner.id)
+                        }}
+                        label={`Remove ${dinner.name}`}
+                        tone="neutral"
+                        onClick={() => setRemoving(dinner)}
+                      >
+                        <Icon icon={Trash2} />
+                      </IconButton>
+                    }
+                  />
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      </Sheet>
+      <Confirm
+        open={removing !== null}
+        title={`Remove ${removing?.name ?? ''}?`}
+        confirmLabel={sendingShown ? 'Removing…' : 'Remove'}
+        cancelLabel="Keep it"
+        busy={sendingShown}
+        // Once the removal is sent, it stands: the confirmation stays until it settles.
+        dismissible={!sendingShown}
+        error={remove.isError ? `Couldn't remove it. ${remove.error.message}` : null}
+        onCancel={cancelRemove}
+        onConfirm={confirmRemove}
+      >
+        It leaves your Quest log for good.
+      </Confirm>
+    </>
+  )
+}

web/src/discover/api.ts

@@ -0,0 +1,281 @@
+import { useMutation, useMutationState, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useApi } from '../api/index.ts'
+import { isRecord } from '../api/errors.ts'
+import { DIFFICULTIES, DINNERS_PATH, dinnerPath, oneOf, parseDinner, photoId, type Difficulty, type Regular } from '../dinners/api.ts'
+
+export const SUGGESTIONS_PATH = '/api/v1/suggestions'
+export const DECK_PATH = `${SUGGESTIONS_PATH}/deck`
+export const BATCHES_PATH = `${SUGGESTIONS_PATH}/batches`
+export const QUEST_LOG_PATH = `${DINNERS_PATH}?status=quest_log`
+
+// DECK_KEY is the deck's query; QUEST_LOG_KEY the Quest log's;
+// DECIDE_KEY the decisions'.
+export const DECK_KEY = ['suggestions', 'deck'] as const
+export const QUEST_LOG_KEY = ['dinners', 'quest_log'] as const
+const DECIDE_KEY = ['suggestions', 'decide'] as const
+
+// SideQuest is a pending suggestion as the deck shows it. dinner_id is the
+// dinner Try it moves to the Quest log; photo_id is the stored photo's id,
+// from photo_url; reason is the "Why this?".
+export type SideQuest = {
+  id: string
+  dinner_id: string
+  name: string
+  photo_id: string | undefined
+  difficulty: Difficulty | null
+  reason: string
+}
+
+// Choice is the household's decision on a Side quest: Try it or Pass.
+export type Choice = 'try' | 'pass'
+
+// Batch is a POST /api/v1/suggestions/batches answer, or the deck's active
+// or failed batch: the batch and the job running it, which GET
+// /api/v1/jobs/{id} reports on.
+export type Batch = { batch_id: string; job_id: string }
+
+// Deck is the deck as GET /api/v1/suggestions/deck reads it: the pending
+// Side quests, oldest first; the batch pending or running, if any; and the
+// newest batch when it failed, which a later batch supersedes. At most one
+// of the two batches is set.
+export type Deck = { suggestions: SideQuest[]; activeBatch: Batch | null; failedBatch: Batch | null }
+
+function isBatch(body: unknown): body is Batch {
+  return isRecord(body) && typeof body.batch_id === 'string' && typeof body.job_id === 'string'
+}
+
+// BATCH_JOB_KIND is the kind of the job running a suggestion batch.
+export const BATCH_JOB_KIND = 'suggestion_batch'
+
+// BatchResult is the suggestion batch job's result, published as it goes.
+export type BatchResult = { batch_id: string; stage: string; suggestion_ids: string[]; dropped: number }
+
+// QuestLogDinner is a dinner in the Quest log, as the Quest log sheet lists
+// it: photo, name, difficulty and minutes, with the method a swap carries
+// onto the plan.
+export type QuestLogDinner = Pick<Regular, 'id' | 'name' | 'photo_id' | 'difficulty' | 'method' | 'minutes_total'>
+
+// DECISION_STATUS is the status a suggestion has once each choice is saved.
+const DECISION_STATUS: Record<Choice, string> = { try: 'accepted', pass: 'declined' }
+
+// parseBatchResult checks a suggestion batch job's result, which useJob
+// passes on unread.
+export function parseBatchResult(where: string, body: unknown): BatchResult {
+  if (
+    !isRecord(body) ||
+    typeof body.batch_id !== 'string' ||
+    typeof body.stage !== 'string' ||
+    !Array.isArray(body.suggestion_ids) ||
+    !body.suggestion_ids.every((id) => typeof id === 'string') ||
+    typeof body.dropped !== 'number'
+  ) {
+    throw new Error(`${where}: result is not a suggestion batch`)
+  }
+  return { batch_id: body.batch_id, stage: body.stage, suggestion_ids: body.suggestion_ids as string[], dropped: body.dropped }
+}
+
+function parseSideQuest(where: string, body: unknown): SideQuest {
+  if (
+    !isRecord(body) ||
+    typeof body.id !== 'string' ||
+    typeof body.dinner_id !== 'string' ||
+    typeof body.name !== 'string' ||
+    typeof body.reason !== 'string'
+  ) {
+    throw new Error(`${where}: response is not a suggestion`)
+  }
+  return {
+    id: body.id,
+    dinner_id: body.dinner_id,
+    name: body.name,
+    photo_id: photoId(where, body.photo_url),
+    difficulty: body.difficulty === null ? null : oneOf(where, 'difficulty', DIFFICULTIES, body.difficulty),
+    reason: body.reason,
+  }
+}
+
+// useDeck is the pending Side quests, oldest first, the batch pending or
+// running and the newest batch when it failed (GET
+// /api/v1/suggestions/deck).
+export function useDeck() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: DECK_KEY,
+    queryFn: async (): Promise<Deck> => {
+      const where = `GET ${DECK_PATH}`
+      const body = await apiFetch<unknown>(DECK_PATH)
+      if (!isRecord(body) || !Array.isArray(body.suggestions)) throw new Error(`${where}: response has no suggestions list`)
+      if (body.active_batch !== null && !isBatch(body.active_batch)) throw new Error(`${where}: response has no active_batch`)
+      if (body.failed_batch !== null && !isBatch(body.failed_batch)) throw new Error(`${where}: response has no failed_batch`)
+      return {
+        suggestions: body.suggestions.map((suggestion) => parseSideQuest(where, suggestion)),
+        activeBatch: body.active_batch === null ? null : { batch_id: body.active_batch.batch_id, job_id: body.active_batch.job_id },
+        failedBatch: body.failed_batch === null ? null : { batch_id: body.failed_batch.batch_id, job_id: body.failed_batch.job_id },
+      }
+    },
+  })
+}
+
+// useQuestLog is the dinners in the Quest log, in the server's order (GET
+// /api/v1/dinners?status=quest_log). The server leaves out a dinner already
+// on the plan for the current week or a later one: it is scheduled.
+export function useQuestLog() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: QUEST_LOG_KEY,
+    queryFn: async (): Promise<QuestLogDinner[]> => {
+      const where = `GET ${QUEST_LOG_PATH}`
+      const body = await apiFetch<unknown>(QUEST_LOG_PATH)
+      if (!isRecord(body) || !Array.isArray(body.dinners)) throw new Error(`${where}: response has no dinners list`)
+      return body.dinners.map((dinner) => {
+        const { id, name, photo_id, difficulty, method, minutes_total } = parseDinner(where, dinner)
+        return { id, name, photo_id, difficulty, method, minutes_total }
+      })
+    },
+  })
+}
+
+// useRemoveFromQuestLog archives a Quest-log dinner (DELETE
+// /api/v1/dinners/{id}). Once the server has archived it, it leaves the
+// Quest log, and the Quest log is read again.
+export function useRemoveFromQuestLog() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (dinner: QuestLogDinner) => {
+      await apiFetch<unknown>(dinnerPath(dinner.id), { method: 'DELETE' })
+    },
+    onSuccess: async (_data, dinner) => {
+      queryClient.setQueryData<QuestLogDinner[]>(QUEST_LOG_KEY, (dinners) => dinners?.filter((d) => d.id !== dinner.id))
+      await queryClient.invalidateQueries({ queryKey: QUEST_LOG_KEY })
+    },
+  })
+}
+
+// useStartBatch asks for more Side quests now (POST
+// /api/v1/suggestions/batches). The server answers with the batch already
+// running when there is one.
+export function useStartBatch() {
+  const { apiFetch } = useApi()
+  return useMutation({
+    mutationFn: async (): Promise<Batch> => {
+      const body = await apiFetch<unknown>(BATCHES_PATH, { method: 'POST' })
+      if (!isBatch(body)) throw new Error(`POST ${BATCHES_PATH}: response is not a batch`)
+      return { batch_id: body.batch_id, job_id: body.job_id }
+    },
+  })
+}
+
+// stillPending says whether the deck's newest read has the Side quest id
+// pending, after a failed decision on it: the Side quest when it does, null
+// when it does not, and undefined when that read failed, which says neither.
+// deck is the deck query's state, from the cache or useDeck.
+export function stillPending(deck: { status: string; data: Deck | undefined } | undefined, id: string): SideQuest | null | undefined {
+  if (deck?.status !== 'success') return undefined
+  return deck.data!.suggestions.find((q) => q.id === id) ?? null
+}
+
+// useDeciding is the ids of the Side quests whose decisions are pending:
+// sent and not yet settled. The deck shown leaves them out, whatever a read
+// of the deck has said meanwhile.
+export function useDeciding(): Set<string> {
+  const ids = useMutationState<string>({
+    filters: { mutationKey: DECIDE_KEY, status: 'pending' },
+    select: (mutation) => (mutation.state.variables as { quest: SideQuest }).quest.id,
+  })
+  return new Set(ids)
+}
+
+// useDecide records Try it (POST /api/v1/suggestions/{id}/accept) or Pass
+// (POST /api/v1/suggestions/{id}/decline) on the Side quest the household
+// decided on, whether or not a read of the deck has since taken it away.
+// The answer must be that suggestion, decided that way; the mutation's data
+// is the id of the replenish job the decision started or joined, or null.
+//
+// The decision is applied at once: the Side quest leaves the deck shown
+// while it is pending (see useDeciding) and, on Try it, its dinner joins the
+// Quest log unless it is there already. Nothing else is worked out here:
+// the server is the record of both. However the decision ends, saved or
+// failed, the deck and the Quest log are read again, and the decision is
+// pending until those reads land, so the next one (which DiscoverPage locks
+// out until then) cannot start under them. A read under way when the
+// decision ends is replaced by the read made after it, and DiscoverPage's
+// batch reads wait for that one rather than replace it.
+// A failed decision waits for the deck read it makes itself. Whether its
+// Side quest is still pending is then the deck query's to say, from its
+// newest successful read: once the reads have landed, a Side quest the deck
+// still has goes back on top of it.
+export function useDecide() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+
+  // send POSTs the decision and checks the answer.
+  async function send(id: string, choice: Choice): Promise<string | null> {
+    const action = choice === 'try' ? 'accept' : 'decline'
+    const path = `${SUGGESTIONS_PATH}/${encodeURIComponent(id)}/${action}`
+    const body = await apiFetch<unknown>(path, { method: 'POST' })
+    if (
+      !isRecord(body) ||
+      !isRecord(body.suggestion) ||
+      body.suggestion.id !== id ||
+      body.suggestion.status !== DECISION_STATUS[choice]
+    ) {
+      throw new Error(`POST ${path}: response is not the ${DECISION_STATUS[choice]} suggestion`)
+    }
+    if (body.replenish_job_id !== null && typeof body.replenish_job_id !== 'string') {
+      throw new Error(`POST ${path}: response has no replenish_job_id`)
+    }
+    return body.replenish_job_id
+  }
+
+  return useMutation<string | null, Error, { quest: SideQuest; choice: Choice }>({
+    mutationKey: DECIDE_KEY,
+    mutationFn: async ({ quest, choice }) => {
+      try {
+        return await send(quest.id, choice)
+      } catch (error) {
+        // The deck is read again as the decision's own fetch, replacing any
+        // read already out. A failed read is the deck query's error, shown
+        // with the deck; the decision's own error is the one thrown.
+        await queryClient
+          .getQueryCache()
+          .build<Deck>(queryClient, { queryKey: DECK_KEY })
+          .fetch(undefined, { cancelRefetch: true })
+          .catch(() => undefined)
+        throw error
+      }
+    },
+    onMutate: ({ quest, choice }) => {
+      if (choice !== 'try') return
+      // A stale deck can offer a Side quest whose dinner the Quest log has.
+      queryClient.setQueryData<QuestLogDinner[]>(QUEST_LOG_KEY, (dinners) =>
+        dinners === undefined || dinners.some((d) => d.id === quest.dinner_id)
+          ? dinners
+          : // The deck does not say the method or minutes; the Quest log
+            // read after the decision does.
+            dinners.concat({
+              id: quest.dinner_id,
+              name: quest.name,
+              photo_id: quest.photo_id,
+              difficulty: quest.difficulty,
+              method: null,
+              minutes_total: null,
+            }),
+      )
+    },
+    onSettled: async (_replenishJobId, error, { quest }) => {
+      if (error === null) {
+        await Promise.all([queryClient.invalidateQueries({ queryKey: DECK_KEY }), queryClient.invalidateQueries({ queryKey: QUEST_LOG_KEY })])
+        return
+      }
+      // A failed decision has read the deck already; any read since is newer.
+      await queryClient.invalidateQueries({ queryKey: QUEST_LOG_KEY })
+      const pending = stillPending(queryClient.getQueryState<Deck>(DECK_KEY), quest.id)
+      if (pending === null || pending === undefined) return
+      queryClient.setQueryData<Deck>(DECK_KEY, (deck) => ({
+        ...deck!,
+        suggestions: [pending, ...deck!.suggestions.filter((q) => q.id !== pending.id)],
+      }))
+    },
+  })
+}

web/src/discover/motion.test.ts

@@ -0,0 +1,221 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { stubAnimate, type FakeAnimation } from '../test/animate.ts'
+import { bump, dragTransform, fadeOut, follow, isAbort, pass, promote, snapBack, tryIt, unfollow } from './motion.ts'
+
+let animations: FakeAnimation[]
+
+beforeEach(() => {
+  animations = stubAnimate({ autoFinish: false })
+})
+
+afterEach(() => {
+  Reflect.deleteProperty(Element.prototype, 'animate')
+})
+
+// card builds a deck card with the parts DeckCard marks.
+function card() {
+  const article = document.createElement('article')
+  article.innerHTML = '<span data-part="try-stamp"></span><span data-part="pass-stamp"></span><span data-part="shade"></span>'
+  return {
+    article,
+    stamp: article.querySelector<HTMLElement>('[data-part="try-stamp"]')!,
+    passStamp: article.querySelector<HTMLElement>('[data-part="pass-stamp"]')!,
+    shade: article.querySelector('[data-part="shade"]')!,
+  }
+}
+
+// settled says whether a promise has settled after pending callbacks run.
+async function settled(promise: Promise<unknown>) {
+  let done = false
+  void promise.then(
+    () => (done = true),
+    () => (done = true),
+  )
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  return done
+}
+
+const FLY_OFF = { transform: 'translate(150%,-60px) rotate(28deg)', opacity: 0 }
+
+describe('motion', () => {
+  it('bumps: scale 1 → .88 → 1.06 → 1, 300 ms ease-out', () => {
+    const button = document.createElement('button')
+    bump(button)
+    expect(animations).toHaveLength(1)
+    expect(animations[0]!.target).toBe(button)
+    expect(animations[0]!.keyframes).toEqual([
+      { transform: 'scale(1)' },
+      { transform: 'scale(.88)' },
+      { transform: 'scale(1.06)' },
+      { transform: 'scale(1)' },
+    ])
+    expect(animations[0]!.options).toEqual({ duration: 300, easing: 'ease-out' })
+  })
+
+  it('Try it pops the stamp and wiggles, then throws the card right', async () => {
+    const { article, stamp } = card()
+    const exit = tryIt(article)
+
+    const [pop, wiggle] = animations
+    expect(pop!.target).toBe(stamp)
+    expect(pop!.keyframes).toEqual([
+      { opacity: 0, transform: 'rotate(-12deg) scale(1.5)' },
+      { opacity: 1, transform: 'rotate(-12deg) scale(1)' },
+    ])
+    expect(pop!.options).toEqual({ duration: 220, easing: 'cubic-bezier(.34,1.4,.64,1)', fill: 'forwards' })
+    expect(wiggle!.target).toBe(article)
+    expect(wiggle!.keyframes).toEqual(['0deg', '-4deg', '4deg', '-3deg', '2deg', '0deg'].map((a) => ({ transform: `rotate(${a})` })))
+    expect(wiggle!.options).toEqual({ duration: 420, easing: 'ease-in-out' })
+    expect(animations).toHaveLength(2)
+
+    // The throw waits for the wiggle.
+    pop!.finish()
+    wiggle!.finish()
+    await expect.poll(() => animations.length).toBe(3)
+    const fly = animations[2]!
+    expect(fly.target).toBe(article)
+    expect(fly.keyframes).toEqual([
+      { transform: 'translate(0px,0px) rotate(0deg)' },
+      { transform: 'translate(-14px,4px) rotate(-3deg)', offset: 0.18 },
+      FLY_OFF,
+    ])
+    expect(fly.options).toEqual({ duration: 480, easing: 'cubic-bezier(.55,0,.8,.4)', fill: 'forwards' })
+
+    expect(await settled(exit.finished)).toBe(false)
+    fly.finish()
+    await expect(exit.finished).resolves.toBeUndefined()
+  })
+
+  it('Try it from a dragged transform skips the wiggle and throws in 340 ms', async () => {
+    const { article } = card()
+    const exit = tryIt(article, 'translate(120px,9px) rotate(6.7deg)')
+    await expect.poll(() => animations.length).toBe(2)
+    const fly = animations[1]!
+    expect(fly.target).toBe(article)
+    expect(fly.keyframes).toEqual([{ transform: 'translate(120px,9px) rotate(6.7deg)' }, FLY_OFF])
+    expect(fly.options).toEqual({ duration: 340, easing: 'cubic-bezier(.55,0,.8,.4)', fill: 'forwards' })
+    fly.finish()
+    await expect(exit.finished).resolves.toBeUndefined()
+  })
+
+  it('Pass folds the card over its left edge under a darkening shade', async () => {
+    const { article, shade } = card()
+    const exit = pass(article)
+
+    const [darken, fold] = animations
+    expect(animations).toHaveLength(2)
+    expect(darken!.target).toBe(shade)
+    expect(darken!.keyframes).toEqual([{ opacity: 0 }, { opacity: 0.4, offset: 0.45 }, { opacity: 0.55 }])
+    expect(darken!.options).toEqual({ duration: 720, fill: 'forwards' })
+    expect(fold!.target).toBe(article)
+    expect(fold!.keyframes).toEqual([
+      { transformOrigin: '0% 50%', transform: 'translate(0px,0px) rotate(0deg) rotateY(0deg)', easing: 'cubic-bezier(.45,0,.85,.55)' },
+      {
+        transformOrigin: '0% 50%',
+        transform: 'translate(0px,0px) rotate(0deg) rotateY(-80deg)',
+        offset: 0.45,
+        easing: 'cubic-bezier(.4,0,.9,.6)',
+      },
+      { transformOrigin: '0% 50%', transform: 'translate(-45%,560px) rotate(-35deg) rotateY(-90deg)', opacity: 0 },
+    ])
+    expect(fold!.options).toEqual({ duration: 720, fill: 'forwards' })
+
+    darken!.finish()
+    expect(await settled(exit.finished)).toBe(false)
+    fold!.finish()
+    await expect(exit.finished).resolves.toBeUndefined()
+  })
+
+  it('Pass from a dragged transform folds from there', () => {
+    const { article } = card()
+    pass(article, 'translate(-130px,6px) rotate(-7deg)')
+    const fold = animations[1]!
+    expect(fold.keyframes.map((k) => k.transform)).toEqual([
+      'translate(-130px,6px) rotate(-7deg) rotateY(0deg)',
+      'translate(-130px,6px) rotate(-7deg) rotateY(-80deg)',
+      'translate(-45%,560px) rotate(-35deg) rotateY(-90deg)',
+    ])
+  })
+
+  it('fades out in 200 ms with reduced motion', async () => {
+    const { article } = card()
+    const exit = fadeOut(article)
+    expect(animations).toHaveLength(1)
+    expect(animations[0]!.target).toBe(article)
+    expect(animations[0]!.keyframes).toEqual([{ opacity: 1 }, { opacity: 0 }])
+    expect(animations[0]!.options).toEqual({ duration: 200, fill: 'forwards' })
+    animations[0]!.finish()
+    await expect(exit.finished).resolves.toBeUndefined()
+  })
+
+  it('promotes the top two cards from the depth behind, 300 ms', () => {
+    const cards = [card().article, card().article, card().article]
+    promote(cards)
+    expect(animations.map((a) => a.target)).toEqual([cards[0], cards[1]])
+    expect(animations.map((a) => a.keyframes)).toEqual([
+      [{ transform: 'translateY(8px) scale(0.95)' }, { transform: 'translateY(0px) scale(1)' }],
+      [{ transform: 'translateY(16px) scale(0.9)' }, { transform: 'translateY(8px) scale(0.95)' }],
+    ])
+    for (const a of animations) expect(a.options).toEqual({ duration: 300, easing: 'cubic-bezier(.2,.8,.2,1)' })
+  })
+
+  it('cancel stops an exit and never starts its next step', async () => {
+    const { article } = card()
+    const exit = tryIt(article)
+    animations[1]!.finish()
+    exit.cancel()
+    const error: unknown = await exit.finished.catch((e: unknown) => e)
+    expect(isAbort(error)).toBe(true)
+    expect(animations).toHaveLength(2)
+    expect(animations.map((a) => a.playState)).toEqual(['idle', 'idle'])
+  })
+
+  it('drags: translate(dx, dy·0.3) rotate(dx/18 deg)', () => {
+    expect(dragTransform(90, 20)).toBe('translate(90px,6px) rotate(5deg)')
+    expect(dragTransform(-36, -10)).toBe('translate(-36px,-3px) rotate(-2deg)')
+  })
+
+  it.each([
+    [50, '0.5', '0'],
+    [-50, '0', '0.5'],
+    [160, '1', '0'],
+    [-160, '0', '1'],
+    [0, '0', '0'],
+  ])('follows a drag of %i px with the stamps at Try it! %s, Pass %s', (dx, tryOpacity, passOpacity) => {
+    const { article, stamp, passStamp } = card()
+    expect(follow(article, dx, 0)).toBe(dragTransform(dx, 0))
+    expect(article.style.transform).toBe(dragTransform(dx, 0))
+    expect(stamp.style.opacity).toBe(tryOpacity)
+    expect(passStamp.style.opacity).toBe(passOpacity)
+    expect(animations).toEqual([])
+  })
+
+  it('unfollows at once, back to the stylesheet', () => {
+    const { article, stamp, passStamp } = card()
+    follow(article, -80, 12)
+    unfollow(article)
+    expect(article.getAttribute('style')).toBe('')
+    expect(stamp.getAttribute('style')).toBe('')
+    expect(passStamp.getAttribute('style')).toBe('')
+    expect(animations).toEqual([])
+  })
+
+  it('snaps back from the drag transform to rest, 420 ms spring, and hides the stamps', () => {
+    const { article, stamp, passStamp } = card()
+    const from = follow(article, 70, 30)
+    snapBack(article, from)
+    expect(article.style.transform).toBe('')
+    expect(stamp.style.opacity).toBe('')
+    expect(passStamp.style.opacity).toBe('')
+    expect(animations).toHaveLength(1)
+    expect(animations[0]!.target).toBe(article)
+    expect(animations[0]!.keyframes).toEqual([{ transform: 'translate(70px,9px) rotate(3.888888888888889deg)' }, { transform: 'translate(0px,0px) rotate(0deg)' }])
+    expect(animations[0]!.options).toEqual({ duration: 420, easing: 'cubic-bezier(.34,1.4,.64,1)' })
+  })
+
+  it('fails fast on a card without its parts', () => {
+    expect(() => tryIt(document.createElement('article'))).toThrow('deck card has no try-stamp')
+    expect(() => pass(document.createElement('article'))).toThrow('deck card has no shade')
+    expect(() => follow(document.createElement('article'), 10, 0)).toThrow('deck card has no try-stamp')
+  })
+})

web/src/discover/motion.ts

@@ -0,0 +1,178 @@
+// The deck's motion, from the handoff's Motion §2 (Try it), §3 (Pass),
+// §4 (swipe), §5 (deck advance) and §6 (reduced motion), with the Web
+// Animations API. The exits take the card's starting transform so the swipe
+// gesture can throw a dragged card from where it was let go.
+
+const SPRING = 'cubic-bezier(.34,1.4,.64,1)'
+const THROW = 'cubic-bezier(.55,0,.8,.4)'
+const SOFT = 'cubic-bezier(.2,.8,.2,1)'
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)'
+
+// REST is the top card's transform when nothing moves it, written as the
+// translate + rotate a drag gives it so the exits interpolate function by
+// function.
+export const REST = 'translate(0px,0px) rotate(0deg)'
+
+// DEPTH_TRANSFORM is each deck depth's transform, as the stylesheet places it.
+export const DEPTH_TRANSFORM = ['translateY(0px) scale(1)', 'translateY(8px) scale(0.95)', 'translateY(16px) scale(0.9)'] as const
+
+const FLY_OFF = 'translate(150%,-60px) rotate(28deg)'
+const PASS_ORIGIN = '0% 50%'
+
+// An Exit is a card leaving the deck: finished resolves once it is off
+// screen and rejects with an AbortError if cancel stops it first. cancel
+// also undoes a finished exit, putting the card back.
+export type Exit = {
+  finished: Promise<void>
+  cancel: () => void
+}
+
+export function prefersReducedMotion(): boolean {
+  return window.matchMedia(REDUCED_MOTION_QUERY).matches
+}
+
+// isAbort says whether an exit's finished rejected because it was canceled.
+export function isAbort(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'AbortError'
+}
+
+// bump is the press bump of the Try it and Pass buttons and the Quest log pill.
+export function bump(element: Element): Animation {
+  return element.animate(
+    [{ transform: 'scale(1)' }, { transform: 'scale(.88)' }, { transform: 'scale(1.06)' }, { transform: 'scale(1)' }],
+    { duration: 300, easing: 'ease-out' },
+  )
+}
+
+// tryIt pops the "Try it!" stamp and throws the card off to the right. From
+// rest it wiggles first and winds up before the throw; from a dragged
+// transform it skips both and throws faster.
+export function tryIt(card: HTMLElement, from?: string): Exit {
+  const exit = recorder()
+  exit.run(part(card, 'try-stamp'), [
+    { opacity: 0, transform: 'rotate(-12deg) scale(1.5)' },
+    { opacity: 1, transform: 'rotate(-12deg) scale(1)' },
+  ], { duration: 220, easing: SPRING, fill: 'forwards' })
+  const wiggled =
+    from === undefined
+      ? exit.run(card, [
+          { transform: 'rotate(0deg)' },
+          { transform: 'rotate(-4deg)' },
+          { transform: 'rotate(4deg)' },
+          { transform: 'rotate(-3deg)' },
+          { transform: 'rotate(2deg)' },
+          { transform: 'rotate(0deg)' },
+        ], { duration: 420, easing: 'ease-in-out' }).finished
+      : Promise.resolve()
+  const finished = wiggled.then(() =>
+    from === undefined
+      ? exit.run(card, [
+          { transform: REST },
+          { transform: 'translate(-14px,4px) rotate(-3deg)', offset: 0.18 },
+          { transform: FLY_OFF, opacity: 0 },
+        ], { duration: 480, easing: THROW, fill: 'forwards' }).finished
+      : exit.run(card, [{ transform: from }, { transform: FLY_OFF, opacity: 0 }], { duration: 340, easing: THROW, fill: 'forwards' })
+          .finished,
+  )
+  return exit.done(finished)
+}
+
+// pass folds the card over its left edge like a page, darkening it, then
+// drops it off to the left. A dragged card folds from where it was let go.
+export function pass(card: HTMLElement, from: string = REST): Exit {
+  const exit = recorder()
+  exit.run(part(card, 'shade'), [{ opacity: 0 }, { opacity: 0.4, offset: 0.45 }, { opacity: 0.55 }], {
+    duration: 720,
+    fill: 'forwards',
+  })
+  const finished = exit.run(card, [
+    { transformOrigin: PASS_ORIGIN, transform: `${from} rotateY(0deg)`, easing: 'cubic-bezier(.45,0,.85,.55)' },
+    { transformOrigin: PASS_ORIGIN, transform: `${from} rotateY(-80deg)`, offset: 0.45, easing: 'cubic-bezier(.4,0,.9,.6)' },
+    { transformOrigin: PASS_ORIGIN, transform: 'translate(-45%,560px) rotate(-35deg) rotateY(-90deg)', opacity: 0 },
+  ], { duration: 720, fill: 'forwards' }).finished
+  return exit.done(finished)
+}
+
+// dragTransform is the top card's transform dragged dx, dy from where the
+// pointer went down.
+export function dragTransform(dx: number, dy: number): string {
+  return `translate(${dx}px,${dy * 0.3}px) rotate(${dx / 18}deg)`
+}
+
+// follow moves a dragged card to its drag transform and shows each stamp as
+// far as the drag has gone toward its side, fully at 100 px. It returns the
+// transform, for the exit or snap-back the release starts.
+export function follow(card: HTMLElement, dx: number, dy: number): string {
+  const transform = dragTransform(dx, dy)
+  card.style.transform = transform
+  part(card, 'try-stamp').style.opacity = String(clamp(dx / 100))
+  part(card, 'pass-stamp').style.opacity = String(clamp(-dx / 100))
+  return transform
+}
+
+// unfollow puts a dragged card and its stamps back where the stylesheet
+// places them, at once.
+export function unfollow(card: HTMLElement) {
+  card.style.removeProperty('transform')
+  part(card, 'try-stamp').style.removeProperty('opacity')
+  part(card, 'pass-stamp').style.removeProperty('opacity')
+}
+
+// snapBack springs a card let go short of a decision back to rest from its
+// drag transform, and hides its stamps.
+export function snapBack(card: HTMLElement, from: string): Animation {
+  unfollow(card)
+  return card.animate([{ transform: from }, { transform: REST }], { duration: 420, easing: SPRING })
+}
+
+// fadeOut is both exits under prefers-reduced-motion: reduce.
+export function fadeOut(card: HTMLElement): Exit {
+  const exit = recorder()
+  return exit.done(exit.run(card, [{ opacity: 1 }, { opacity: 0 }], { duration: 200, fill: 'forwards' }).finished)
+}
+
+// promote moves the cards left after an exit, top first, from the depth
+// behind to their own.
+export function promote(cards: HTMLElement[]): Animation[] {
+  return cards.slice(0, DEPTH_TRANSFORM.length - 1).map((card, depth) =>
+    card.animate([{ transform: DEPTH_TRANSFORM[depth + 1] }, { transform: DEPTH_TRANSFORM[depth] }], {
+      duration: 300,
+      easing: SOFT,
+    }),
+  )
+}
+
+function clamp(value: number): number {
+  return Math.min(1, Math.max(0, value))
+}
+
+// part is the card's element marked data-part="name", which DeckCard renders.
+function part(card: HTMLElement, name: string): HTMLElement {
+  const element = card.querySelector<HTMLElement>(`[data-part="${name}"]`)
+  if (element === null) throw new Error(`deck card has no ${name}`)
+  return element
+}
+
+// recorder keeps every animation an exit starts, so cancel can stop them all.
+// A step that would start after cancel aborts instead.
+function recorder() {
+  const animations: Animation[] = []
+  let canceled = false
+  return {
+    run(element: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions): Animation {
+      if (canceled) throw new DOMException('The exit was canceled.', 'AbortError')
+      const animation = element.animate(keyframes, options)
+      animations.push(animation)
+      return animation
+    },
+    done(finished: Promise<unknown>): Exit {
+      return {
+        finished: finished.then(() => undefined),
+        cancel: () => {
+          canceled = true
+          animations.forEach((animation) => animation.cancel())
+        },
+      }
+    },
+  }
+}

web/src/onboarding/NotificationsStep.test.tsx

@@ -180,10 +180,22 @@ describe('onboarding step 3', () => {
     expect(requestPermission).not.toHaveBeenCalled()
   })
 
-  it('"Turn on notifications" finishes onboarding and goes Home while notifications are unavailable', async () => {
+  it('"Turn on notifications" says plainly that nothing was turned on while notifications are unavailable', async () => {
     const server = await renderApp()
     fireEvent.click(turnOn())
 
+    expect(await screen.findByRole('status')).toHaveTextContent(
+      "Notifications aren't on yet: MealQuest can't send them until the notification feature ships, so nothing was turned on.",
+    )
+    // Not a silent success: onboarding is not finished behind the household's back.
+    expect(server.held).toHaveLength(0)
+    expect(screen.getByRole('heading', { level: 1, name: 'Stay in the loop' })).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Turn on notifications' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Maybe later' })).not.toBeInTheDocument()
+
+    const finish = screen.getByRole('button', { name: 'Finish setting up' })
+    expectMinHitArea(finish)
+    fireEvent.click(finish)
     await vi.waitFor(() => expect(server.held).toHaveLength(1))
     expect(server.held[0]!.body).toEqual({ onboarding_completed: true })
     completed(server.held[0]!)
@@ -193,6 +205,19 @@ describe('onboarding step 3', () => {
     expect(requestPermission).not.toHaveBeenCalled()
   })
 
+  it('"Turn on notifications" says the browser blocked them when denied, then finishes on request', async () => {
+    const server = await renderStep(() => Promise.resolve('denied'))
+    fireEvent.click(turnOn())
+
+    expect(await screen.findByRole('status')).toHaveTextContent("Notifications aren't on: this browser blocked them.")
+    expect(server.held).toHaveLength(0)
+
+    fireEvent.click(screen.getByRole('button', { name: 'Finish setting up' }))
+    await vi.waitFor(() => expect(server.held).toHaveLength(1))
+    completed(server.held[0]!)
+    expect(await screen.findByRole('heading', { level: 1, name: 'Home' })).toBeInTheDocument()
+  })
+
   it('"Turn on notifications" asks the injected enableNotifications first, then finishes', async () => {
     let answer: (result: 'enabled') => void = () => {}
     const enable = vi.fn<EnableNotifications>(

web/src/onboarding/NotificationsStep.tsx

@@ -14,11 +14,21 @@ export type NotificationsResult = 'enabled' | 'denied' | 'unavailable'
 export type EnableNotifications = () => Promise<NotificationsResult>
 
 // TODO(Feature 19): Web Push. Until it is wired, notifications cannot be
-// turned on, and nothing asks the browser for permission.
+// turned on, and nothing asks the browser for permission. This placeholder
+// is the interim state: "Turn on notifications" answers 'unavailable', and
+// the step tells the household plainly that nothing was turned on.
 export function notificationsUnavailable(): Promise<NotificationsResult> {
   return Promise.resolve('unavailable')
 }
 
+// notOnReasons says why notifications are not on after asking, for each
+// result other than 'enabled'.
+const notOnReasons: Record<Exclude<NotificationsResult, 'enabled'>, string> = {
+  unavailable:
+    "Notifications aren't on yet: MealQuest can't send them until the notification feature ships, so nothing was turned on. You can finish setting up now.",
+  denied: "Notifications aren't on: this browser blocked them. You can allow them in the browser's settings later.",
+}
+
 const topics: { icon: LucideIcon; name: string; meaning: string }[] = [
   {
     icon: CalendarDays,
@@ -49,16 +59,19 @@ export type NotificationsStepProps = {
 }
 
 // NotificationsStep is onboarding step 3: what MealQuest notifies about, the
-// iOS install hint, and finishing onboarding. Either button records that
-// onboarding is finished and goes Home. When the server refuses because the
-// household has fewer than three Regulars, the reason shows with a way back
-// to step 2 to add them.
+// iOS install hint, and finishing onboarding. "Maybe later", and "Turn on
+// notifications" once they are enabled, record that onboarding is finished
+// and go Home. When they are not enabled, the step says so and offers only
+// "Finish setting up". When the server refuses because the household has
+// fewer than three Regulars, the reason shows with a way back to step 2 to
+// add them.
 export function NotificationsStep({ enableNotifications = notificationsUnavailable }: NotificationsStepProps) {
   const navigate = useNavigate()
   const complete = useCompleteOnboarding()
   const [enabling, setEnabling] = useState(false)
   const [problem, setProblem] = useState<string | null>(null)
   const [fewRegulars, setFewRegulars] = useState(false)
+  const [notOn, setNotOn] = useState<string | null>(null)
   const busy = enabling || complete.isPending
 
   async function finish() {
@@ -80,14 +93,19 @@ export function NotificationsStep({ enableNotifications = notificationsUnavailab
   async function turnOn() {
     clearProblem()
     setEnabling(true)
+    let result: NotificationsResult
     try {
-      await enableNotifications()
+      result = await enableNotifications()
     } catch (error) {
       setProblem(`Could not turn on notifications: ${(error as Error).message}`)
       return
     } finally {
       setEnabling(false)
     }
+    if (result !== 'enabled') {
+      setNotOn(notOnReasons[result])
+      return
+    }
     await finish()
   }
 
@@ -101,14 +119,22 @@ export function NotificationsStep({ enableNotifications = notificationsUnavailab
       step={3}
       title="Stay in the loop"
       action={
-        <div className={styles.actions}>
-          <Button className={styles.action} disabled={busy} onClick={() => void turnOn()}>
-            Turn on notifications
-          </Button>
-          <Button variant="outline" className={styles.action} disabled={busy} onClick={later}>
-            Maybe later
-          </Button>
-        </div>
+        notOn ? (
+          <div className={styles.actions}>
+            <Button className={styles.action} disabled={busy} onClick={later}>
+              Finish setting up
+            </Button>
+          </div>
+        ) : (
+          <div className={styles.actions}>
+            <Button className={styles.action} disabled={busy} onClick={() => void turnOn()}>
+              Turn on notifications
+            </Button>
+            <Button variant="outline" className={styles.action} disabled={busy} onClick={later}>
+              Maybe later
+            </Button>
+          </div>
+        )
       }
     >
       <p className={styles.helper}>MealQuest can let the household know when there&apos;s something to look at:</p>
@@ -128,6 +154,11 @@ export function NotificationsStep({ enableNotifications = notificationsUnavailab
       <div className={styles.hint}>
         <InstallHint />
       </div>
+      {notOn && (
+        <p role="status" className={styles.notOn}>
+          {notOn}
+        </p>
+      )}
       {problem && (
         <p role="alert" className={styles.problem}>
           {problem}

web/src/onboarding/Onboarding.module.css

@@ -229,6 +229,18 @@
   color: var(--color-accent-700);
 }
 
+/* Step 3: why notifications are not on after asking for them. */
+.notOn {
+  margin: var(--space-4) 0 0;
+  padding: var(--space-4);
+  border-radius: var(--radius-lg);
+  background: var(--color-surface);
+  font-family: var(--font-body);
+  font-size: 15px;
+  line-height: 1.4;
+  color: var(--color-text);
+}
+
 /* Step 3: back to step 2 when the server wants more Regulars. */
 .recover {
   margin-top: var(--space-3);

web/src/onboarding/OnboardingGate.tsx

@@ -19,7 +19,8 @@ function inOnboarding(pathname: string): boolean {
 // The service worker never caches the settings, so offline on the saved
 // pages (see AuthBootstrap) they cannot be read: the saved pages open as they
 // are, since onboarding needs the server anyway, and the settings are read
-// again when the browser is back online.
+// again when the browser is back online. The read runs even while the
+// browser reports offline, so that case fails fast instead of waiting.
 export function OnboardingGate() {
   const api = useApi()
   const { pathname } = useLocation()

web/src/plan/PlanPage.module.css

@@ -0,0 +1,589 @@
+/* Plan · Draft board (mock 1f) and plan manager (mocks 2c, 2d). */
+.page {
+  box-sizing: border-box;
+}
+
+.board {
+  box-sizing: border-box;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+.mobilePage {
+  max-width: 440px;
+  padding-top: 8px;
+}
+
+/* The grid fills the screen below the header: the main area's 32 px top and
+   bottom padding (AppShell) is taken back off the viewport height. */
+.tabletPage .board {
+  min-height: calc(100dvh - 64px);
+}
+
+/* Desktop: the board beside the 290 px right panel, which runs the full
+   height of the screen to its right edge over the main area's padding. */
+.desktopPage {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 290px;
+  min-height: 100dvh;
+  margin: -32px -36px -32px 0;
+}
+
+.desktopPage .board {
+  padding: 32px 36px 32px 0;
+}
+
+.header {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.heading {
+  min-width: 0;
+}
+
+.kicker {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--color-accent-700);
+}
+
+.titleRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 26px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+.weekNav {
+  flex: none;
+  display: flex;
+  gap: 8px;
+}
+
+/* The assistant: a 32 px grape "Q" avatar beside its note. */
+.assistant {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+}
+
+.avatar {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border-radius: var(--radius-pill);
+  background: var(--color-accent);
+  color: var(--on-accent);
+  font-family: var(--font-heading);
+  font-size: 16px;
+  line-height: 1;
+}
+
+.bubble {
+  margin: 0;
+  padding: 12px 14px;
+  border-radius: 4px 18px 18px 18px;
+  background: var(--color-surface);
+  font-family: var(--font-body);
+  font-size: 14px;
+  line-height: 1.45;
+}
+
+/* Two columns of 86 px day tiles; the 8th cell is "+ Rebuild week". */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.tile {
+  box-sizing: border-box;
+  display: flex;
+  min-height: 86px;
+  border-radius: 22px;
+  background: var(--color-surface);
+  color: var(--color-text);
+}
+
+/* The whole tile is the button that opens the swap sheet. */
+.tileButton {
+  box-sizing: border-box;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  align-items: stretch;
+  gap: 6px;
+  padding: 12px;
+  border: 0;
+  border-radius: inherit;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+/* A Quest-log pick. */
+.newTile {
+  background: var(--color-accent-2-300);
+}
+
+.dayKicker {
+  display: block;
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--color-neutral-700);
+}
+
+.newTile .dayKicker {
+  color: var(--color-accent-2-900);
+}
+
+.dinner {
+  display: block;
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 15px;
+  font-weight: 400;
+  line-height: 1.15;
+  overflow-wrap: anywhere;
+}
+
+.startBy {
+  display: block;
+  margin: 4px 0 0;
+  font-family: var(--font-body);
+  font-size: 11px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.newTile .startBy {
+  color: var(--color-accent-2-900);
+}
+
+/* The day being swapped, while the swap sheet is open: the page background
+   ringed in grape, its name muted. */
+.swapping {
+  background: var(--color-bg);
+  box-shadow: inset 0 0 0 2px var(--color-accent);
+}
+
+.swapping .dayKicker {
+  color: var(--color-accent-700);
+}
+
+.swapping .dinner,
+.swapping .startBy {
+  color: var(--color-neutral-600);
+}
+
+.rebuildCell {
+  display: flex;
+}
+
+.rebuild {
+  box-sizing: border-box;
+  flex: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  min-height: 86px;
+  padding: 12px;
+  border: 2px dashed var(--color-neutral-400);
+  border-radius: 22px;
+  background: transparent;
+  color: var(--color-neutral-700);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.rebuild:hover:not(:disabled) {
+  background: var(--color-neutral-100);
+}
+
+.rebuild:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.loading {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.skeletonTile {
+  height: 86px;
+  border-radius: 22px;
+}
+
+.drafting {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  text-align: center;
+  color: var(--color-neutral-700);
+}
+
+/* An action with nothing behind it yet (Push to Calendar until Feature 16,
+   the shopping list until Feature 17): it keeps focus, so hovering, tapping
+   or focusing it shows the tooltip. */
+.unavailable {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+}
+
+.pushButton {
+  min-height: 50px;
+}
+
+.unavailable [aria-disabled='true'] {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+/* Unavailable, it neither darkens nor presses. */
+.unavailable .primary[aria-disabled='true']:hover,
+.unavailable .primary[aria-disabled='true']:active {
+  background: var(--color-accent);
+  transform: none;
+}
+
+.unavailable .outline[aria-disabled='true']:hover,
+.unavailable .outline[aria-disabled='true']:active {
+  background: transparent;
+  transform: none;
+}
+
+.hint {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  left: 50%;
+  transform: translateX(-50%);
+  width: max-content;
+  max-width: 100%;
+  padding: 8px 12px;
+  border-radius: var(--radius-md);
+  background: var(--color-text);
+  color: var(--color-bg);
+  font-family: var(--font-body);
+  font-size: 13px;
+  line-height: 1.4;
+  text-align: center;
+  box-shadow: var(--shadow-md);
+  visibility: hidden;
+  pointer-events: none;
+}
+
+/* In the plan manager's header the tooltip opens below, at the action's
+   right edge. */
+.below .hint {
+  top: calc(100% + 8px);
+  bottom: auto;
+  left: auto;
+  right: 0;
+  transform: none;
+  width: 240px;
+  max-width: none;
+  z-index: 1;
+}
+
+.unavailable:hover .hint,
+.unavailable [aria-disabled='true']:focus + .hint {
+  visibility: visible;
+}
+
+/* The plan manager's header: kicker and title beside the week buttons, over
+   the sync status and the actions. */
+.wideHeader {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.titleBar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 14px;
+}
+
+.wideTitle {
+  margin: 4px 0 0;
+  font-family: var(--font-heading);
+  font-size: 40px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+.tabletPage .wideTitle {
+  font-size: 36px;
+}
+
+.wideHeader .kicker {
+  font-size: 12px;
+}
+
+.wideHeader .weekNav {
+  align-items: center;
+  gap: 12px;
+}
+
+.thisWeek {
+  min-height: 44px;
+  padding: 10px 16px;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+  color: var(--color-text);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.thisWeek:hover {
+  background: var(--color-neutral-100);
+}
+
+.actionBar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+}
+
+/* The status keeps to one line; the actions wrap under it when the row is
+   too narrow for both. */
+.status {
+  flex: 1 0 auto;
+  white-space: nowrap;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.synced {
+  color: var(--color-accent-2-800);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.action {
+  min-height: 44px;
+  padding: 0 18px;
+  white-space: nowrap;
+}
+
+/* The week: seven columns, each a day label over its card. A column is
+   never narrower than 112 px, which holds a dinner's words whole and the
+   tag beside the swap icon; where seven of those do not fit (tablet's
+   narrow end, desktop beside the panel) the week scrolls sideways. Its 8 px
+   padding, taken back by the margin, keeps the swap icons' hit boxes and
+   focus rings inside the scroll area. */
+.week {
+  flex: 1;
+  display: grid;
+  grid-template-columns: repeat(7, minmax(112px, 1fr));
+  gap: 12px;
+  margin: -8px;
+  padding: 8px;
+  overflow-x: auto;
+  list-style: none;
+}
+
+.column {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.dayLabel {
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+  margin: 0;
+  padding: 0 4px;
+}
+
+.dayName {
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.dayNumber {
+  font-family: var(--font-heading);
+  font-size: 22px;
+  color: var(--color-text);
+}
+
+.card {
+  position: relative;
+  box-sizing: border-box;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 9px;
+  padding: 12px;
+  border-radius: 26px;
+  background: var(--color-surface);
+  color: var(--color-text);
+}
+
+.tablet .card {
+  gap: 8px;
+  padding: 10px;
+  border-radius: 24px;
+}
+
+/* A Side quest's card. */
+.sideQuestCard {
+  background: var(--color-accent-2-200);
+}
+
+.cardPhoto {
+  width: 100%;
+  height: 110px;
+}
+
+.tablet .cardPhoto {
+  height: 96px;
+}
+
+.cardName {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 17px;
+  line-height: 1.15;
+  overflow-wrap: break-word;
+}
+
+.tablet .cardName {
+  font-size: 16px;
+}
+
+.cardMinutes,
+.cardStartBy {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  color: var(--color-neutral-800);
+}
+
+.cardStartBy {
+  font-weight: 700;
+}
+
+.sideQuestCard .cardMinutes,
+.sideQuestCard .cardStartBy {
+  color: var(--color-accent-2-900);
+}
+
+.cardFooter {
+  margin-top: auto;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+/* The day a dragged dinner drops on: a dashed 2.5 px grape border on
+   grape-100 over the card, saying which dinner it replaces. */
+.dropTarget {
+  position: absolute;
+  inset: 0;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: 4px;
+  padding: 12px;
+  border: 2.5px dashed var(--color-accent);
+  border-radius: inherit;
+  background: var(--color-accent-100);
+  text-align: center;
+}
+
+.dropTitle {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 16px;
+  color: var(--color-accent-700);
+}
+
+.dropReplaces {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+  overflow-wrap: break-word;
+}
+
+/* The swap icon sits bare on the card, beside the tag: its 44 px hit box
+   keeps the 16 px footprint of its icon, reaching over the card's padding
+   and the tag. */
+.cardFooter .swapButton {
+  margin: -14px;
+}
+
+.cardFooter .cardTag {
+  margin-right: auto;
+  padding: 3px 8px;
+}
+
+.swapButton > span {
+  background: transparent;
+  color: var(--color-neutral-700);
+}
+
+.skeletonCard {
+  height: 300px;
+  border-radius: 26px;
+}

web/src/plan/PlanPage.tsx

@@ -0,0 +1,599 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { CalendarDays, Check, ChevronLeft, ChevronRight, Plus, RefreshCw, ShoppingCart } from 'lucide-react'
+import { useEffect, useId, useMemo, useState, type ReactNode } from 'react'
+import { useJob } from '../api/index.ts'
+import { QUEST_LOG_KEY } from '../discover/api.ts'
+import { Confirm } from '../settings/LeaveGuard.tsx'
+import { methodLabels } from '../settings/RegularsSettingsPage.tsx'
+import { formatClockTime, useHouseholdSettings } from '../settings/api.ts'
+import { useBreakpoint, type Breakpoint } from '../shell/useBreakpoint.ts'
+import { Button, type ButtonVariant } from '../ui/Button.tsx'
+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 { Tag } from '../ui/Tag.tsx'
+import {
+  DRAFT_JOB_KIND,
+  parseDraftResult,
+  planKey,
+  usePlan,
+  useStartDraft,
+  useSwapDay,
+  type DraftResult,
+  type Plan,
+  type PlanDay,
+  type PlanDinner,
+  type PlanStatus,
+  type Swap,
+} from './api.ts'
+import { DragAnnouncer, DROP_DATE, DropBoard, PlanDragProvider, useDropTarget } from './drag.tsx'
+import { PlanPanel, QuestLogStrip } from './PlanPanel.tsx'
+import { SwapSheet } from './SwapSheet.tsx'
+import {
+  addDays,
+  dayOfMonth,
+  defaultWeek,
+  localNow,
+  weekdayKicker,
+  weekdayName,
+  weekLabel,
+  weekStart as weekOf,
+} from './week.ts'
+import styles from './PlanPage.module.css'
+
+// statusTags is the tag beside the week's title for each plan status.
+const statusTags: Record<PlanStatus, { label: string; tone: 'grape' | 'teal' }> = {
+  draft: { label: 'Draft', tone: 'grape' },
+  synced: { label: 'Synced', tone: 'teal' },
+  changed: { label: 'Changes not pushed', tone: 'grape' },
+}
+
+// draftFailures says why a draft_week job failed, by its failure code. Any
+// other code is shown as it is.
+const draftFailures: Record<string, string> = {
+  not_enough_dinners: 'There are fewer than seven Regulars and Quest-log dinners to draft from.',
+  ai_failed: "The AI assistant couldn't draft it.",
+  confirm_required: 'The plan was pushed to Calendar while it was drafting.',
+  plan_changed: 'The plan was edited while it was drafting.',
+  pool_changed: 'A dinner it picked was archived, tried or planned for another week while it was drafting.',
+  internal_error: 'Something went wrong on the server.',
+}
+
+// PUSH_HINT is why Push to Calendar is unavailable.
+// TODO(Feature 16): connect Push to Calendar once Google Calendar is.
+const PUSH_HINT = 'Push to Calendar arrives once Google Calendar can be connected.'
+
+// SHOPPING_HINT is why the shopping list is unavailable.
+// TODO(Feature 17): open the Supply run, with its count, once it is built.
+const SHOPPING_HINT = 'The shopping list arrives once the Supply run is built.'
+
+// syncStatuses is the plan manager's line on whether the plan is on Calendar.
+const syncStatuses: Record<PlanStatus, string> = {
+  draft: 'Not pushed to Google Calendar yet',
+  synced: 'Synced to Google Calendar',
+  changed: 'Changes not pushed to Google Calendar',
+}
+
+// duration is minutes as the plan manager's cards say it: "45 min", "6 hr",
+// "1 hr 30 min", with no-break spaces so a narrow card wraps the line
+// between the method and the duration, never inside the duration.
+export function duration(minutes: number): string {
+  const hours = Math.floor(minutes / 60)
+  const rest = minutes % 60
+  if (hours === 0) return `${rest}\u00a0min`
+  return rest === 0 ? `${hours}\u00a0hr` : `${hours}\u00a0hr\u00a0${rest}\u00a0min`
+}
+
+// cooking is a card's "method · duration" line, "Crock pot · 6 hr", with
+// whichever of the two is known, or null when neither is.
+export function cooking(dinner: PlanDinner): string | null {
+  const parts = [dinner.method && methodLabels[dinner.method], dinner.minutes !== null && duration(dinner.minutes)].filter(
+    (part): part is string => typeof part === 'string',
+  )
+  return parts.length === 0 ? null : parts.join(' · ')
+}
+
+// ago is how long before now the instant at was: "just now", "2 min ago",
+// "3 hr ago", "2 days ago".
+export function ago(at: Date, now: Date): string {
+  const minutes = Math.floor((now.getTime() - at.getTime()) / 60_000)
+  if (minutes < 1) return 'just now'
+  if (minutes < 60) return `${minutes} min ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours} hr ago`
+  const days = Math.floor(hours / 24)
+  return days === 1 ? '1 day ago' : `${days} days ago`
+}
+
+// pushedToCalendar says whether drafting over a plan of this status needs
+// confirm: it was pushed to Calendar.
+function pushedToCalendar(status: PlanStatus): boolean {
+  return status !== 'draft'
+}
+
+// DayTile is one day of the Draft board: a Regular on the surface, a
+// Quest-log pick in teal with its "NEW" kicker, and a crock-pot dinner's
+// start-by time in the household's zone. Tapping it opens the swap sheet;
+// while that is open the tile is swapping: on the page background, ringed in
+// grape, its name muted.
+function DayTile({ day, timezone, swapping, onSwap }: { day: PlanDay; timezone: string; swapping: boolean; onSwap: () => void }) {
+  const kicker = weekdayKicker(day.date)
+  const classes = [styles.tile, day.is_new && styles.newTile, swapping && styles.swapping].filter(Boolean).join(' ')
+  return (
+    <li className={classes}>
+      <button type="button" className={styles.tileButton} onClick={onSwap}>
+        <span className={styles.dayKicker}>{swapping ? `${kicker} · SWAPPING…` : day.is_new ? `${kicker} · NEW` : kicker}</span>
+        <span>
+          <span className={styles.dinner}>{day.dinner.name}</span>
+          {day.start_by !== null && (
+            <span className={styles.startBy}>Start by {formatClockTime(localNow(timezone, new Date(day.start_by)).time)}</span>
+          )}
+        </span>
+      </button>
+    </li>
+  )
+}
+
+// DayColumn is one day of the plan manager's 7-column grid: its day label
+// over a card with the dinner's washed photo, name, method and time, a
+// crock-pot dinner's start-by time in the household's zone, and its Regular
+// or Side quest tag, a Side quest's card in teal. The swap icon opens the swap
+// sheet; while that is open the card is swapping, ringed in grape. A dinner
+// dragged over the day drops on it: the card is swapping, covered by a
+// dashed grape "Drop to swap" saying which dinner it replaces.
+function DayColumn({ day, timezone, swapping, onSwap }: { day: PlanDay; timezone: string; swapping: boolean; onSwap: () => void }) {
+  const { dinner } = day
+  const time = cooking(dinner)
+  const target = useDropTarget(day.date) !== null
+  const classes = [styles.card, day.is_new && styles.sideQuestCard, (swapping || target) && styles.swapping].filter(Boolean).join(' ')
+  return (
+    <li className={styles.column} aria-label={weekdayName(day.date)} {...{ [DROP_DATE]: day.date }}>
+      <p className={styles.dayLabel} aria-hidden="true">
+        <span className={styles.dayName}>{weekdayKicker(day.date)}</span>
+        <span className={styles.dayNumber}>{dayOfMonth(day.date)}</span>
+      </p>
+      <div className={classes}>
+        {/* The card's name already says what the photo shows. */}
+        <span aria-hidden="true">
+          <Photo id={dinner.photo_id} name={dinner.name} radius="18px" sizes="160px" className={styles.cardPhoto} />
+        </span>
+        <p className={styles.cardName}>{dinner.name}</p>
+        {time !== null && <p className={styles.cardMinutes}>{time}</p>}
+        {day.start_by !== null && (
+          <p className={styles.cardStartBy}>Start by {formatClockTime(localNow(timezone, new Date(day.start_by)).time)}</p>
+        )}
+        <div className={styles.cardFooter}>
+          <Tag tone={day.is_new ? 'grape' : 'neutral'} className={styles.cardTag}>{day.is_new ? 'Side quest' : 'Regular'}</Tag>
+          <IconButton label={`Swap ${weekdayName(day.date)}`} className={styles.swapButton} onClick={onSwap}>
+            <Icon icon={RefreshCw} size="inline" />
+          </IconButton>
+        </div>
+        {target && (
+          <div className={styles.dropTarget}>
+            <p className={styles.dropTitle}>Drop to swap</p>
+            <p className={styles.dropReplaces}>Replaces {dinner.name}</p>
+          </div>
+        )}
+      </div>
+    </li>
+  )
+}
+
+// SkeletonTiles stands in for the seven days while the plan loads or the AI
+// drafts it, as two columns of tiles on mobile and seven columns wider.
+function SkeletonTiles({ label, layout, children }: { label: string; layout: Breakpoint; children?: string }) {
+  const wide = layout !== 'mobile'
+  return (
+    <section aria-busy="true" aria-label={label} className={styles.loading}>
+      <div className={wide ? `${styles.week} ${styles[layout]}` : styles.grid}>
+        {Array.from({ length: 7 }, (_, i) => (
+          <Skeleton key={i} data-testid="skeleton-tile" className={wide ? styles.skeletonCard : styles.skeletonTile} />
+        ))}
+      </div>
+      {children !== undefined && <p className={styles.drafting}>{children}</p>}
+    </section>
+  )
+}
+
+// WeekBoard is the Draft board of the week starting on weekStart. Drafting
+// it — the empty state's "Draft this week" or the "+ Rebuild week" tile —
+// starts the draft_week job and shows skeleton tiles until the job ends and
+// the plan is read again. Rebuilding a plan pushed to Calendar asks first,
+// and sends confirm. A failed draft is shown with Retry; no plan is made up.
+//
+// From tablet up it is the plan manager (mocks 2c, 2d): Rebuild week and the
+// unavailable Shopping list and Push to Calendar are actions in the header,
+// over the plan's sync status and the 7-column grid.
+function WeekBoard({
+  weekStart,
+  timezone,
+  layout,
+  onWeek,
+}: {
+  weekStart: string
+  timezone: string
+  layout: Breakpoint
+  onWeek: (weekStart: string) => void
+}) {
+  const queryClient = useQueryClient()
+  const plan = usePlan(weekStart)
+  const startDraft = useStartDraft()
+  const [jobId, setJobId] = useState<string | null>(null)
+  const job = useJob<unknown>(DRAFT_JOB_KIND, jobId)
+  const [confirming, setConfirming] = useState(false)
+  const swap = useSwapDay(weekStart)
+  // The date of the day being swapped, while the swap sheet is open.
+  const [swappingDate, setSwappingDate] = useState<string | null>(null)
+  const label = weekLabel(weekStart)
+
+  // The draft's result, once the job has succeeded, or why it cannot be read.
+  const result = useMemo((): { draft: DraftResult | null; error: Error | null } => {
+    if (job.status !== 'succeeded') return { draft: null, error: null }
+    try {
+      return { draft: parseDraftResult(`GET /api/v1/jobs/${jobId}`, weekStart, job.result), error: null }
+    } catch (error) {
+      return { draft: null, error: error as Error }
+    }
+  }, [job.status, job.result, jobId, weekStart])
+
+  // Once the job ends the plan is read again: a succeeded draft is followed
+  // until that read lands; a failed one stays shown, and may have met a
+  // plan changed meanwhile. The Quest log is read again too, as after a
+  // swap: the draft may have planned some of it.
+  const [readJobId, setReadJobId] = useState<string | null>(null)
+  const ended = job.status === 'succeeded' || job.status === 'failed'
+  useEffect(() => {
+    if (!ended) return
+    let active = true
+    void queryClient.invalidateQueries({ queryKey: QUEST_LOG_KEY })
+    void queryClient.invalidateQueries({ queryKey: planKey(weekStart) }).then(() => {
+      if (active) setReadJobId(jobId)
+    })
+    return () => {
+      active = false
+    }
+  }, [queryClient, ended, jobId, weekStart])
+
+  // The plan read shows once it is the one drafted, read from the server; no
+  // plan, another one, or a copy cached before the draft (a redraft keeps the
+  // plan's id) is an error rather than an empty or stale board. Its Retry
+  // reads the plan again, keeping the job: a later read from the server that
+  // is the draft still lands it.
+  const { draft } = result
+  const read = draft !== null && readJobId === jobId && plan.isSuccess
+  const landed = read && plan.data?.id === draft.plan_id && !plan.data.cached
+  const unreadError =
+    read && !landed
+      ? new Error(
+          plan.data === null
+            ? `The week has no plan, not draft ${draft.plan_id}.`
+            : plan.data.id !== draft.plan_id
+              ? `The week's plan is not draft ${draft.plan_id}.`
+              : `The plan came from this device's cache, not the server, so it may not be draft ${draft.plan_id} yet.`,
+        )
+      : null
+  const resultError = result.error ?? unreadError
+  useEffect(() => {
+    if (landed) setJobId(null)
+  }, [landed])
+
+  const drafting = startDraft.isPending || (jobId !== null && job.status !== 'failed' && resultError === null)
+
+  const { mutate } = startDraft
+  function start(confirm: boolean) {
+    setConfirming(false)
+    // A draft asked for again leaves the last one's failure, and a failed
+    // swap's, behind.
+    setJobId(null)
+    swap.dismiss()
+    mutate(
+      { weekStart, confirm },
+      {
+        onSuccess: setJobId,
+        // A plan pushed to Calendar meanwhile needs confirm: read it again.
+        onError: () => void queryClient.invalidateQueries({ queryKey: planKey(weekStart) }),
+      },
+    )
+  }
+  // rebuild drafts the week, asking first over a plan pushed to Calendar.
+  // It waits for a swap of the week still pending, which may yet fail: the
+  // Rebuild week tile is disabled meanwhile.
+  function rebuild() {
+    if (swap.pending) return
+    if (plan.data && pushedToCalendar(plan.data.status)) setConfirming(true)
+    else start(false)
+  }
+
+  const failure = swap.failed !== null ? (
+    <ErrorBanner onRetry={() => swapIn(swap.failed!.swap)}>
+      Couldn't swap {weekdayName(swap.failed.swap.date)}'s dinner. {swap.failed.error.message}
+    </ErrorBanner>
+  ) : startDraft.isError ? (
+    <ErrorBanner onRetry={rebuild}>Couldn't start drafting this week. {startDraft.error.message}</ErrorBanner>
+  ) : result.error !== null ? (
+    <ErrorBanner onRetry={rebuild}>Couldn't read the draft. {result.error.message}</ErrorBanner>
+  ) : unreadError !== null ? (
+    <ErrorBanner onRetry={() => void plan.refetch()}>Couldn't read the draft. {unreadError.message}</ErrorBanner>
+  ) : job.error === null ? null : job.status === 'failed' ? (
+    <ErrorBanner onRetry={rebuild}>
+      Couldn't draft this week. {draftFailures[job.error.message] ?? job.error.message}
+    </ErrorBanner>
+  ) : (
+    <ErrorBanner onRetry={job.poll}>Couldn't check on the draft. {job.error.message}</ErrorBanner>
+  )
+
+  // swapIn sends the swap chosen in the sheet and closes it.
+  function swapIn(chosen: Swap) {
+    setSwappingDate(null)
+    swap.mutate(chosen)
+  }
+  // dropIn swaps in a dinner dragged onto a day. A drag is not picked up,
+  // nor dropped, while a swap of the week is pending.
+  function dropIn(chosen: Swap) {
+    swap.dismiss()
+    swapIn(chosen)
+  }
+  // openSwap opens the swap sheet on a day. One swap of the week is sent at
+  // a time, even across leaving the week and coming back: the plan the
+  // server answers it with must not overwrite another still pending.
+  function openSwap(date: string) {
+    if (swap.pending) return
+    swap.dismiss()
+    setSwappingDate(date)
+  }
+
+  let body
+  if (plan.isError) {
+    body = <ErrorBanner onRetry={() => void plan.refetch()}>Couldn't load this week's plan. {plan.error.message}</ErrorBanner>
+  } else if (drafting) {
+    body = (
+      <SkeletonTiles label="Drafting this week" layout={layout}>
+        Drafting your week…
+      </SkeletonTiles>
+    )
+  } else if (resultError !== null) {
+    // An unread draft shows no board: the plan read is not the draft.
+    body = null
+  } else if (plan.isPending) {
+    body = <SkeletonTiles label="Plan loading" layout={layout} />
+  } else if (plan.data === null) {
+    body = (
+      <EmptyState title="Nothing planned yet" action={{ label: 'Draft this week', onClick: rebuild }}>
+        I'll draft seven dinners from your Regulars and Quest log.
+      </EmptyState>
+    )
+  } else {
+    const { ai_note, days } = plan.data
+    const swappingDay = days.find((day) => day.date === swappingDate)
+    const sheet = swappingDay !== undefined && (
+      <SwapSheet
+        day={swappingDay}
+        planned={new Set(days.map((day) => day.dinner.id))}
+        onSwap={swapIn}
+        onClose={() => setSwappingDate(null)}
+      />
+    )
+    body =
+      layout !== 'mobile' ? (
+        <>
+          <DropBoard days={days} pending={swap.pending} drop={dropIn} />
+          <ul className={`${styles.week} ${styles[layout]}`} aria-label="Dinners this week">
+            {days.map((day) => (
+              <DayColumn
+                key={day.date}
+                day={day}
+                timezone={timezone}
+                swapping={day.date === swappingDate}
+                onSwap={() => openSwap(day.date)}
+              />
+            ))}
+          </ul>
+          {sheet}
+        </>
+      ) : (
+        <>
+          {ai_note !== null && (
+            <div className={styles.assistant}>
+              <span className={styles.avatar} aria-hidden="true">
+                Q
+              </span>
+              <p className={styles.bubble}>{ai_note}</p>
+            </div>
+          )}
+          <ul className={styles.grid} aria-label="Dinners this week">
+            {days.map((day) => (
+              <DayTile
+                key={day.date}
+                day={day}
+                timezone={timezone}
+                swapping={day.date === swappingDate}
+                onSwap={() => openSwap(day.date)}
+              />
+            ))}
+            <li className={styles.rebuildCell}>
+              <button type="button" className={styles.rebuild} onClick={rebuild} disabled={swap.pending}>
+                <Icon icon={Plus} size="inline" />
+                Rebuild week
+              </button>
+            </li>
+          </ul>
+          <Unavailable hint={PUSH_HINT} className={styles.pushButton}>
+            Looks good — push to Calendar
+          </Unavailable>
+          {sheet}
+        </>
+      )
+  }
+
+  const tag = plan.data ? statusTags[plan.data.status] : null
+  const header =
+    layout !== 'mobile' ? (
+      <header className={styles.wideHeader}>
+        <div className={styles.titleBar}>
+          <div className={styles.heading}>
+            <p className={styles.kicker}>{label.week} · Plan</p>
+            <h1 className={styles.wideTitle}>{label.dates}</h1>
+          </div>
+          <div className={styles.weekNav}>
+            <IconButton label="Previous week" onClick={() => onWeek(addDays(weekStart, -7))}>
+              <Icon icon={ChevronLeft} size="inline" />
+            </IconButton>
+            {layout === 'desktop' && (
+              <button type="button" className={styles.thisWeek} onClick={() => onWeek(weekOf(localNow(timezone, new Date()).date))}>
+                This week
+              </button>
+            )}
+            <IconButton label="Next week" onClick={() => onWeek(addDays(weekStart, 7))}>
+              <Icon icon={ChevronRight} size="inline" />
+            </IconButton>
+          </div>
+        </div>
+        <div className={styles.actionBar}>
+          {plan.data ? <SyncStatus plan={plan.data} /> : <span className={styles.status} />}
+          <div className={styles.actions}>
+            <Unavailable hint={SHOPPING_HINT} variant="outline" below className={styles.action}>
+              <Icon icon={ShoppingCart} size="inline" />
+              Shopping list
+            </Unavailable>
+            <Button variant="outline" className={styles.action} onClick={rebuild} disabled={swap.pending || drafting || !plan.isSuccess}>
+              <Icon icon={RefreshCw} size="inline" />
+              Rebuild week
+            </Button>
+            <Unavailable hint={PUSH_HINT} below className={styles.action}>
+              <Icon icon={CalendarDays} size="inline" />
+              Push to Calendar
+            </Unavailable>
+          </div>
+        </div>
+      </header>
+    ) : (
+      <header className={styles.header}>
+        <div className={styles.heading}>
+          <p className={styles.kicker}>{label.week}</p>
+          <div className={styles.titleRow}>
+            <h1 className={styles.title}>{label.dates}</h1>
+            {tag !== null && <Tag tone={tag.tone}>{tag.label}</Tag>}
+          </div>
+        </div>
+        <div className={styles.weekNav}>
+          <IconButton label="Previous week" onClick={() => onWeek(addDays(weekStart, -7))}>
+            <Icon icon={ChevronLeft} size="inline" />
+          </IconButton>
+          <IconButton label="Next week" onClick={() => onWeek(addDays(weekStart, 7))}>
+            <Icon icon={ChevronRight} size="inline" />
+          </IconButton>
+        </div>
+      </header>
+    )
+  return (
+    <>
+      {header}
+      {body}
+      {failure}
+      <Confirm
+        open={confirming}
+        title="Rebuild this week?"
+        confirmLabel="Rebuild week"
+        cancelLabel="Keep this plan"
+        onCancel={() => setConfirming(false)}
+        onConfirm={() => start(true)}
+      >
+        This week is already pushed to Calendar. The AI assistant drafts a new plan in its place.
+      </Confirm>
+    </>
+  )
+}
+
+// SyncStatus is the plan manager's status line: whether the plan is on
+// Google Calendar and, once synced, how long ago it was pushed, kept current
+// minute by minute.
+function SyncStatus({ plan }: { plan: Plan }) {
+  const { status, calendar_synced_at: syncedAt } = plan
+  const [now, setNow] = useState(() => new Date())
+  useEffect(() => {
+    const timer = setInterval(() => setNow(new Date()), 60_000)
+    return () => clearInterval(timer)
+  }, [])
+  return (
+    <p className={[styles.status, status === 'synced' && styles.synced].filter(Boolean).join(' ')}>
+      {status === 'synced' && <Icon icon={Check} size="inline" />}
+      {syncStatuses[status]}
+      {status === 'synced' && syncedAt !== null && ` ${ago(syncedAt, now)}`}
+    </p>
+  )
+}
+
+// Unavailable is an action with nothing behind it yet (Push to Calendar, the
+// shopping list): it stays focusable, so a tap or focus shows the tooltip
+// saying why, above it or, at the top of the page, below.
+function Unavailable({
+  hint,
+  variant = 'primary',
+  below = false,
+  className,
+  children,
+}: {
+  hint: string
+  variant?: ButtonVariant
+  below?: boolean
+  className?: string
+  children: ReactNode
+}) {
+  const hintId = useId()
+  return (
+    <div className={[styles.unavailable, below && styles.below].filter(Boolean).join(' ')}>
+      <Button
+        variant={variant}
+        className={[className, styles[variant]].filter(Boolean).join(' ')}
+        aria-disabled="true"
+        aria-describedby={hintId}
+      >
+        {children}
+      </Button>
+      <span id={hintId} role="tooltip" className={styles.hint}>
+        {hint}
+      </span>
+    </div>
+  )
+}
+
+// PlanPage is the Draft board on the week chosen with the previous / next
+// week buttons: mock 1f on mobile; from tablet up the plan manager, with the
+// Quest log as a strip under the grid on tablet (2c) and the Quest log and
+// Regulars in a right panel on desktop (2d). It opens on next week once this
+// week's plan_draft time has come in the household's zone, otherwise on this
+// week. The board keeps its place in the tree across layouts, so crossing a
+// breakpoint keeps a draft being followed. From tablet up a dinner is
+// dragged from the strip or the panel onto a day of the grid to swap it in.
+export function PlanPage() {
+  const layout = useBreakpoint()
+  const settings = useHouseholdSettings()
+  const [week, setWeek] = useState<string | null>(null)
+  if (week === null && settings.data) setWeek(defaultWeek(settings.data, new Date()))
+
+  let content
+  if (settings.isError) {
+    content = (
+      <ErrorBanner onRetry={() => void settings.refetch()}>Couldn't load the household settings. {settings.error.message}</ErrorBanner>
+    )
+  } else if (week === null || !settings.data) {
+    content = <SkeletonTiles label="Plan loading" layout={layout} />
+  } else {
+    content = <WeekBoard key={week} weekStart={week} timezone={settings.data.timezone} layout={layout} onWeek={setWeek} />
+  }
+  return (
+    <PlanDragProvider>
+      <div className={`${styles.page} ${styles[`${layout}Page`]}`}>
+        <div className={styles.board}>
+          {content}
+          {layout === 'tablet' && <QuestLogStrip />}
+        </div>
+        {layout === 'desktop' && <PlanPanel />}
+        {layout !== 'mobile' && <DragAnnouncer />}
+      </div>
+    </PlanDragProvider>
+  )
+}

web/src/plan/PlanPanel.module.css

@@ -0,0 +1,223 @@
+/* Desktop's right panel (mock 2d) and tablet's Quest-log strip (mock 2c). */
+.panel {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 32px 22px;
+  border-left: 1px solid var(--color-divider);
+}
+
+.hint {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 13px;
+  color: var(--color-neutral-800);
+}
+
+.rows {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.row {
+  box-sizing: border-box;
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px;
+  border-radius: 22px;
+  background: var(--color-surface);
+  text-align: left;
+}
+
+/* The 48 px washed photo; Photo applies the washed filter. The placeholder's
+   "dish photo" caption does not fit, so only its stripes show. */
+.rowPhoto {
+  width: 48px;
+  height: 48px;
+  font-size: 0;
+}
+
+.rowText {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  font-family: var(--font-body);
+}
+
+.rowName {
+  font-size: 14px;
+  font-weight: 700;
+  overflow-wrap: anywhere;
+}
+
+.rowMeta {
+  font-size: 12px;
+  color: var(--color-neutral-700);
+}
+
+/* Two columns of three 4 px dots. */
+.grip {
+  flex: none;
+  display: grid;
+  grid-template-columns: 4px 4px;
+  gap: 3px;
+}
+
+.dot {
+  width: 4px;
+  height: 4px;
+  border-radius: var(--radius-pill);
+  background: var(--color-neutral-500);
+}
+
+.more {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-height: 44px;
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--color-accent-700);
+  text-decoration: none;
+}
+
+.more:hover {
+  text-decoration: underline;
+}
+
+.loading {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.skeleton {
+  height: 68px;
+  border-radius: 22px;
+}
+
+.empty {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--color-neutral-700);
+}
+
+/* Tablet: the Quest log as chips on a surface card under the grid. */
+.strip {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 16px 18px;
+  border-radius: var(--radius-lg);
+  background: var(--color-surface);
+}
+
+.stripHeader {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 12px;
+}
+
+.stripTitle {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 18px;
+  font-weight: 400;
+}
+
+.stripHint {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.chips {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+}
+
+.chip {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 5px 14px 5px 5px;
+  border-radius: var(--radius-pill);
+  background: var(--color-bg);
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+}
+
+/* As the row's photo, at 28 px. */
+.chipPhoto {
+  width: 28px;
+  height: 28px;
+  font-size: 0;
+}
+
+/* A row or a chip is a button dragged onto a day: by a pointer (no
+   scrolling or text selection under it) or with the keyboard. Its 2 px
+   border is clear until it is the ghost, inside its padding. */
+.draggable {
+  margin: 0;
+  border: 2px solid transparent;
+  font: inherit;
+  color: var(--color-text);
+  cursor: grab;
+  touch-action: none;
+  user-select: none;
+}
+
+.row.draggable {
+  padding: 8px;
+}
+
+.chip.draggable {
+  padding: 3px 12px 3px 3px;
+}
+
+/* A dinner that cannot be picked up now: no grid to drop on, a swap
+   pending, or already this week. */
+.draggable[aria-disabled='true'] {
+  cursor: default;
+}
+
+/* The row or chip being dragged: a dashed ghost at 55% opacity. */
+.ghost {
+  border-style: dashed;
+  border-color: var(--color-neutral-500);
+  background: transparent;
+  opacity: 0.55;
+}
+
+/* The dragged copy floating below right of the pointer: lifted with the
+   large shadow and tilted -3deg. It lets the pointer through to the day
+   under it. */
+.floating {
+  position: fixed;
+  z-index: 10;
+  box-sizing: border-box;
+  margin: 0;
+  box-shadow: var(--shadow-lg);
+  transform: rotate(-3deg);
+  pointer-events: none;
+  cursor: grabbing;
+}

web/src/plan/PlanPanel.tsx

@@ -0,0 +1,210 @@
+import { Compass } from 'lucide-react'
+import { useId, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { Link } from 'react-router'
+import { useRegulars } from '../dinners/api.ts'
+import { useQuestLog, type QuestLogDinner } from '../discover/api.ts'
+import { DIFFICULTY_LABEL } from '../discover/DeckCard.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { Photo } from '../ui/Photo.tsx'
+import { Segmented } from '../ui/Segmented.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { useDraggable, type Float } from './drag.tsx'
+import { emptyLists, planDinner, sourceNames, type Source } from './SwapSheet.tsx'
+import styles from './PlanPanel.module.css'
+
+// DRAG_HINT says how a dinner is swapped in from the panel or the strip.
+const DRAG_HINT = 'Drag a dinner onto a day to swap it in.'
+
+// KEYS_HINT says how a dinner is swapped in with the keyboard.
+const KEYS_HINT = 'Press Enter or Space to pick it up, the arrow keys to choose a day, Enter to drop it on that day and Escape to cancel.'
+
+type List = ReturnType<typeof useQuestLog>
+
+// ListBody is a list of the panel or the strip once it has loaded, or why it
+// has not: its error with Retry, skeletons while loading, or that it is
+// empty.
+function ListBody({ source, list, children }: { source: Source; list: List; children: (dinners: QuestLogDinner[]) => ReactNode }) {
+  if (list.isError) {
+    return (
+      <ErrorBanner onRetry={() => void list.refetch()}>
+        Couldn't load your {sourceNames[source]}. {list.error.message}
+      </ErrorBanner>
+    )
+  }
+  if (list.isPending) {
+    return (
+      <div aria-busy="true" aria-label={`${sourceNames[source]} loading`} className={styles.loading}>
+        {Array.from({ length: 3 }, (_, i) => (
+          <Skeleton key={i} className={styles.skeleton} />
+        ))}
+      </div>
+    )
+  }
+  if (list.data.length === 0) return <p className={styles.empty}>{emptyLists[source]}</p>
+  return children(list.data)
+}
+
+// Grip is the 6-dot drag handle of a panel row.
+function Grip() {
+  return (
+    <span className={styles.grip} aria-hidden="true">
+      {Array.from({ length: 6 }, (_, i) => (
+        <span key={i} className={styles.dot} />
+      ))}
+    </span>
+  )
+}
+
+// Draggable is a dinner of the panel or the strip, dragged onto a day to
+// swap it in: a button whose content is the row or the chip. While it is
+// dragged it is a dashed ghost, and with a pointer a copy of it floats
+// below right of the pointer, lifted and tilted.
+function Draggable({
+  dinner,
+  fromQuestLog,
+  className,
+  keysHintId,
+  children,
+}: {
+  dinner: QuestLogDinner
+  fromQuestLog: boolean
+  className: string | undefined
+  keysHintId: string
+  children: ReactNode
+}) {
+  const { drag, float, props } = useDraggable({ dinner: planDinner(dinner), fromQuestLog })
+  return (
+    <li>
+      <button
+        type="button"
+        className={[className, styles.draggable, drag !== null && styles.ghost].filter(Boolean).join(' ')}
+        aria-describedby={keysHintId}
+        {...props}
+      >
+        {children}
+      </button>
+      {float !== null && <Floating float={float} className={className}>{children}</Floating>}
+    </li>
+  )
+}
+
+// Floating is the dragged copy of a row or a chip, drawn over the page.
+function Floating({ float, className, children }: { float: Float; className: string | undefined; children: ReactNode }) {
+  return createPortal(
+    <div
+      aria-hidden="true"
+      data-testid="drag-float"
+      className={[className, styles.floating].filter(Boolean).join(' ')}
+      style={{ left: float.left, top: float.top, width: float.width }}
+    >
+      {children}
+    </div>,
+    document.body,
+  )
+}
+
+// KeysHint is the keyboard's way to swap a dinner in, describing each
+// draggable.
+function KeysHint({ id }: { id: string }) {
+  return (
+    <p id={id} hidden>
+      {KEYS_HINT}
+    </p>
+  )
+}
+
+// PlanPanel is desktop's right panel (mock 2d): the Quest log and the
+// Regulars, segmented "Quest log · N | Regulars · N", each dinner with its
+// 48 px photo, name, difficulty and grip, and a link to swipe more Side
+// quests.
+export function PlanPanel() {
+  const questLog = useQuestLog()
+  const regulars = useRegulars()
+  const [source, setSource] = useState<Source>('quest_log')
+  const lists = { quest_log: questLog, regulars }
+  const keysHintId = useId()
+
+  const label = (s: Source) => {
+    const dinners = lists[s].data
+    return dinners === undefined ? sourceNames[s] : `${sourceNames[s]} · ${dinners.length}`
+  }
+
+  return (
+    <aside aria-label="Quest log and Regulars" className={styles.panel}>
+      <Segmented
+        label="Dinners to swap in"
+        options={[
+          { value: 'quest_log', label: label('quest_log') },
+          { value: 'regulars', label: label('regulars') },
+        ]}
+        value={source}
+        onValueChange={setSource}
+      />
+      <p className={styles.hint}>{DRAG_HINT}</p>
+      <KeysHint id={keysHintId} />
+      <ListBody source={source} list={lists[source]}>
+        {(dinners) => (
+          <ul aria-label={sourceNames[source]} className={styles.rows}>
+            {dinners.map((dinner) => (
+              <Draggable
+                key={dinner.id}
+                dinner={dinner}
+                fromQuestLog={source === 'quest_log'}
+                className={styles.row}
+                keysHintId={keysHintId}
+              >
+                {/* The row's name already says what the photo shows. */}
+                <span aria-hidden="true">
+                  <Photo id={dinner.photo_id} name={dinner.name} radius="var(--radius-pill)" sizes="48px" className={styles.rowPhoto} />
+                </span>
+                <span className={styles.rowText}>
+                  <span className={styles.rowName}>{dinner.name}</span>
+                  {dinner.difficulty !== null && <span className={styles.rowMeta}>{DIFFICULTY_LABEL[dinner.difficulty]}</span>}
+                </span>
+                <Grip />
+              </Draggable>
+            ))}
+          </ul>
+        )}
+      </ListBody>
+      <Link to="/discover" className={styles.more}>
+        <Icon icon={Compass} size="inline" />
+        Swipe more side quests
+      </Link>
+    </aside>
+  )
+}
+
+// QuestLogStrip is tablet's Quest log under the week's grid (mock 2c): each
+// dinner a chip with its 28 px photo and name, dragged as the panel's rows
+// are.
+export function QuestLogStrip() {
+  const questLog = useQuestLog()
+  const keysHintId = useId()
+  const title = questLog.data === undefined ? sourceNames.quest_log : `${sourceNames.quest_log} · ${questLog.data.length}`
+  return (
+    <section aria-label={sourceNames.quest_log} className={styles.strip}>
+      <div className={styles.stripHeader}>
+        <h2 className={styles.stripTitle}>{title}</h2>
+        <p className={styles.stripHint}>{DRAG_HINT}</p>
+      </div>
+      <KeysHint id={keysHintId} />
+      <ListBody source="quest_log" list={questLog}>
+        {(dinners) => (
+          <ul aria-label={`${sourceNames.quest_log} dinners`} className={styles.chips}>
+            {dinners.map((dinner) => (
+              <Draggable key={dinner.id} dinner={dinner} fromQuestLog className={styles.chip} keysHintId={keysHintId}>
+                <span aria-hidden="true">
+                  <Photo id={dinner.photo_id} name={dinner.name} radius="var(--radius-pill)" sizes="28px" className={styles.chipPhoto} />
+                </span>
+                {dinner.name}
+              </Draggable>
+            ))}
+          </ul>
+        )}
+      </ListBody>
+    </section>
+  )
+}

web/src/plan/SwapSheet.module.css

@@ -0,0 +1,57 @@
+/* The mobile swap sheet: the Quest log and Regulars of desktop's plan panel
+   (mock 2d) as a bottom sheet. */
+.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;
+}
+
+.replaces {
+  margin: 2px 0 0;
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--color-neutral-700);
+}
+
+.rows {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+}
+
+/* The 48 px washed photo; Photo applies the washed filter. */
+.photo {
+  width: 48px;
+  height: 48px;
+}
+
+/* A dinner already this week: shown, muted, and not a button. */
+.already {
+  color: var(--color-neutral-600);
+}
+
+.skeletonRow {
+  height: 72px;
+  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/plan/SwapSheet.tsx

@@ -0,0 +1,129 @@
+import { useId, useState } from 'react'
+import { useRegulars } from '../dinners/api.ts'
+import { useQuestLog, type QuestLogDinner } from '../discover/api.ts'
+import { details } from '../discover/QuestLogSheet.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { ListRow } from '../ui/ListRow.tsx'
+import { Photo } from '../ui/Photo.tsx'
+import { Segmented } from '../ui/Segmented.tsx'
+import { Sheet } from '../ui/Sheet.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { Tag } from '../ui/Tag.tsx'
+import type { PlanDay, PlanDinner, Swap } from './api.ts'
+import { weekdayName } from './week.ts'
+import styles from './SwapSheet.module.css'
+
+// Source is a list a dinner is swapped in from.
+export type Source = 'quest_log' | 'regulars'
+
+export const sourceNames: Record<Source, string> = { quest_log: 'Quest log', regulars: 'Regulars' }
+
+export const emptyLists: Record<Source, string> = {
+  quest_log: 'Your Quest log is empty — swipe right on a Side quest to add one.',
+  regulars: 'You have no Regulars yet.',
+}
+
+// planDinner is a listed dinner as it is planned on a day.
+export function planDinner(dinner: QuestLogDinner): PlanDinner {
+  return { id: dinner.id, name: dinner.name, photo_id: dinner.photo_id, minutes: dinner.minutes_total, method: dinner.method }
+}
+
+export type SwapSheetProps = {
+  // The day being swapped.
+  day: PlanDay
+  // The ids of the dinners already on the week's plan.
+  planned: ReadonlySet<string>
+  onSwap: (swap: Swap) => void
+  onClose: () => void
+}
+
+// SwapSheet is the mobile swap sheet: the Quest log and the Regulars, as
+// desktop's plan panel lists them, segmented "Quest log · N | Regulars · N",
+// each dinner with its 48 px photo, name, difficulty and minutes. Choosing a
+// dinner swaps it into the day; a dinner already this week can't be chosen.
+export function SwapSheet({ day, planned, onSwap, onClose }: SwapSheetProps) {
+  const titleId = useId()
+  const questLog = useQuestLog()
+  const regulars = useRegulars()
+  const [source, setSource] = useState<Source>('quest_log')
+  const lists = { quest_log: questLog, regulars }
+  const list = lists[source]
+
+  const label = (s: Source) => {
+    const dinners = lists[s].data
+    return dinners === undefined ? sourceNames[s] : `${sourceNames[s]} · ${dinners.length}`
+  }
+
+  let body
+  if (list.isError) {
+    body = (
+      <ErrorBanner onRetry={() => void list.refetch()}>
+        Couldn't load your {sourceNames[source]}. {list.error.message}
+      </ErrorBanner>
+    )
+  } else if (list.isPending) {
+    body = (
+      <div aria-busy="true" aria-label={`${sourceNames[source]} loading`} className={styles.rows}>
+        {Array.from({ length: 3 }, (_, i) => (
+          <Skeleton key={i} className={styles.skeletonRow} />
+        ))}
+      </div>
+    )
+  } else if (list.data.length === 0) {
+    body = <p className={styles.empty}>{emptyLists[source]}</p>
+  } else {
+    body = (
+      <ul aria-label={sourceNames[source]} className={styles.rows}>
+        {list.data.map((dinner: QuestLogDinner) => {
+          const already = planned.has(dinner.id)
+          return (
+            <li key={dinner.id}>
+              <ListRow
+                className={already ? styles.already : undefined}
+                leading={
+                  // The row's name already says what the photo shows.
+                  <span aria-hidden="true">
+                    <Photo id={dinner.photo_id} name={dinner.name} radius="var(--radius-md)" sizes="48px" className={styles.photo} />
+                  </span>
+                }
+                title={dinner.name}
+                meta={details(dinner)}
+                // A dinner already this week is no button: it can't be chosen.
+                onClick={
+                  already
+                    ? undefined
+                    : () =>
+                        onSwap({ date: day.date, dinner: planDinner(dinner), fromQuestLog: source === 'quest_log' })
+                }
+                trailing={already && <Tag>Already this week</Tag>}
+              />
+            </li>
+          )
+        })}
+      </ul>
+    )
+  }
+
+  return (
+    <Sheet open onClose={onClose} aria-labelledby={titleId}>
+      <div className={styles.sheet}>
+        <div>
+          <h2 id={titleId} className={styles.title}>
+            Swap {weekdayName(day.date)}
+          </h2>
+          <p className={styles.replaces}>Replaces {day.dinner.name}</p>
+        </div>
+        <Segmented
+          label="Swap in from"
+          options={[
+            { value: 'quest_log', label: label('quest_log') },
+            { value: 'regulars', label: label('regulars') },
+          ]}
+          value={source}
+          onValueChange={setSource}
+        />
+        {body}
+      </div>
+    </Sheet>
+  )
+}

web/src/plan/api.test.tsx

@@ -0,0 +1,205 @@
+import { QueryClientProvider, type QueryClient } from '@tanstack/react-query'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import type { ReactNode } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ApiProvider, createApiClient, createQueryClient, createVerifiedSession } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { errorResponse, fakeLocation, jsonResponse, ME } from '../test/fetchStub.ts'
+import { planKey, usePlan, useSwapDay, type Plan } from './api.ts'
+
+const WEEK = '2026-10-05'
+const PLAN = `/api/v1/plans/${WEEK}`
+const MONDAY = `${PLAN}/days/2026-10-05`
+const FRIDAY = `${PLAN}/days/2026-10-09`
+const DAYS = ['2026-10-05', '2026-10-06', '2026-10-07', '2026-10-08', '2026-10-09', '2026-10-10', '2026-10-11']
+
+// planBody is the plan of the week of Oct 5, dinners d0 to d6, with days
+// changed as given by index.
+function planBody(changes: Record<number, { id: string; name: string; is_new?: boolean; start_by?: string | null }> = {}) {
+  return {
+    id: 'plan-1',
+    week_start: WEEK,
+    status: 'draft',
+    ai_note: null,
+    calendar_synced_at: null as string | null,
+    days: DAYS.map((date, i) => {
+      const change = changes[i]
+      return {
+        date,
+        dinner: { id: change?.id ?? `d${i}`, name: change?.name ?? `Dinner ${i}`, photo: null, minutes: null, method: null as string | null, origin: 'regular' },
+        is_new: change?.is_new ?? false,
+        start_by: change?.start_by ?? null,
+      }
+    }),
+  }
+}
+
+// deferred is a reply the test sends when it chooses.
+function deferred() {
+  let send!: (response: Response) => void
+  const reply = new Promise<Response>((resolve) => (send = resolve))
+  return { reply, send }
+}
+
+// stubServer answers "METHOD path" requests from responders, with /me and
+// the Quest log; any other request fails the test.
+function stubServer(responders: Record<string, () => Response | Promise<Response>>) {
+  const all: Record<string, () => Response | Promise<Response>> = {
+    'GET /api/v1/me': () => jsonResponse(200, ME),
+    'GET /api/v1/dinners?status=quest_log': () => jsonResponse(200, { dinners: [] }),
+    ...responders,
+  }
+  vi.stubGlobal(
+    'fetch',
+    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())
+    }),
+  )
+}
+
+// renderSwaps renders the week's plan and swaps over a query client.
+async function renderSwaps() {
+  const api = createApiClient(fakeLocation('/plan'), createNetworkStatus(window), createVerifiedSession(localStorage))
+  await api.loadMe()
+  const queryClient: QueryClient = createQueryClient()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <ApiProvider client={api}>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </ApiProvider>
+  )
+  const hook = renderHook(() => ({ plan: usePlan(WEEK), swap: useSwapDay(WEEK) }), { wrapper })
+  await waitFor(() => expect(hook.result.current.plan.isSuccess).toBe(true))
+  return { ...hook, queryClient, plan: () => queryClient.getQueryData<Plan>(planKey(WEEK))! }
+}
+
+const ORZO = { date: '2026-10-09', dinner: { id: 'q1', name: 'Lemon orzo', photo_id: undefined, minutes: null, method: null }, fromQuestLog: true }
+const FISH = { date: '2026-10-05', dinner: { id: 'r1', name: 'Fish tacos', photo_id: undefined, minutes: null, method: null }, fromQuestLog: false }
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+// renderPlan renders the week's plan read over a query client.
+async function renderPlan() {
+  const api = createApiClient(fakeLocation('/plan'), createNetworkStatus(window), createVerifiedSession(localStorage))
+  await api.loadMe()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <ApiProvider client={api}>
+      <QueryClientProvider client={createQueryClient()}>{children}</QueryClientProvider>
+    </ApiProvider>
+  )
+  const hook = renderHook(() => usePlan(WEEK), { wrapper })
+  await waitFor(() => expect(hook.result.current.isPending).toBe(false))
+  return hook.result.current
+}
+
+describe('usePlan', () => {
+  it("reads each dinner's method and when the plan was pushed to Calendar", async () => {
+    const body = planBody()
+    body.days[2]!.dinner.method = 'crockpot'
+    stubServer({ [`GET ${PLAN}`]: () => jsonResponse(200, { ...body, status: 'synced', calendar_synced_at: '2026-10-07T15:58:00Z' }) })
+    const plan = await renderPlan()
+
+    expect(plan.data?.calendar_synced_at).toEqual(new Date('2026-10-07T15:58:00Z'))
+    expect(plan.data?.days.map((day) => day.dinner.method)).toEqual([null, null, 'crockpot', null, null, null, null])
+  })
+
+  it.each([
+    ['a method it does not know', (body: ReturnType<typeof planBody>) => (body.days[0]!.dinner.method = 'microwave'), 'method "microwave"'],
+    ['no method', (body: ReturnType<typeof planBody>) => Reflect.deleteProperty(body.days[0]!.dinner, 'method'), 'method undefined'],
+    ['a sync time that is no instant', (body: ReturnType<typeof planBody>) => (body.calendar_synced_at = 'yesterday'), 'calendar_synced_at "yesterday"'],
+  ])('refuses a plan with %s', async (_, change, said) => {
+    const body = planBody()
+    change(body)
+    stubServer({ [`GET ${PLAN}`]: () => jsonResponse(200, body) })
+    const plan = await renderPlan()
+
+    expect(plan.error?.message).toContain(said)
+  })
+})
+
+describe('useSwapDay', () => {
+  // Friday's swap is sent first, then Monday's; the server answers Monday's
+  // with both swapped, Friday's with only Friday.
+  const fridayPlan = planBody({ 4: { id: 'q1', name: 'Lemon orzo', is_new: true } })
+  const bothPlan = planBody({ 0: { id: 'r1', name: 'Fish tacos' }, 4: { id: 'q1', name: 'Lemon orzo', is_new: true } })
+
+  it.each([
+    ['the later swap answered first', ['monday', 'friday'] as const],
+    ['the earlier swap answered first', ['friday', 'monday'] as const],
+  ])('keeps the plan of the later of two swaps, %s', async (_, order) => {
+    const replies = { friday: deferred(), monday: deferred() }
+    stubServer({
+      [`GET ${PLAN}`]: () => jsonResponse(200, planBody()),
+      [`PUT ${FRIDAY}`]: () => replies.friday.reply,
+      [`PUT ${MONDAY}`]: () => replies.monday.reply,
+    })
+    const { result, plan, queryClient } = await renderSwaps()
+
+    act(() => result.current.swap.mutate(ORZO))
+    act(() => result.current.swap.mutate(FISH))
+    await waitFor(() => expect(plan().days[0]!.dinner.name).toBe('Fish tacos'))
+
+    // Whichever reply settles, Monday stays swapped: Friday's plan, the
+    // earlier one, never lands over it.
+    for (const [settled, day] of order.entries()) {
+      await act(async () => replies[day].send(jsonResponse(200, day === 'friday' ? fridayPlan : bothPlan)))
+      await waitFor(() => expect(queryClient.isMutating()).toBe(1 - settled))
+      expect(plan().days[0]!.dinner.name).toBe('Fish tacos')
+    }
+    expect(plan().days.map((day) => day.dinner.name)).toEqual(bothPlan.days.map((day) => day.dinner.name))
+  })
+
+  it("does not take an earlier swap's failure for the week's", async () => {
+    const friday = deferred()
+    stubServer({
+      [`GET ${PLAN}`]: () => jsonResponse(200, planBody()),
+      [`PUT ${FRIDAY}`]: () => friday.reply,
+      [`PUT ${MONDAY}`]: () => jsonResponse(200, planBody({ 0: { id: 'r1', name: 'Fish tacos' } })),
+    })
+    const { result, plan } = await renderSwaps()
+
+    act(() => result.current.swap.mutate(ORZO))
+    act(() => result.current.swap.mutate(FISH))
+    await waitFor(() => expect(plan().days[0]!.dinner.name).toBe('Fish tacos'))
+    await act(async () => friday.send(errorResponse(409, 'dinner_not_plannable')))
+
+    await waitFor(() => expect(result.current.swap.pending).toBe(false))
+    expect(result.current.swap.failed).toBeNull()
+  })
+
+  it('leaves a day a later plan read landed when the swap of it fails', async () => {
+    const friday = deferred()
+    // The read finds Friday already lemon orzo, starting by 2 pm.
+    let read = planBody()
+    stubServer({
+      [`GET ${PLAN}`]: () => jsonResponse(200, read),
+      [`PUT ${FRIDAY}`]: () => friday.reply,
+    })
+    const { result, plan, queryClient } = await renderSwaps()
+
+    act(() => result.current.swap.mutate(ORZO))
+    await waitFor(() => expect(plan().days[4]).toEqual({ date: '2026-10-09', dinner: ORZO.dinner, is_new: true, start_by: null }))
+    read = planBody({ 4: { id: 'q1', name: 'Lemon orzo', is_new: true, start_by: '2026-10-09T14:00:00-04:00' } })
+    await act(() => result.current.plan.refetch())
+    await act(async () => friday.send(errorResponse(409, 'dinner_not_plannable')))
+
+    await waitFor(() => expect(queryClient.isMutating()).toBe(0))
+    expect(plan().days[4]).toEqual({ date: '2026-10-09', dinner: ORZO.dinner, is_new: true, start_by: '2026-10-09T14:00:00-04:00' })
+    expect(result.current.swap.failed?.error.message).toBe('dinner_not_plannable message')
+  })
+
+  it('refuses to dismiss a pending swap', async () => {
+    const friday = deferred()
+    stubServer({ [`GET ${PLAN}`]: () => jsonResponse(200, planBody()), [`PUT ${FRIDAY}`]: () => friday.reply })
+    const { result } = await renderSwaps()
+
+    act(() => result.current.swap.mutate(ORZO))
+    await waitFor(() => expect(result.current.swap.pending).toBe(true))
+    expect(() => result.current.swap.dismiss()).toThrow('The week of 2026-10-05 has a swap pending, which cannot be dismissed.')
+    await act(async () => friday.send(jsonResponse(200, planBody())))
+  })
+})

web/src/plan/api.ts

@@ -0,0 +1,276 @@
+import { useMutation, useMutationState, useQuery, useQueryClient } from '@tanstack/react-query'
+import { ApiError, useApi, type ApiRead } from '../api/index.ts'
+import { isRecord } from '../api/errors.ts'
+import { METHODS, oneOf, photoId, type Method } from '../dinners/api.ts'
+import { QUEST_LOG_KEY } from '../discover/api.ts'
+
+export const PLANS_PATH = '/api/v1/plans'
+
+// planPath is the plan of the week starting on Monday weekStart.
+export function planPath(weekStart: string): string {
+  return `${PLANS_PATH}/${encodeURIComponent(weekStart)}`
+}
+
+// planKey is the query of the plan of the week starting on weekStart.
+export function planKey(weekStart: string) {
+  return ['plans', weekStart] as const
+}
+
+export const PLAN_STATUSES = ['draft', 'synced', 'changed'] as const
+
+// PlanStatus is draft until Push to Calendar syncs the plan; an edit of a
+// synced plan makes it changed.
+export type PlanStatus = (typeof PLAN_STATUSES)[number]
+
+// PlanDinner is a planned dinner: photo_id is its stored photo's id, from
+// photo, minutes its minutes from prep to table and method how it is
+// cooked, each when known.
+export type PlanDinner = { id: string; name: string; photo_id: string | undefined; minutes: number | null; method: Method | null }
+
+// PlanDay is one day of a plan: its household-local date, the dinner
+// planned, whether that dinner is a Quest-log pick, and, for a crock-pot
+// dinner of known minutes, the instant it must start by.
+export type PlanDay = {
+  date: string
+  dinner: PlanDinner
+  is_new: boolean
+  start_by: string | null
+}
+
+// Plan is GET /api/v1/plans/{weekStart}: the week's seven days, Monday to
+// Sunday, the AI's note on the draft, if any, and when it was last pushed to
+// Google Calendar, if ever. cached says the service worker answered from its
+// cache: the server may have changed the plan since.
+export type Plan = {
+  id: string
+  week_start: string
+  status: PlanStatus
+  ai_note: string | null
+  calendar_synced_at: Date | null
+  days: PlanDay[]
+  cached: boolean
+}
+
+// DRAFT_JOB_KIND is the kind of the job drafting a week's plan.
+export const DRAFT_JOB_KIND = 'draft_week'
+
+// DraftResult is the draft_week job's result: the week drafted and its plan.
+export type DraftResult = { week_start: string; plan_id: string }
+
+function parseDay(where: string, body: unknown): PlanDay {
+  if (
+    !isRecord(body) ||
+    typeof body.date !== 'string' ||
+    !isRecord(body.dinner) ||
+    typeof body.dinner.id !== 'string' ||
+    typeof body.dinner.name !== 'string' ||
+    (body.dinner.minutes !== null && !Number.isInteger(body.dinner.minutes)) ||
+    typeof body.is_new !== 'boolean' ||
+    (body.start_by !== null && typeof body.start_by !== 'string')
+  ) {
+    throw new Error(`${where}: response has a day that is not a plan day`)
+  }
+  const dinner: PlanDinner = {
+    id: body.dinner.id,
+    name: body.dinner.name,
+    photo_id: photoId(where, body.dinner.photo),
+    minutes: body.dinner.minutes as number | null,
+    method: body.dinner.method === null ? null : oneOf(where, 'method', METHODS, body.dinner.method),
+  }
+  return { date: body.date, dinner, is_new: body.is_new, start_by: body.start_by }
+}
+
+// syncedAt reads calendar_synced_at, an RFC 3339 instant or null.
+function syncedAt(where: string, value: unknown): Date | null {
+  if (value === null) return null
+  const at = typeof value === 'string' ? new Date(value) : null
+  if (at === null || Number.isNaN(at.getTime())) {
+    throw new Error(`${where}: calendar_synced_at ${JSON.stringify(value)} is not an instant`)
+  }
+  return at
+}
+
+function parsePlan(where: string, weekStart: string, body: unknown, cached: boolean): Plan {
+  if (
+    !isRecord(body) ||
+    typeof body.id !== 'string' ||
+    body.week_start !== weekStart ||
+    (body.ai_note !== null && typeof body.ai_note !== 'string') ||
+    !Array.isArray(body.days) ||
+    body.days.length !== 7
+  ) {
+    throw new Error(`${where}: response is not the plan of the week of ${weekStart}`)
+  }
+  return {
+    id: body.id,
+    week_start: weekStart,
+    status: oneOf(where, 'status', PLAN_STATUSES, body.status),
+    ai_note: body.ai_note,
+    calendar_synced_at: syncedAt(where, body.calendar_synced_at),
+    days: body.days.map((day) => parseDay(where, day)),
+    cached,
+  }
+}
+
+// parseDraftResult checks a draft_week job's result, which useJob passes on
+// unread, is the draft of the week starting on weekStart.
+export function parseDraftResult(where: string, weekStart: string, body: unknown): DraftResult {
+  if (!isRecord(body) || body.week_start !== weekStart || typeof body.plan_id !== 'string') {
+    throw new Error(`${where}: result is not the draft of the week of ${weekStart}`)
+  }
+  return { week_start: weekStart, plan_id: body.plan_id }
+}
+
+// usePlan is the plan of the week starting on Monday weekStart (GET
+// /api/v1/plans/{weekStart}), or null when the week has none (404).
+export function usePlan(weekStart: string) {
+  const { apiRead } = useApi()
+  return useQuery({
+    queryKey: planKey(weekStart),
+    queryFn: async (): Promise<Plan | null> => {
+      const path = planPath(weekStart)
+      let read: ApiRead<unknown>
+      try {
+        read = await apiRead<unknown>(path)
+      } catch (error) {
+        if (error instanceof ApiError && error.status === 404) return null
+        throw error
+      }
+      return parsePlan(`GET ${path}`, weekStart, read.body, read.cached)
+    },
+  })
+}
+
+// useStartDraft asks the AI to draft the week starting on weekStart (POST
+// /api/v1/plans/{weekStart}/draft) and resolves with the id of the
+// draft_week job, which the server answers with the draft already running
+// when there is one. Drafting over a plan pushed to Calendar (synced or
+// changed) needs confirm.
+export function useStartDraft() {
+  const { apiFetch } = useApi()
+  return useMutation({
+    mutationFn: async ({ weekStart, confirm }: { weekStart: string; confirm: boolean }): Promise<string> => {
+      const path = `${planPath(weekStart)}/draft`
+      const body = await apiFetch<unknown>(path, { method: 'POST', body: confirm ? { confirm: true } : {} })
+      if (!isRecord(body) || typeof body.jobId !== 'string') throw new Error(`POST ${path}: response has no jobId`)
+      return body.jobId
+    },
+  })
+}
+
+// Swap is one day's swap: the day, and the dinner chosen for it with whether
+// it was chosen from the Quest log.
+export type Swap = { date: string; dinner: PlanDinner; fromQuestLog: boolean }
+
+// sameDay says whether two plan days are the same in every field.
+function sameDay(a: PlanDay, b: PlanDay): boolean {
+  return (
+    a.date === b.date &&
+    a.dinner.id === b.dinner.id &&
+    a.dinner.name === b.dinner.name &&
+    a.dinner.photo_id === b.dinner.photo_id &&
+    a.dinner.minutes === b.dinner.minutes &&
+    a.dinner.method === b.dinner.method &&
+    a.is_new === b.is_new &&
+    a.start_by === b.start_by
+  )
+}
+
+// swapKey keys the swaps of the week starting on weekStart in the mutation
+// cache, where they outlive the Draft board that sent them.
+function swapKey(weekStart: string) {
+  return ['plans', weekStart, 'swap'] as const
+}
+
+// SwapDay is the swaps of one week, as the mutation cache holds them:
+// whether one is pending, and the failure of the latest, if it failed.
+export type SwapDay = {
+  pending: boolean
+  failed: { swap: Swap; error: Error } | null
+  mutate: (chosen: Swap) => void
+  dismiss: () => void
+}
+
+// useSwapDay swaps the dinner of one day of the week starting on weekStart
+// (PUT /api/v1/plans/{weekStart}/days/{date}). The day shows the dinner at
+// once, NEW when it came from the Quest log, with no start-by time until the
+// server answers with the plan as swapped, which then replaces it. A refused
+// swap puts the day back as it was, unless it has changed again meanwhile.
+// However the swap ends, the Quest log is read again: the server leaves a
+// dinner on the plan out of it.
+//
+// The week's swaps live in the mutation cache, not in the component, so
+// leaving the week and coming back keeps them: pending and failed are read
+// from there. Only the latest swap of the week speaks for it: the plan an
+// earlier one is answered with is not written over a later one, and its
+// failure is not the week's. dismiss leaves settled swaps behind; it is
+// refused while one is pending, so a later swap is always in the cache for
+// an earlier, pending one to see.
+export function useSwapDay(weekStart: string): SwapDay {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  const key = planKey(weekStart)
+  const mutationKey = swapKey(weekStart)
+  const mutations = queryClient.getMutationCache()
+  // The week's swaps, in the order sent.
+  const swaps = useMutationState({
+    filters: { mutationKey },
+    select: (mutation) => ({ status: mutation.state.status, swap: mutation.state.variables as Swap, error: mutation.state.error }),
+  })
+  const latest = swaps.at(-1)
+
+  function mutate(chosen: Swap) {
+    // isLatest says whether no swap of the week was sent after this one.
+    const isLatest = () => mutations.findAll({ mutationKey }).every((other) => other.mutationId <= mutation.mutationId)
+    const mutation = mutations.build<Plan, Error, Swap, { previous: PlanDay; swapped: PlanDay }>(queryClient, {
+      mutationKey,
+      // Kept until dismissed: a later swap must stay in the cache while an
+      // earlier one is pending.
+      gcTime: Infinity,
+      mutationFn: async ({ date, dinner }) => {
+        const path = `${planPath(weekStart)}/days/${encodeURIComponent(date)}`
+        const body = await apiFetch<unknown>(path, { method: 'PUT', body: { dinner_id: dinner.id } })
+        return parsePlan(`PUT ${path}`, weekStart, body, false)
+      },
+      onMutate: async ({ date, dinner, fromQuestLog }) => {
+        await queryClient.cancelQueries({ queryKey: key })
+        const plan = queryClient.getQueryData<Plan | null>(key)
+        const previous = plan?.days.find((day) => day.date === date)
+        if (!plan || previous === undefined) throw new Error(`The week of ${weekStart} has no plan day ${date} to swap.`)
+        const swapped: PlanDay = { date, dinner, is_new: fromQuestLog, start_by: null }
+        queryClient.setQueryData<Plan>(key, { ...plan, days: plan.days.map((day) => (day.date === date ? swapped : day)) })
+        return { previous, swapped }
+      },
+      onSuccess: (plan) => {
+        if (isLatest()) queryClient.setQueryData<Plan>(key, plan)
+      },
+      // The day goes back only while it is still, field for field, the day
+      // this swap wrote: a later swap or plan read that replaced it is left
+      // alone.
+      onError: (_error, _swap, context) => {
+        if (context === undefined) return
+        queryClient.setQueryData<Plan | null>(key, (plan) =>
+          plan && { ...plan, days: plan.days.map((day) => (sameDay(day, context.swapped) ? context.previous : day)) },
+        )
+      },
+      onSettled: () => queryClient.invalidateQueries({ queryKey: QUEST_LOG_KEY }),
+    })
+    // A failure is the mutation's state, which failed reports.
+    mutation.execute(chosen).catch(() => undefined)
+  }
+
+  function dismiss() {
+    const week = mutations.findAll({ mutationKey })
+    if (week.some((mutation) => mutation.state.status === 'pending')) {
+      throw new Error(`The week of ${weekStart} has a swap pending, which cannot be dismissed.`)
+    }
+    for (const mutation of week) mutations.remove(mutation)
+  }
+
+  return {
+    pending: swaps.some((swap) => swap.status === 'pending'),
+    failed: latest?.status === 'error' ? { swap: latest.swap, error: latest.error! } : null,
+    mutate,
+    dismiss,
+  }
+}