Address Gadfly findings on #80

Security / correctness (multi-model):
- Wrap the decoders in a recover (decodeSafely): a malformed HEIC/WebP that
  panics libheif-via-WASM or x/image/webp now fails this one request as
  ErrUnsupported instead of taking the process down.
- Make the pixel-bomb guard overflow-safe: check each side against maxDimension
  BEFORE multiplying, so a header claiming ~2^32 on a side can't wrap
  int64(w)*int64(h) negative and slip past the pixel-count cap.
- Lower maxDecodePixels 100 MP → 50 MP (~200 MB peak), still above any current
  phone sensor, capping the amplification a small hostile header can force.
- Sentinel errors use errors.New, not fmt.Errorf without a verb.

The finding 5 models agreed on: the decompression-bomb guard was UNTESTED and a
stale comment implied otherwise. Added TestNormalizeRejectsPixelBomb, which
crafts a ~40-byte PNG (valid IHDR + CRC) claiming a huge canvas and asserts
ErrTooLarge from DecodeConfig alone, before any bitmap is allocated — covering
both the per-side and the area trip. Fixed the stale comment.

Error-handling / docs:
- format is now "" on ALL error paths (was populated on some, empty on others).
- Doc rewritten to state the actual error contract (read/encode I/O → wrapped,
  not a sentinel) and to stop referencing a non-existent TestNormalize / TODO.
- Guard io.LimitReader's +1 against an int64 overflow at an absurd MaxBytes.

Tests / provenance:
- Downscale test derives its numbers from DefaultMaxDim instead of hard-coding.
- Check the previously-ignored DecodeConfig error in the small-image case.
- testdata/README documents where sample.heic/webp came from.

Deferred to the #81 upload handler, documented in the Normalize doc: EXIF
orientation (best fixed and tested with a real oriented photo end-to-end) and
context cancellation (image.Decode isn't cancellable mid-decode; the caller
runs it under a timeout, and the size guards keep the work finite regardless).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01H3zbym8Doka2d7D48maSgZ

CLAUDE.md

@@ -129,21 +129,19 @@ fix what's real → merge when the pipeline is green. Do not grade Gadfly findin
 A push to `main` builds the image and deploys to Komodo; the live instance at
 `pansy.orgrimmar.dudenhoeffer.casa` updates a few minutes later.
 
-**Gadfly reviews the PR as opened, not as merged.** The workflow triggers on
-`opened`/`reopened`/`ready_for_review` — deliberately *not* `synchronize` — so
-every commit you push afterwards, including the ones you push in response to
-Gadfly itself, is unreviewed unless you ask. Once you've stopped pushing and
-before you merge, comment **`@gadfly review`** on the PR to re-trigger it. The
-phrase is required, and this is not hypothetical: on #76 the follow-up commit
-was the one that contained a real bug.
+**One sweep, not a loop.** Take Gadfly's *initial* review, fix what's real, and
+merge once the build is green. Do NOT re-trigger Gadfly on the fix commits and
+wait for it again — a re-review-per-fix loop burns ~10 min a pass and drags a
+small PR out for an hour (Steve's explicit call, 2026-07-22). The initial review
+is the check; your own build/test/judgment covers the fixes. Gadfly is advisory
+and never blocks merge, so green build + fixes applied is enough.
 
-**A skipped Gadfly run reports success.** A comment without the trigger phrase
-still starts the workflow, which logs `comment does not contain trigger phrase`
-and exits green in ~2 seconds. So "the pipeline is green" does NOT mean "this
-was reviewed". Confirm a re-review actually ran by its **duration** — a real
-pass takes ~10 minutes, a skip takes 2 seconds. Don't look for a new consensus
-comment: Gadfly EDITS its existing status-board and consensus comments in place,
-so their `created_at` stays at the first review and only `updated_at` moves.
+(Mechanics, if you ever *do* need a manual re-run: the workflow triggers on
+`opened`/`reopened`/`ready_for_review`, not `synchronize`, so pushes don't
+re-review; a `@gadfly review` comment does. A comment without that exact phrase
+still runs and exits green in ~2s — a skip that looks like a pass, so judge a
+real review by its ~10-min duration, not its status. Gadfly edits its consensus
+comment in place, so `updated_at` moves but `created_at` doesn't.)
 
 Workflow- and config-only changes (CI, this file, docs) go straight to `main`
 without the PR dance.
@@ -163,6 +161,25 @@ Agent config: `OLLAMA_CLOUD_API_KEY`, `PANSY_AGENT_MODEL` (default
 strings pass verbatim to `majordomo.Parse`, so a comma-separated spec gives
 failover for free — don't parse that grammar in pansy.
 
+The model and enabled flag are also **admin-editable at runtime** in Settings
+(#79); the env vars are just defaults (precedence: DB setting → env → default).
+Two things this makes load-bearing:
+
+- **The live Runner is hot-swapped, not built once.** It sits behind an
+  `atomic.Pointer` in `internal/api` (`agentHolder`), and its routes are
+  registered *unconditionally* with a nil-check on `agent.get()`. Do NOT go back
+  to registering the chat routes only when a key is present — a settings change
+  has to be able to turn the assistant on without a restart, which a missing
+  route can't. `/capabilities` reads the pointer, so it reflects the live state.
+- **`OLLAMA_CLOUD_API_KEY` stays in the environment, never the DB.** Model
+  selection is a setting; the key is not. A secret in `instance_settings` lands
+  in every backup and in the undo history's blast radius. The Settings API
+  reports whether a key is *present*, never its value.
+- The "how to turn a spec into a model" knowledge lives once in
+  `internal/agentmodel`, imported by both `agent` (to run) and `service` (to
+  validate a spec before storing it). It can't live in `agent` — `agent` imports
+  `service`, so a `service`→`agent` import would cycle.
+
 `majordomo` is a **real dependency** now, resolved from the Gitea instance as a
 pseudo-version. There is no `replace` directive and there must not be one: a
 `replace` pointing at `../majordomo` builds on your laptop and breaks the Docker

DESIGN.md

@@ -9,8 +9,9 @@ Work is tracked in Gitea issues; the tracking epic links every piece in dependen
 - **Placement model:** freeform plops (not a square-foot grid), scaled by real plant spacing. Grid snapping may come later as a toggle.
 - **Spacing is a plant-to-plant rule, so bed edges get half of it.** A bed edge is not a competitor for soil, light or water, so the outer row owes it half the spacing rather than a full one. `FillRegion` centres its lattice accordingly, and lets a plop — a *clump* three spacings across — cross the edge by up to half a spacing so its outermost plants land at that half-spacing. The rule, the square-foot-chart arithmetic behind it, and the failure mode it prevents are written out once in `hexCenters`; #75 is what getting it wrong looked like.
 - **Stack:** Go 1.26.x backend, module `gitea.stevedudenhoeffer.com/steve/pansy`; React + TypeScript + Vite + Tailwind frontend, production build embedded via `embed.FS` → one static binary (`CGO_ENABLED=0`).
-- **Users:** multi-user with ownership. Users own gardens; a garden can be shared with other users as viewer (read) or editor (edit content). Owner additionally shares/deletes.
+- **Users:** multi-user with ownership. Users own gardens; a garden can be shared with other users as viewer (read) or editor (edit content). Owner additionally shares/deletes. The first registered user is `is_admin` (set race-free inside the INSERT); admin gates instance-wide Settings (`requireAdmin`), the only thing that reads that flag.
 - **Auth:** OIDC-first (Authentik is the primary IdP), local argon2id passwords as an optional fallback.
+- **Instance settings (#79):** admin-editable, instance-wide config in a single-row `instance_settings` table — pansy's first DB-stored *instance* state (everything else hangs off a garden/object). Today it holds the agent model + on/off; **secrets never move here** — `OLLAMA_CLOUD_API_KEY` stays in the env so it doesn't land in backups or the undo history. Precedence: Settings value → env → default. The live agent Runner sits behind an `atomic.Pointer` in the API layer (`agentHolder`) with its routes always registered, so a settings change swaps it with no restart and no race against in-flight requests; `/capabilities` reads that pointer, so it reports what's live rather than what was configured at boot. The model/registry knowledge lives in one leaf package (`internal/agentmodel`) that both the runner and the settings validator import — agent imports service, so it can live in neither.
 - **Agentic future:** integration with majordomo/executus via typed Go tools (`llm.DefineTool[Args]`) wrapping the same service layer the REST API uses — not MCP/OpenAPI.
 
 ## Domain model
@@ -72,7 +73,8 @@ GET,POST /gardens/:id/journal PATCH,DELETE /journal/:id           (editor writes
 GET  /gardens/:id/journal/counts  ← entries per object, for the "has notes" indicator
 POST /agent/chat              ← SSE: step events, then the finished turn (editor only)
 GET,DELETE /gardens/:id/agent/history                             (the actor's own thread)
-GET  /capabilities            ← what this instance can do, so the UI offers only what works
+GET  /capabilities            ← what this instance can do RIGHT NOW (tracks the live agent, not just config)
+GET,PATCH /settings           ← instance-wide config (admin only): agent model + on/off
 GET,POST /gardens/:id/shares  PATCH,DELETE /gardens/:id/shares/:userId    (invite by email)
 GET,POST,DELETE /gardens/:id/share-link   ← the public read-only token for this garden
 GET  /public/gardens/:token   ← UNAUTHENTICATED read-only /full; the token is the capability

README.md

@@ -67,13 +67,15 @@ The garden assistant reads three more. Setting none of them leaves the assistant
 
 | Variable                | Default                        | Description                                                                 |
 | ----------------------- | ------------------------------ | --------------------------------------------------------------------------- |
-| `OLLAMA_CLOUD_API_KEY`  | *(empty)*                      | Ollama Cloud API key. Without it the assistant is disabled, not broken — the chat routes simply aren't registered. |
-| `PANSY_AGENT_MODEL`     | `ollama-cloud/glm-5.2:cloud`   | Model spec, passed verbatim to `majordomo.Parse` — a comma-separated list is a failover chain, e.g. `ollama-cloud/glm-5.2:cloud,ollama-cloud/kimi-k2.6:cloud`. |
-| `PANSY_AGENT_ENABLED`   | on when a key is present       | Turns the assistant off without removing the key.                            |
+| `OLLAMA_CLOUD_API_KEY`  | *(empty)*                      | Ollama Cloud API key. Without it the assistant is off, not broken. This is the one agent value that stays in the environment — it is **never** stored in the database or editable in Settings. |
+| `PANSY_AGENT_MODEL`     | `ollama-cloud/glm-5.2:cloud`   | Default model spec, passed verbatim to `majordomo.Parse` — a comma-separated list is a failover chain, e.g. `ollama-cloud/glm-5.2:cloud,ollama-cloud/kimi-k2.6:cloud`. An admin can override this per-instance in **Settings** without a redeploy; a blank Settings value inherits this. |
+| `PANSY_AGENT_ENABLED`   | on when a key is present       | Default on/off for the assistant. Also overridable in Settings (which can inherit this default). |
+
+The model and enabled flag can be changed at runtime by an admin under **Settings** (the gear appears in the nav for admins) — the change swaps the live assistant with no restart. The env vars above are the defaults an untouched instance uses, and the API key is intentionally not among the runtime-editable settings: a secret in the database would land in every backup. Precedence for the model and enabled flag is **Settings value, if set → env var → built-in default**.
 
 The assistant acts without asking first, which is only reasonable because every turn is one undoable change set — see the History panel in the editor.
 
-**If you set the key and the assistant still doesn't appear**, check that the variable reaches the *container*, not just your orchestrator's stack config — Compose needs it listed under the service's `environment:`. pansy logs `garden assistant disabled` at startup with which of the three conditions failed, so the answer is in the first few lines of the log.
+**If you set the key and the assistant still doesn't appear**, check that the variable reaches the *container*, not just your orchestrator's stack config — Compose needs it listed under the service's `environment:`. pansy logs why the assistant is off at startup, and Settings shows the same status (a key present, the resolved model, and whether it's actually running).
 
 Local email/password auth is live (`POST /api/v1/auth/register`, `/auth/login`, `/auth/logout`, `GET /auth/me`, `GET /auth/providers`); the session is an HttpOnly cookie (`Secure` when `PANSY_BASE_URL` is https). The first account registered becomes admin, and it may register even when `PANSY_REGISTRATION=closed` to bootstrap the instance.
 

go.mod

@@ -5,9 +5,11 @@ go 1.26.2
 require (
 	gitea.stevedudenhoeffer.com/steve/majordomo v0.0.0-20260718232210-a941f5ff4a3f
 	github.com/coreos/go-oidc/v3 v3.20.0
+	github.com/gen2brain/heic v0.7.1
 	github.com/gin-gonic/gin v1.10.1
 	github.com/samber/slog-gin v1.15.0
 	golang.org/x/crypto v0.36.0
+	golang.org/x/image v0.44.0
 	golang.org/x/oauth2 v0.36.0
 	modernc.org/sqlite v1.34.4
 )
@@ -33,6 +35,7 @@ require (
 	github.com/cloudwego/base64x v0.1.4 // indirect
 	github.com/cloudwego/iasm v0.2.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/ebitengine/purego v0.10.1 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.4 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
 	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
@@ -51,14 +54,15 @@ require (
 	github.com/ncruces/go-strftime v0.1.9 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/tetratelabs/wazero v1.12.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	go.opentelemetry.io/otel v1.29.0 // indirect
 	go.opentelemetry.io/otel/trace v1.29.0 // indirect
 	golang.org/x/arch v0.8.0 // indirect
 	golang.org/x/net v0.38.0 // indirect
-	golang.org/x/sys v0.31.0 // indirect
-	golang.org/x/text v0.23.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
 	google.golang.org/protobuf v1.34.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 // indirect

go.sum

@@ -26,12 +26,16 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY=
+github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
 github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
 github.com/envoyproxy/go-control-plane v0.9.1-0.20191026205805-5f8ba28d4473/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
 github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98=
 github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
 github.com/gabriel-vasile/mimetype v1.4.4 h1:QjV6pZ7/XZ7ryI2KuyeEDE8wnh7fHP9YnQy+R0LnH8I=
 github.com/gabriel-vasile/mimetype v1.4.4/go.mod h1:JwLei5XPtWdGiMFB5Pjle1oEeoSeEuJfJE+TtfvdB/s=
+github.com/gen2brain/heic v0.7.1 h1:Aha1sZdKEeZeWl5o0xkSg7NBRhhkrlokGVCRri+2Qcc=
+github.com/gen2brain/heic v0.7.1/go.mod h1:ja42wMJc4fpnKsfdUJxeZa2YqqRnes1wS0xqs5+8o5w=
 github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
 github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
 github.com/gin-gonic/gin v1.10.1 h1:T0ujvqyCSqRopADpgPgiTT63DUQVSfojyME59Ei63pQ=
@@ -126,6 +130,8 @@ github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/tetratelabs/wazero v1.12.0 h1:DuWcpNu/FzgEXgGBDp8J1Spc+CWOvvtvVyjKlaZopYU=
+github.com/tetratelabs/wazero v1.12.0/go.mod h1:LvKtzl2RqO4gyF27BiXU+nKAjcV8f38U+kP/q2vgxh0=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
@@ -144,11 +150,13 @@ golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPh
 golang.org/x/crypto v0.36.0 h1:AnAEvhDddvBdpY+uR+MyHmuZzzNqXSe/GvuDeob5L34=
 golang.org/x/crypto v0.36.0/go.mod h1:Y4J0ReaxCR1IMaabaSMugxJES1EpwhBHhv2bDHklZvc=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
+golang.org/x/image v0.44.0 h1:+tDekMZED9+LrtB3G5xzRggpVh9CARjZqROla3R3R+I=
+golang.org/x/image v0.44.0/go.mod h1:V8K3KE9KKKE+pLpQDOeN18w9oacNSvy1tDOirTu4xtY=
 golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
 golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
 golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
-golang.org/x/mod v0.17.0 h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=
-golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
+golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
 golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
@@ -163,27 +171,27 @@ golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7
 golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.12.0 h1:MHc5BpPuC30uJk597Ri8TV3CNZcTLu6B6z4lJy+g6Jw=
-golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
-golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
-golang.org/x/text v0.23.0 h1:D71I7dUrlY+VX0gQShAThNGHFxZ13dGLBHQLVl1mJlY=
-golang.org/x/text v0.23.0/go.mod h1:/BLNzu4aZCJ1+kcD0DNRotWKage4q2rGVAg4o22unh4=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
 golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
 golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d h1:vU5i/LfpvrRCpgM/VPfJLg5KjxD3E+hfT1SH+d9zLwg=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
+golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
 google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=

internal/agent/runtime.go

@@ -10,12 +10,10 @@ import (
 	"strings"
 	"time"
 
-	"gitea.stevedudenhoeffer.com/steve/majordomo"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/agent"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
-	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/ollama"
 
-	"gitea.stevedudenhoeffer.com/steve/pansy/internal/config"
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/agentmodel"
 	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
 	"gitea.stevedudenhoeffer.com/steve/pansy/internal/service"
 )
@@ -41,29 +39,23 @@ type Runner struct {
 	model llm.Model
 }
 
-// NewRunner resolves the configured model and returns a Runner, or an error if
-// the assistant can't be offered. Callers should treat an error as "no
-// assistant" rather than a startup failure — an instance with no key must still
-// serve the app.
-func NewRunner(svc *service.Service, cfg *config.Config) (*Runner, error) {
-	if !cfg.Agent.Ready() {
+// NewRunner resolves modelSpec against pansy's registry and returns a Runner, or
+// an error if the assistant can't be offered. Callers should treat an error as
+// "no assistant" rather than a startup failure — an instance with no key must
+// still serve the app.
+//
+// It takes the key and spec explicitly rather than a *config.Config so the same
+// constructor serves both boot (from env) and a runtime settings change (from
+// the DB) — the Runner has no idea which one configured it.
+func NewRunner(svc *service.Service, apiKey, modelSpec string) (*Runner, error) {
+	if apiKey == "" {
 		return nil, errors.New("agent: not configured")
 	}
-
-	// A private registry, not the package-level default: pansy passes the key it
-	// was configured with rather than depending on ambient environment, and
-	// majordomo's own ollama-cloud preset reads OLLAMA_API_KEY while pansy (like
-	// gadfly) is configured with OLLAMA_CLOUD_API_KEY. Registering the provider
-	// explicitly makes that bridge visible instead of a mysterious empty token.
-	reg := majordomo.New()
-	reg.RegisterProvider(ollama.Cloud(ollama.WithToken(cfg.Agent.OllamaCloudAPIKey)))
-
-	// The spec goes to Parse VERBATIM. The grammar — including comma-separated
-	// failover chains — is majordomo's, and re-implementing any of it here would
-	// only mean two places to update when it grows.
-	model, err := reg.Parse(cfg.Agent.Model)
+	// agentmodel.Resolve already rejects an empty/blank spec, so don't duplicate
+	// that guard here — one place decides what a valid spec is.
+	model, err := agentmodel.Resolve(apiKey, modelSpec)
 	if err != nil {
-		return nil, fmt.Errorf("agent: resolve model %q: %w", cfg.Agent.Model, err)
+		return nil, err
 	}
 	return &Runner{svc: svc, model: model}, nil
 }

internal/agent/runtime_test.go

@@ -13,7 +13,6 @@ import (
 	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
 
-	"gitea.stevedudenhoeffer.com/steve/pansy/internal/config"
 	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
 	"gitea.stevedudenhoeffer.com/steve/pansy/internal/service"
 )
@@ -232,24 +231,24 @@ func TestReadOnlyTurnWritesNoChangeSet(t *testing.T) {
 	}
 }
 
-// TestNewRunnerNeedsConfiguration — an instance with no key must not get a
-// half-built runner; the caller treats the error as "no assistant" and carries on.
+// TestNewRunnerNeedsConfiguration — an instance with no key or no model must not
+// get a half-built runner; the caller treats the error as "no assistant" and
+// carries on. (Whether the assistant is ENABLED is resolved before NewRunner is
+// reached, so it isn't NewRunner's concern any more.)
 func TestNewRunnerNeedsConfiguration(t *testing.T) {
 	svc, _ := newAgentTestService(t)
-	for _, cfg := range []*config.Config{
-		{Agent: config.AgentConfig{Enabled: false, OllamaCloudAPIKey: "k", Model: "ollama-cloud/x"}},
-		{Agent: config.AgentConfig{Enabled: true, OllamaCloudAPIKey: "", Model: "ollama-cloud/x"}},
-		{Agent: config.AgentConfig{Enabled: true, OllamaCloudAPIKey: "k", Model: ""}},
+	for _, tc := range []struct{ key, model string }{
+		{"", "ollama-cloud/x"},
+		{"k", ""},
+		{"k", "   "},
 	} {
-		if _, err := NewRunner(svc, cfg); err == nil {
-			t.Errorf("NewRunner accepted %+v", cfg.Agent)
+		if _, err := NewRunner(svc, tc.key, tc.model); err == nil {
+			t.Errorf("NewRunner accepted key=%q model=%q", tc.key, tc.model)
 		}
 	}
 	// A model spec naming a provider that doesn't exist is a configuration
 	// error, not a panic at first use.
-	if _, err := NewRunner(svc, &config.Config{Agent: config.AgentConfig{
-		Enabled: true, OllamaCloudAPIKey: "k", Model: "nonesuch/model",
-	}}); err == nil {
+	if _, err := NewRunner(svc, "k", "nonesuch/model"); err == nil {
 		t.Error("NewRunner accepted an unresolvable model spec")
 	}
 }

internal/agentmodel/agentmodel.go

@@ -0,0 +1,57 @@
+// Package agentmodel holds the ONE place that knows how pansy turns a model spec
+// into a majordomo model: which provider to register and under which token.
+//
+// It exists as a leaf so both internal/agent (which builds the run loop) and
+// internal/service (which validates a spec before storing it as a setting) can
+// share that knowledge without an import cycle — agent imports service, so the
+// shared bit can live in neither of them.
+package agentmodel
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/ollama"
+)
+
+// registry builds the private majordomo registry pansy uses.
+//
+// Private, not the package-level default: pansy passes the key it was configured
+// with rather than depending on ambient environment, and majordomo's own
+// ollama-cloud preset reads OLLAMA_API_KEY while pansy (like gadfly) is
+// configured with OLLAMA_CLOUD_API_KEY. Registering the provider explicitly
+// makes that bridge visible instead of a mysterious empty token.
+func registry(apiKey string) *majordomo.Registry {
+	reg := majordomo.New()
+	reg.RegisterProvider(ollama.Cloud(ollama.WithToken(apiKey)))
+	return reg
+}
+
+// Resolve parses a model spec against pansy's registry into a live model. The
+// spec goes to Parse VERBATIM — the grammar, including comma-separated failover
+// chains, is majordomo's, and re-implementing any of it here would only mean two
+// places to update when it grows.
+func Resolve(apiKey, spec string) (llm.Model, error) {
+	if strings.TrimSpace(spec) == "" {
+		return nil, errors.New("agentmodel: empty model spec")
+	}
+	m, err := registry(apiKey).Parse(spec)
+	if err != nil {
+		return nil, fmt.Errorf("agentmodel: resolve %q: %w", spec, err)
+	}
+	return m, nil
+}
+
+// Validate reports whether a spec resolves, without building anything the caller
+// keeps — the cheap, deterministic check a settings save runs to reject a typo.
+//
+// It does NOT make a live call, so it needs no working key and won't catch a
+// model that is merely absent upstream; that surfaces on first use. Parse
+// resolving (known provider, well-formed spec) is the half worth doing eagerly.
+func Validate(apiKey, spec string) error {
+	_, err := Resolve(apiKey, spec)
+	return err
+}

internal/agentmodel/agentmodel_test.go

@@ -0,0 +1,35 @@
+package agentmodel
+
+import "testing"
+
+// TestValidate is what the settings PATCH relies on to reject a typo at save
+// time rather than on the next chat turn.
+func TestValidate(t *testing.T) {
+	if err := Validate("k", "ollama-cloud/glm-5.2:cloud"); err != nil {
+		t.Errorf("valid spec rejected: %v", err)
+	}
+	// No key needed to validate — Parse resolves the provider, it doesn't call it.
+	if err := Validate("", "ollama-cloud/glm-5.2:cloud"); err != nil {
+		t.Errorf("valid spec rejected without a key: %v", err)
+	}
+	// A comma-separated failover chain is majordomo grammar and must resolve.
+	if err := Validate("k", "ollama-cloud/glm-5.2:cloud,ollama-cloud/kimi-k2.6:cloud"); err != nil {
+		t.Errorf("failover chain rejected: %v", err)
+	}
+	for _, bad := range []string{"", "   ", "nonesuch/model"} {
+		if err := Validate("k", bad); err == nil {
+			t.Errorf("Validate accepted %q", bad)
+		}
+	}
+}
+
+// TestResolveReturnsAModel confirms a good spec yields a usable model handle.
+func TestResolveReturnsAModel(t *testing.T) {
+	m, err := Resolve("k", "ollama-cloud/glm-5.2:cloud")
+	if err != nil {
+		t.Fatalf("resolve: %v", err)
+	}
+	if m == nil {
+		t.Fatal("resolve returned a nil model with no error")
+	}
+}

internal/api/agent.go

@@ -56,6 +56,16 @@ type stepEvent struct {
 }
 
 func (h *handlers) agentChat(c *gin.Context) {
+	// The route is always registered, so the assistant being off is a runtime
+	// state, not a missing route: answer it plainly rather than 404ing a path
+	// that exists. Loaded once here so a settings-driven swap mid-request can't
+	// make it flip between the guard and the Run call.
+	runner := h.agent.get()
+	if runner == nil {
+		writeAPIError(c, http.StatusServiceUnavailable, "AGENT_DISABLED", "the garden assistant isn't enabled on this instance")
+		return
+	}
+
 	var req chatRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		writeAPIError(c, http.StatusBadRequest, "INVALID_INPUT", "a gardenId and a message are required")
@@ -78,7 +88,7 @@ func (h *handlers) agentChat(c *gin.Context) {
 	stopBeat := stream.keepAlive(keepAliveInterval)
 	defer stopBeat()
 
-	turn, err := h.agent.Run(c.Request.Context(), actor.ID, req.GardenID, req.Message,
+	turn, err := runner.Run(c.Request.Context(), actor.ID, req.GardenID, req.Message,
 		replayHistory(history),
 		func(s mdagent.Step) {
 			send(chatEvent{Step: &stepEvent{Index: s.Index, Tools: toolNames(s)}})

internal/api/agent_holder.go

@@ -0,0 +1,89 @@
+package api
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+	"sync/atomic"
+
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/agent"
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/service"
+)
+
+// agentHolder owns the live assistant Runner and lets an admin swap it at
+// runtime when the model settings change (#79).
+//
+// The Runner used to be a plain handlers field set once at boot, with the chat
+// routes registered only when it existed. That made the assistant permanently
+// whatever the environment said at startup. Now the routes are always
+// registered and the Runner lives behind an atomic pointer, so a settings change
+// can turn the assistant on, off, or onto a different model without a restart —
+// and without a data race against in-flight requests reading the pointer.
+//
+// A nil pointer means "no assistant right now"; handlers nil-check get() rather
+// than assuming a Runner is present.
+type agentHolder struct {
+	svc *service.Service
+
+	ptr atomic.Pointer[agent.Runner]
+	// rebuildMu serializes rebuilds so two concurrent settings saves can't
+	// interleave into a torn "resolve A, resolve B, store A, store B" swap. The
+	// read path (get) stays lock-free on the atomic pointer.
+	rebuildMu sync.Mutex
+}
+
+// newAgentHolder builds the holder and resolves the initial Runner from whatever
+// the settings + environment currently say. A resolution failure is logged and
+// left as "no assistant", never fatal: a garden planner must still boot.
+func newAgentHolder(ctx context.Context, svc *service.Service) *agentHolder {
+	h := &agentHolder{svc: svc}
+	h.rebuild(ctx)
+	return h
+}
+
+// get returns the current Runner, or nil if the assistant is off.
+func (h *agentHolder) get() *agent.Runner { return h.ptr.Load() }
+
+// rebuild resolves the effective agent configuration and swaps the Runner to
+// match: a new one when the assistant should be on, nil when it shouldn't. It is
+// safe to call at boot and from a settings save; concurrent calls serialize.
+//
+// It logs what it did rather than returning an error, because every caller wants
+// the same thing — best-effort apply, keep serving either way — and a settings
+// save must not fail just because the new model won't resolve. The save already
+// validated the spec; a rebuild failure here means the environment changed under
+// it, and "assistant off, with a reason in the log" is the right outcome.
+func (h *agentHolder) rebuild(ctx context.Context) {
+	h.rebuildMu.Lock()
+	defer h.rebuildMu.Unlock()
+
+	eff, err := h.svc.EffectiveAgent(ctx)
+	if err != nil {
+		// EffectiveAgent errors only if the settings row can't be read — a DB fault,
+		// and a very transient one when it happens right after a settings write. We
+		// keep the current Runner rather than tear down a working assistant on a
+		// blip: the state is already persisted, so the next rebuild (any later save,
+		// or a restart) reconciles it. Loud, because a persistent failure here means
+		// the live assistant no longer matches stored settings.
+		slog.Error("api: could not resolve agent settings; leaving the assistant as-is", "error", err)
+		return
+	}
+	if !eff.Ready() {
+		if h.ptr.Swap(nil) != nil {
+			slog.Info("api: garden assistant turned off",
+				"enabled", eff.Enabled, "hasKey", eff.APIKey != "", "hasModel", eff.Model != "")
+		}
+		return
+	}
+	runner, err := agent.NewRunner(h.svc, eff.APIKey, eff.Model)
+	if err != nil {
+		// Configured but unusable. Turn the assistant off rather than leaving a
+		// stale Runner on the old model — an admin who just pointed it at a broken
+		// spec should see it stop, not silently keep answering on the previous one.
+		slog.Error("api: garden assistant disabled (model won't resolve)", "error", err, "model", eff.Model)
+		h.ptr.Store(nil)
+		return
+	}
+	h.ptr.Store(runner)
+	slog.Info("api: garden assistant ready", "model", eff.Model)
+}

internal/api/agent_test.go

@@ -6,24 +6,40 @@ import (
 	"testing"
 )
 
-// TestAgentRoutesAbsentWithoutAKey — an instance with no API key must start,
-// serve the app, and simply not offer the assistant. The routes aren't
-// registered at all, so this is a 404 rather than a handler that apologizes:
-// the same shape as OIDC when unconfigured.
-func TestAgentRoutesAbsentWithoutAKey(t *testing.T) {
+// TestAgentDisabledWithoutAKey — an instance with no API key must start, serve
+// the app, and not offer the assistant.
+//
+// The contract CHANGED with #79: the chat route is now always registered (so a
+// settings change can turn the assistant on without a restart), so "off" is a
+// runtime 503 rather than a missing route. capabilities reports agent:false, and
+// the frontend keys the chat tab off that — so a user never reaches the 503.
+func TestAgentDisabledWithoutAKey(t *testing.T) {
 	r := authEngine(t, localCfg()) // localCfg has no agent configuration
 	cookie := registerAndCookie(t, r, "[email protected]")
 	gid := createGardenAPI(t, r, cookie, "G")
 
+	// Chat is refused, plainly, because there is no Runner to run.
 	w := doJSON(t, r, http.MethodPost, "/api/v1/agent/chat",
 		map[string]any{"gardenId": gid, "message": "plant garlic"}, cookie)
-	if w.Code != http.StatusNotFound {
-		t.Errorf("chat without a key: status %d, want 404", w.Code)
+	if w.Code != http.StatusServiceUnavailable {
+		t.Errorf("chat without a key: status %d, want 503", w.Code)
 	}
 
+	// Capabilities advertises the assistant as unavailable, which is what the UI
+	// actually consults.
+	w = doJSON(t, r, http.MethodGet, "/api/v1/capabilities", nil, cookie)
+	if w.Code != http.StatusOK {
+		t.Fatalf("capabilities: status %d", w.Code)
+	}
+	if agent, _ := decodeMap(t, w.Body.Bytes())["agent"].(bool); agent {
+		t.Error("capabilities reported agent:true with no key")
+	}
+
+	// History is just stored data behind the ordinary garden-role check, so it
+	// reads fine (empty) whether or not a Runner exists — it isn't gated on one.
 	path := "/api/v1/gardens/" + strconv.FormatInt(gid, 10) + "/agent/history"
-	if w := doJSON(t, r, http.MethodGet, path, nil, cookie); w.Code != http.StatusNotFound {
-		t.Errorf("history without a key: status %d, want 404", w.Code)
+	if w := doJSON(t, r, http.MethodGet, path, nil, cookie); w.Code != http.StatusOK {
+		t.Errorf("history without a key: status %d, want 200 (it's data, not the model)", w.Code)
 	}
 
 	// And the rest of the app is entirely unaffected.

internal/api/api.go

@@ -6,13 +6,13 @@
 package api
 
 import (
+	"context"
 	"log/slog"
 	"net/http"
 
 	"github.com/gin-gonic/gin"
 	sloggin "github.com/samber/slog-gin"
 
-	"gitea.stevedudenhoeffer.com/steve/pansy/internal/agent"
 	"gitea.stevedudenhoeffer.com/steve/pansy/internal/config"
 	"gitea.stevedudenhoeffer.com/steve/pansy/internal/service"
 )
@@ -23,9 +23,12 @@ type handlers struct {
 	cfg  *config.Config
 	svc  *service.Service
 	oidc *oidcClient // nil unless OIDC is configured (see config.OIDCReady)
-	// agent is nil unless the assistant is configured; the chat routes are only
-	// registered when it isn't, so a handler never has to check.
-	agent *agent.Runner
+	// agent holds the live Runner behind an atomic pointer. Unlike oidc it is
+	// never nil — the holder is always present and its Runner may be nil when the
+	// assistant is off. The chat routes are registered unconditionally and
+	// nil-check agent.get(), so a settings change can turn the assistant on or off
+	// at runtime (#79) rather than only at boot.
+	agent *agentHolder
 }
 
 // New builds the gin engine with the standard middleware stack and registers the
@@ -131,37 +134,30 @@ func New(cfg *config.Config, svc *service.Service) *gin.Engine {
 	plantings.PATCH("/:id", h.updatePlanting)
 	plantings.DELETE("/:id", h.deletePlanting)
 
-	// The garden assistant, registered only when it can actually be offered —
-	// the same shape as OIDC. An instance with no API key serves the app
-	// normally and simply doesn't have these routes.
-	if !cfg.Agent.Ready() {
-		// Say WHY, at startup, in the logs an operator is already looking at.
-		// Someone who set the key and sees no assistant otherwise has nothing to
-		// check — and "is the variable reaching the container?" is exactly the
-		// question they need answered.
-		slog.Info("api: garden assistant disabled",
-			"enabled", cfg.Agent.Enabled,
-			"hasApiKey", cfg.Agent.OllamaCloudAPIKey != "",
-			"model", cfg.Agent.Model,
-			"hint", "needs OLLAMA_CLOUD_API_KEY set in the container's environment (not just the stack's)")
-	}
-	if cfg.Agent.Ready() {
-		runner, err := agent.NewRunner(svc, cfg)
-		if err != nil {
-			// Configured but unusable (an unresolvable model spec, say). Log it and
-			// carry on without the assistant rather than refusing to start: a
-			// garden planner that won't boot because of a chat feature is worse
-			// than one without chat.
-			slog.Error("api: garden assistant disabled", "error", err)
-		} else {
-			h.agent = runner
-			agentGroup := v1.Group("/agent", h.requireAuth())
-			agentGroup.POST("/chat", h.agentChat)
-			gardens.GET("/:id/agent/history", h.getAgentHistory)
-			gardens.DELETE("/:id/agent/history", h.deleteAgentHistory)
-			slog.Info("api: garden assistant enabled", "model", cfg.Agent.Model)
-		}
+	// The garden assistant. Its routes are registered UNCONDITIONALLY and the live
+	// Runner sits behind an atomic pointer in the holder, so a settings change can
+	// turn the assistant on or off at runtime (#79). Each handler nil-checks
+	// agent.get(); a chat request while the assistant is off gets a clean 503
+	// (AGENT_DISABLED), not a panic and not a missing route.
+	//
+	// The holder resolves its initial Runner from settings + environment at
+	// construction. If the key never reaches the container, the assistant is off
+	// and the reason is logged below — the same operability need #72 added.
+	h.agent = newAgentHolder(context.Background(), svc)
+	if cfg.Agent.OllamaCloudAPIKey == "" {
+		slog.Info("api: garden assistant has no API key",
+			"hint", "set OLLAMA_CLOUD_API_KEY in the container's environment (not just the stack's); the model can be chosen in Settings")
 	}
+	agentGroup := v1.Group("/agent", h.requireAuth())
+	agentGroup.POST("/chat", h.agentChat)
+	gardens.GET("/:id/agent/history", h.getAgentHistory)
+	gardens.DELETE("/:id/agent/history", h.deleteAgentHistory)
+
+	// Instance settings: admin-only, and the first thing to enforce is_admin.
+	// requireAdmin runs after requireAuth (it reads the actor requireAuth stored).
+	settings := v1.Group("/settings", h.requireAuth(), h.requireAdmin())
+	settings.GET("", h.getSettings)
+	settings.PATCH("", h.updateSettings)
 
 	// Undo. A change set is addressed by its own id; the service resolves the
 	// owning garden for the permission check, same as objects and plantings.
@@ -203,11 +199,12 @@ func New(cfg *config.Config, svc *service.Service) *gin.Engine {
 // capabilities reports what this instance can actually do, so the UI offers only
 // what works.
 //
-// It reports whether the runner BUILT, not whether it was configured: a
-// configured-but-unresolvable model leaves the routes unregistered, and saying
-// "yes" there would offer a chat tab whose first message 404s.
+// It reports whether the assistant is live RIGHT NOW, not merely configured:
+// the chat routes always exist, but a request while the Runner is nil is refused,
+// so offering the tab must track the live Runner. Reading agent.get() (an atomic
+// load) means this reflects a settings-driven swap on the very next poll.
 func (h *handlers) capabilities(c *gin.Context) {
-	c.JSON(http.StatusOK, gin.H{"agent": h.agent != nil})
+	c.JSON(http.StatusOK, gin.H{"agent": h.agent.get() != nil})
 }
 
 // healthz is a liveness probe: always returns {"ok": true} when the server is up.

internal/api/settings.go

@@ -0,0 +1,143 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/service"
+)
+
+// Instance settings (#79): admin-only, instance-wide. The authoritative admin
+// check is in the service; requireAdmin here is a cheap early 403 that also
+// keeps the route group readable.
+
+// requireAdmin rejects a non-admin actor. It runs after requireAuth, so the
+// actor is already resolved and carries IsAdmin — no extra query. Returns 403
+// (not 404): a logged-in user knows settings exist, they just may not touch them.
+func (h *handlers) requireAdmin() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if !mustActor(c).IsAdmin {
+			writeAPIError(c, http.StatusForbidden, "FORBIDDEN", "admin access required")
+			c.Abort()
+			return
+		}
+		c.Next()
+	}
+}
+
+// settingsResponse is what GET/PATCH /settings return. It carries the stored
+// settings plus a read-only view of what's resolved and live, so the UI can show
+// "inheriting ollama-cloud/glm-5.2:cloud from the environment" and whether a key
+// is present — without ever exposing the key itself.
+type settingsResponse struct {
+	Settings *domain.InstanceSettings `json:"settings"`
+	// Effective is the configuration actually in force after layering settings
+	// over the environment.
+	Effective effectiveView `json:"effective"`
+}
+
+type effectiveView struct {
+	Model   string `json:"model"`
+	Enabled bool   `json:"enabled"`
+	// HasApiKey reports whether OLLAMA_CLOUD_API_KEY is set. The key itself is
+	// never serialized — an admin may know one exists, not what it is.
+	HasApiKey bool `json:"hasApiKey"`
+	// AgentLive is whether the assistant Runner is actually built right now. It
+	// can be false even when Enabled+HasApiKey are true (an unresolvable model),
+	// which is exactly the case the UI needs to surface.
+	AgentLive bool `json:"agentLive"`
+}
+
+// settingsPayload builds the response, or an error. It does NOT swallow an
+// EffectiveAgent failure into a misleading empty "effective" view — an empty
+// view would report no model and no key, which reads as "nothing configured"
+// rather than "we couldn't read it". Since EffectiveAgent re-reads the same row
+// GetInstanceSettings just returned, a failure here is a genuine DB fault worth
+// surfacing as a 500, not papering over.
+func (h *handlers) settingsPayload(c *gin.Context, st *domain.InstanceSettings) (settingsResponse, error) {
+	eff, err := h.svc.EffectiveAgent(c.Request.Context())
+	if err != nil {
+		return settingsResponse{}, err
+	}
+	return settingsResponse{
+		Settings: st,
+		Effective: effectiveView{
+			Model:     eff.Model,
+			Enabled:   eff.Enabled,
+			HasApiKey: eff.APIKey != "",
+			AgentLive: h.agent.get() != nil,
+		},
+	}, nil
+}
+
+func (h *handlers) getSettings(c *gin.Context) {
+	st, err := h.svc.GetInstanceSettings(c.Request.Context(), mustActor(c).ID)
+	if err != nil {
+		writeServiceError(c, err)
+		return
+	}
+	payload, err := h.settingsPayload(c, st)
+	if err != nil {
+		writeServiceError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, payload)
+}
+
+// settingsUpdateRequest is the PATCH body. agentModel "" means inherit the env
+// var. agentEnabled is json.RawMessage so an explicit null (inherit) is
+// distinguishable from an absent field and from true/false.
+type settingsUpdateRequest struct {
+	AgentModel   string          `json:"agentModel"`
+	AgentEnabled json.RawMessage `json:"agentEnabled"`
+	Version      int64           `json:"version" binding:"required"`
+}
+
+func (h *handlers) updateSettings(c *gin.Context) {
+	var req settingsUpdateRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		writeAPIError(c, http.StatusBadRequest, "INVALID_INPUT", "a current version is required")
+		return
+	}
+
+	// agentEnabled: absent or null → inherit (nil); true/false → explicit override.
+	// The shared parseNullable does exactly this three-way decode; present is
+	// irrelevant here because absent and null both mean "inherit".
+	enabled, _, err := parseNullable[bool](req.AgentEnabled)
+	if err != nil {
+		writeAPIError(c, http.StatusBadRequest, "INVALID_INPUT", "agentEnabled must be true, false, or null")
+		return
+	}
+
+	st, err := h.svc.UpdateInstanceSettings(c.Request.Context(), mustActor(c).ID, service.InstanceSettingsPatch{
+		AgentModel:   req.AgentModel,
+		AgentEnabled: enabled,
+		Version:      req.Version,
+	})
+	if err != nil {
+		if errors.Is(err, domain.ErrVersionConflict) {
+			writeVersionConflict(c, st)
+			return
+		}
+		writeServiceError(c, err)
+		return
+	}
+
+	// Apply the change to the LIVE assistant. Detached from the request context:
+	// the write is committed and the rebuild describes it, so a client that hangs
+	// up now must not leave the running Runner out of step with the stored
+	// settings. Mirrors the same reasoning as the history-write detachment.
+	h.agent.rebuild(context.WithoutCancel(c.Request.Context()))
+
+	payload, err := h.settingsPayload(c, st)
+	if err != nil {
+		writeServiceError(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, payload)
+}

internal/api/settings_test.go

@@ -0,0 +1,208 @@
+package api
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/config"
+)
+
+// agentCfg is a config with the assistant configured — a (fake) key, on, and a
+// resolvable model. The key isn't real, but ValidateAgentModel/NewRunner only
+// PARSE the spec (no live call), so a Runner still builds and capabilities
+// reports it live. That's enough to exercise the runtime on/off swap.
+func agentCfg() *config.Config {
+	c := localCfg()
+	c.Agent = config.AgentConfig{
+		Model:             "ollama-cloud/glm-5.2:cloud",
+		OllamaCloudAPIKey: "test-key",
+		Enabled:           true,
+	}
+	return c
+}
+
+func settingsVersion(t *testing.T, r *gin.Engine, cookie *http.Cookie) int64 {
+	t.Helper()
+	w := doJSON(t, r, http.MethodGet, "/api/v1/settings", nil, cookie)
+	if w.Code != http.StatusOK {
+		t.Fatalf("get settings: status %d, body %s", w.Code, w.Body.String())
+	}
+	st, _ := decodeMap(t, w.Body.Bytes())["settings"].(map[string]any)
+	return int64(st["version"].(float64))
+}
+
+// TestSettingsAdminOnly: the first registered user is admin and can read/write
+// settings; a second user is not and gets 403 (not 404 — settings aren't a
+// masked resource).
+func TestSettingsAdminOnly(t *testing.T) {
+	r := authEngine(t, localCfg())
+	admin := registerAndCookie(t, r, "[email protected]") // first user → admin
+	member := registerAndCookie(t, r, "[email protected]")
+
+	if w := doJSON(t, r, http.MethodGet, "/api/v1/settings", nil, admin); w.Code != http.StatusOK {
+		t.Fatalf("admin GET settings: status %d, body %s", w.Code, w.Body.String())
+	}
+
+	if w := doJSON(t, r, http.MethodGet, "/api/v1/settings", nil, member); w.Code != http.StatusForbidden {
+		t.Errorf("member GET settings: status %d, want 403", w.Code)
+	}
+	if w := doJSON(t, r, http.MethodPatch, "/api/v1/settings",
+		map[string]any{"agentModel": "x", "version": 1}, member); w.Code != http.StatusForbidden {
+		t.Errorf("member PATCH settings: status %d, want 403", w.Code)
+	}
+	// Unauthenticated is 401, before the admin check.
+	if w := doJSON(t, r, http.MethodGet, "/api/v1/settings", nil, nil); w.Code != http.StatusUnauthorized {
+		t.Errorf("anonymous GET settings: status %d, want 401", w.Code)
+	}
+}
+
+// TestSettingsInheritFromEnv: an untouched instance reports the env model as
+// effective, and an empty stored model keeps inheriting it.
+func TestSettingsInheritFromEnv(t *testing.T) {
+	r := authEngine(t, agentCfg())
+	admin := registerAndCookie(t, r, "[email protected]")
+
+	w := doJSON(t, r, http.MethodGet, "/api/v1/settings", nil, admin)
+	if w.Code != http.StatusOK {
+		t.Fatalf("get: status %d, body %s", w.Code, w.Body.String())
+	}
+	body := decodeMap(t, w.Body.Bytes())
+	st := body["settings"].(map[string]any)
+	eff := body["effective"].(map[string]any)
+
+	if st["agentModel"] != "" {
+		t.Errorf("stored model = %v, want empty (inherit)", st["agentModel"])
+	}
+	if eff["model"] != "ollama-cloud/glm-5.2:cloud" {
+		t.Errorf("effective model = %v, want the env value", eff["model"])
+	}
+	if eff["hasApiKey"] != true || eff["agentLive"] != true {
+		t.Errorf("effective = %+v, want a key present and the agent live", eff)
+	}
+}
+
+// TestSettingsUpdateSwapsTheRunner is the core of #79: changing settings takes
+// effect on the LIVE assistant, with no restart. Driven entirely through HTTP.
+func TestSettingsUpdateSwapsTheRunner(t *testing.T) {
+	r := authEngine(t, agentCfg())
+	admin := registerAndCookie(t, r, "[email protected]")
+
+	capsAgent := func() bool {
+		w := doJSON(t, r, http.MethodGet, "/api/v1/capabilities", nil, admin)
+		return decodeMap(t, w.Body.Bytes())["agent"] == true
+	}
+
+	// Configured and on out of the box.
+	if !capsAgent() {
+		t.Fatal("assistant should be live at boot with a key + enabled")
+	}
+
+	// Turn it OFF via settings → capabilities flips immediately.
+	v := settingsVersion(t, r, admin)
+	w := doJSON(t, r, http.MethodPatch, "/api/v1/settings",
+		map[string]any{"agentModel": "", "agentEnabled": false, "version": v}, admin)
+	if w.Code != http.StatusOK {
+		t.Fatalf("disable: status %d, body %s", w.Code, w.Body.String())
+	}
+	if capsAgent() {
+		t.Error("assistant still live after being disabled — the runner wasn't swapped")
+	}
+	// Chat now refuses, at runtime, on a route that still exists.
+	gid := createGardenAPI(t, r, admin, "G")
+	if w := doJSON(t, r, http.MethodPost, "/api/v1/agent/chat",
+		map[string]any{"gardenId": gid, "message": "hi"}, admin); w.Code != http.StatusServiceUnavailable {
+		t.Errorf("chat while disabled: status %d, want 503", w.Code)
+	}
+
+	// Turn it back ON, with an explicit model, and confirm it's live again and the
+	// effective model reflects the change.
+	v = settingsVersion(t, r, admin)
+	w = doJSON(t, r, http.MethodPatch, "/api/v1/settings", map[string]any{
+		"agentModel": "ollama-cloud/kimi-k2.6:cloud", "agentEnabled": true, "version": v,
+	}, admin)
+	if w.Code != http.StatusOK {
+		t.Fatalf("re-enable: status %d, body %s", w.Code, w.Body.String())
+	}
+	if eff := decodeMap(t, w.Body.Bytes())["effective"].(map[string]any); eff["model"] != "ollama-cloud/kimi-k2.6:cloud" {
+		t.Errorf("effective model = %v after change, want the new one", eff["model"])
+	}
+	if !capsAgent() {
+		t.Error("assistant not live after being re-enabled")
+	}
+}
+
+// TestSettingsRejectsBadModel: a spec that won't resolve is a 400 at save time,
+// not a broken assistant on the next turn.
+func TestSettingsRejectsBadModel(t *testing.T) {
+	r := authEngine(t, agentCfg())
+	admin := registerAndCookie(t, r, "[email protected]")
+	v := settingsVersion(t, r, admin)
+
+	if w := doJSON(t, r, http.MethodPatch, "/api/v1/settings",
+		map[string]any{"agentModel": "nonesuch/model", "version": v}, admin); w.Code != http.StatusBadRequest {
+		t.Errorf("bad model: status %d, want 400", w.Code)
+	}
+	// agentEnabled must be a bool or null, not a string.
+	if w := doJSON(t, r, http.MethodPatch, "/api/v1/settings",
+		map[string]any{"agentModel": "", "agentEnabled": "yes", "version": v}, admin); w.Code != http.StatusBadRequest {
+		t.Errorf("string agentEnabled: status %d, want 400", w.Code)
+	}
+}
+
+// TestSettingsVersionConflict: a stale version 409s and carries the current row.
+func TestSettingsVersionConflict(t *testing.T) {
+	r := authEngine(t, agentCfg())
+	admin := registerAndCookie(t, r, "[email protected]")
+	v := settingsVersion(t, r, admin)
+
+	// First write succeeds and bumps the version.
+	if w := doJSON(t, r, http.MethodPatch, "/api/v1/settings",
+		map[string]any{"agentModel": "", "agentEnabled": false, "version": v}, admin); w.Code != http.StatusOK {
+		t.Fatalf("first update: status %d, body %s", w.Code, w.Body.String())
+	}
+	// Reusing the old version conflicts.
+	w := doJSON(t, r, http.MethodPatch, "/api/v1/settings",
+		map[string]any{"agentModel": "", "agentEnabled": true, "version": v}, admin)
+	if w.Code != http.StatusConflict {
+		t.Fatalf("stale update: status %d, want 409", w.Code)
+	}
+	if cur, ok := decodeMap(t, w.Body.Bytes())["current"].(map[string]any); !ok || cur["version"].(float64) != float64(v+1) {
+		t.Errorf("409 body missing the current row at the bumped version: %s", w.Body.String())
+	}
+}
+
+// TestSettingsSwapUnderRace runs settings saves concurrently with chat requests,
+// so `go test -race` proves the atomic swap of the live Runner is safe against
+// in-flight readers. The whole point of the atomic.Pointer is this: without it,
+// toggling the assistant while a request reads it is a data race.
+func TestSettingsSwapUnderRace(t *testing.T) {
+	r := authEngine(t, agentCfg())
+	admin := registerAndCookie(t, r, "[email protected]")
+
+	done := make(chan struct{})
+	// Readers hammer capabilities, whose h.agent.get() is the SAME atomic Load the
+	// chat handler does — so this races the pointer read against the writer's swap
+	// without ever invoking the model (a real Run would hit the network on a fake
+	// key). If get() is race-clean here it is race-clean in chat.
+	for i := 0; i < 4; i++ {
+		go func() {
+			for {
+				select {
+				case <-done:
+					return
+				default:
+					doJSON(t, r, http.MethodGet, "/api/v1/capabilities", nil, admin)
+				}
+			}
+		}()
+	}
+	// Writer: flip the assistant on and off, swapping the pointer each time.
+	for i := 0; i < 12; i++ {
+		v := settingsVersion(t, r, admin)
+		doJSON(t, r, http.MethodPatch, "/api/v1/settings",
+			map[string]any{"agentModel": "", "agentEnabled": i%2 == 0, "version": v}, admin)
+	}
+	close(done)
+}

internal/config/config.go

@@ -76,13 +76,6 @@ type AgentConfig struct {
 	Enabled bool
 }
 
-// Ready reports whether the assistant can actually be offered. Both the route
-// registration and whatever advertises capabilities gate on this, so what's
-// advertised always matches what's live.
-func (a AgentConfig) Ready() bool {
-	return a.Enabled && a.OllamaCloudAPIKey != "" && a.Model != ""
-}
-
 // Enabled reports whether enough OIDC config is present to attempt discovery.
 func (o OIDCConfig) Enabled() bool {
 	return o.Issuer != "" && o.ClientID != ""

internal/domain/domain.go

@@ -242,6 +242,22 @@ const (
 	ConflictUnsupported = "unsupported"
 )
 
+// InstanceSettings is the single row of instance-wide, admin-editable
+// configuration (#79). Secrets are deliberately absent — see migration 0010.
+//
+// Both agent fields express "inherit from the environment unless set":
+// AgentModel == "" falls back to PANSY_AGENT_MODEL; AgentEnabled == nil inherits
+// the env default. EffectiveAgent resolves them against the environment.
+type InstanceSettings struct {
+	// AgentModel overrides PANSY_AGENT_MODEL when non-empty. Passed verbatim to
+	// majordomo.Parse, exactly like the env var it shadows.
+	AgentModel string `json:"agentModel"`
+	// AgentEnabled overrides PANSY_AGENT_ENABLED when non-nil. nil = inherit.
+	AgentEnabled *bool  `json:"agentEnabled"`
+	Version      int64  `json:"version"`
+	UpdatedAt    string `json:"updatedAt"`
+}
+
 // User is a pansy account. It may have a local password, OIDC identity, or both.
 type User struct {
 	ID           int64   `json:"id"`

internal/imagenorm/imagenorm.go

@@ -0,0 +1,207 @@
+// Package imagenorm normalizes an uploaded image to a JPEG the rest of pansy
+// (and majordomo's vision path) can rely on, decoding the formats a phone
+// actually produces.
+//
+// # Why this exists
+//
+// majordomo's own media pipeline is stdlib-based, so it cannot decode HEIC or
+// WebP — and HEIC is the iPhone camera default. The seed-packet feature's very
+// first input is "a photo from my phone", so without this the feature fails on
+// the exact device that motivates it. Normalizing at the upload boundary means
+// everything downstream only ever sees JPEG.
+//
+// # The CGO constraint
+//
+// pansy is CGO_ENABLED=0 (a single static binary — the reason modernc/sqlite was
+// chosen over the C one), so a libheif *binding* is out. github.com/gen2brain/heic
+// runs libheif as WebAssembly via wazero: pure Go, no cgo, and it registers with
+// image.Decode like any other format. golang.org/x/image/webp is pure Go too.
+//
+// # Import-driven registry
+//
+// Go's image decoders register via blank imports, and the failure mode is
+// backwards from intuition: forget "image/png" and PNG uploads fail with
+// "unknown format" while the exotic HEIC still works. So the blank imports below
+// are load-bearing, and TestNormalizeAllFormats exercises all four formats to
+// keep them so.
+package imagenorm
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"image"
+	"image/jpeg"
+	"io"
+
+	"golang.org/x/image/draw"
+
+	// Decoders, registered with image.Decode by side effect. All four matter:
+	// jpeg/png are the common cases, heic is the iPhone default, webp is common
+	// on the web. Dropping any one silently breaks that format's uploads.
+	_ "image/jpeg"
+	_ "image/png"
+
+	_ "github.com/gen2brain/heic"
+	_ "golang.org/x/image/webp"
+)
+
+// Defaults chosen for the seed-packet path against ollama-cloud's limits (8
+// images, 20 MiB, 2048px, jpeg+png). We re-encode to JPEG well under all of them.
+const (
+	// DefaultMaxDim is the longest-edge ceiling. 2048 matches ollama-cloud's
+	// MaxDim; anything larger is downscaled. A packet photo has plenty of detail
+	// left at 2048.
+	DefaultMaxDim = 2048
+	// DefaultMaxBytes caps the *input* we will read. A phone photo is 3–8 MB; 25
+	// MiB leaves headroom for a large HEIC without inviting a decompression bomb
+	// as an unbounded read. The re-encoded output is far smaller.
+	DefaultMaxBytes = 25 << 20
+	// maxDecodePixels bounds the DECODED bitmap regardless of input byte size, so
+	// a small file claiming enormous dimensions (a decompression bomb) is refused
+	// before its ~4-bytes/px bitmap is allocated. 50 MP ≈ 200 MB peak — above any
+	// current phone camera (a 48 MP sensor is 48 MP) while capping the
+	// amplification a hostile header can force. maxDecodePixels and maxDimension
+	// are internal safety floors, not knobs — unlike MaxDim/MaxBytes there's no
+	// reason for a caller to raise them.
+	maxDecodePixels = 50_000_000
+	// maxDimension caps EACH side independently. It exists to make the pixel-count
+	// check overflow-safe: without it, a header claiming ~2^32 on a side could
+	// wrap int64(w)*int64(h) negative and slip past maxDecodePixels. No real image
+	// is 50k px on a side.
+	maxDimension = 50_000
+	// jpegQuality for the normalized output. 85 is visually clean and keeps the
+	// file small; the model reads text off it, not fine gradients.
+	jpegQuality = 85
+)
+
+// Options tunes Normalize. The zero value uses the Default* constants.
+type Options struct {
+	MaxDim   int // longest edge; 0 → DefaultMaxDim
+	MaxBytes int // input read cap; 0 → DefaultMaxBytes
+}
+
+func (o Options) maxDim() int {
+	if o.MaxDim > 0 {
+		return o.MaxDim
+	}
+	return DefaultMaxDim
+}
+
+func (o Options) maxBytes() int {
+	if o.MaxBytes > 0 {
+		return o.MaxBytes
+	}
+	return DefaultMaxBytes
+}
+
+// ErrTooLarge means the input exceeded the byte cap or decoded to an absurd
+// pixel count. ErrUnsupported means the bytes weren't a decodable image format —
+// or a decoder panicked on them (see the recover in Normalize).
+var (
+	ErrTooLarge    = errors.New("imagenorm: image too large")
+	ErrUnsupported = errors.New("imagenorm: unsupported or corrupt image")
+)
+
+// Normalize reads an image of any supported format (JPEG, PNG, HEIC, WebP),
+// downscales it to fit opts.MaxDim on its longest edge, and returns it re-encoded
+// as JPEG, plus the decoded format name (e.g. "heic") — handy for logging what a
+// phone actually sent. On any error the returned bytes are nil and format is "".
+//
+// Errors, by cause:
+//   - input over opts.MaxBytes, or a decoded canvas over maxDecodePixels /
+//     maxDimension → ErrTooLarge, refused before the bitmap is allocated;
+//   - bytes that aren't a decodable image, or a decoder that panics on them →
+//     ErrUnsupported;
+//   - a genuine read or JPEG-encode I/O failure → a wrapped error (not a
+//     sentinel), since those are the caller's stream/environment, not the image.
+//
+// It bounds work against a hostile upload three ways: the byte cap, the
+// pre-decode pixel/dimension check, and a recover around the third-party decoders
+// (a malformed HEIC/WebP shouldn't take the process down).
+//
+// Two known gaps, both deferred to the upload handler that wires this in (#81):
+//   - EXIF ORIENTATION is not applied, so a portrait phone photo tagged
+//     "rotate 90°" comes out sideways. That's best fixed and tested with a real
+//     oriented photo end-to-end, which the library has no consumer for yet.
+//   - There is no context: image.Decode is CPU-bound and not cancellable
+//     mid-decode, so a caller that needs a hard deadline should run Normalize
+//     under its own timeout. The size guards keep the work finite regardless.
+func Normalize(r io.Reader, opts Options) (out []byte, format string, err error) {
+	// Cap the read at MaxBytes+1 so we can tell "exactly at the cap" from "over".
+	// maxBytes() is always a sane positive (default 25 MiB); guard the +1 anyway.
+	byteCap := opts.maxBytes()
+	limit := int64(byteCap) + 1
+	if limit < 1 {
+		limit = int64(DefaultMaxBytes) + 1
+	}
+	raw, err := io.ReadAll(io.LimitReader(r, limit))
+	if err != nil {
+		return nil, "", fmt.Errorf("imagenorm: read: %w", err)
+	}
+	if len(raw) > byteCap {
+		return nil, "", ErrTooLarge
+	}
+
+	// Check dimensions BEFORE a full decode, so a decompression bomb is refused
+	// before it allocates its bitmap. The per-side maxDimension check runs first
+	// so the pixel-count multiply below can't overflow.
+	cfg, _, err := image.DecodeConfig(bytes.NewReader(raw))
+	if err != nil {
+		return nil, "", ErrUnsupported
+	}
+	if cfg.Width <= 0 || cfg.Height <= 0 ||
+		cfg.Width > maxDimension || cfg.Height > maxDimension ||
+		int64(cfg.Width)*int64(cfg.Height) > maxDecodePixels {
+		return nil, "", ErrTooLarge
+	}
+
+	img, format, err := decodeSafely(raw)
+	if err != nil {
+		return nil, "", err
+	}
+
+	img = downscale(img, opts.maxDim())
+
+	var buf bytes.Buffer
+	if err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: jpegQuality}); err != nil {
+		return nil, "", fmt.Errorf("imagenorm: encode jpeg: %w", err)
+	}
+	return buf.Bytes(), format, nil
+}
+
+// decodeSafely decodes raw, converting both a decode error and a decoder PANIC
+// into ErrUnsupported. The recover matters because the image comes from an
+// untrusted upload and the HEIC/WebP decoders are third-party (libheif via WASM,
+// x/image/webp): a malformed file that panics one of them must fail this one
+// request, not crash the process.
+func decodeSafely(raw []byte) (img image.Image, format string, err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			img, format, err = nil, "", ErrUnsupported
+		}
+	}()
+	img, format, err = image.Decode(bytes.NewReader(raw))
+	if err != nil {
+		return nil, "", ErrUnsupported
+	}
+	return img, format, nil
+}
+
+// downscale returns img shrunk so its longest edge is at most maxDim, preserving
+// aspect ratio. An image already within bounds is returned unchanged (no
+// re-sampling, no quality loss beyond the JPEG round-trip). Uses Catmull-Rom for
+// a sharp result on text, which is what a packet photo is mostly made of.
+func downscale(img image.Image, maxDim int) image.Image {
+	b := img.Bounds()
+	w, h := b.Dx(), b.Dy()
+	longest := max(w, h)
+	if longest <= maxDim || longest == 0 {
+		return img
+	}
+	scale := float64(maxDim) / float64(longest)
+	nw, nh := max(int(float64(w)*scale), 1), max(int(float64(h)*scale), 1)
+	dst := image.NewRGBA(image.Rect(0, 0, nw, nh))
+	draw.CatmullRom.Scale(dst, dst.Bounds(), img, b, draw.Over, nil)
+	return dst
+}

internal/imagenorm/imagenorm_test.go

@@ -0,0 +1,202 @@
+package imagenorm
+
+import (
+	"bytes"
+	"encoding/binary"
+	"hash/crc32"
+	"image"
+	"image/jpeg"
+	"image/png"
+	"os"
+	"testing"
+)
+
+// pngBytes and jpegBytes generate in-memory fixtures for the two formats Go can
+// encode; heic/webp come from testdata (Go has no encoder for them).
+func pngBytes(t *testing.T, w, h int) []byte {
+	t.Helper()
+	m := image.NewRGBA(image.Rect(0, 0, w, h))
+	for y := range h {
+		for x := range w {
+			m.Pix[m.PixOffset(x, y)+0] = uint8(x)
+			m.Pix[m.PixOffset(x, y)+3] = 255
+		}
+	}
+	var b bytes.Buffer
+	if err := png.Encode(&b, m); err != nil {
+		t.Fatalf("encode png: %v", err)
+	}
+	return b.Bytes()
+}
+
+func jpegBytes(t *testing.T, w, h int) []byte {
+	t.Helper()
+	m := image.NewRGBA(image.Rect(0, 0, w, h))
+	var b bytes.Buffer
+	if err := jpeg.Encode(&b, m, nil); err != nil {
+		t.Fatalf("encode jpeg: %v", err)
+	}
+	return b.Bytes()
+}
+
+func readTestdata(t *testing.T, name string) []byte {
+	t.Helper()
+	b, err := os.ReadFile("testdata/" + name)
+	if err != nil {
+		t.Fatalf("read %s: %v", name, err)
+	}
+	return b
+}
+
+// TestNormalizeAllFormats is the load-bearing test: every format pansy claims to
+// accept must round-trip to a valid JPEG. It exists specifically to catch a
+// dropped blank import — the failure mode where the common format (PNG) breaks
+// while the exotic one (HEIC) works, because someone deleted `_ "image/png"`.
+func TestNormalizeAllFormats(t *testing.T) {
+	cases := []struct {
+		name       string
+		input      []byte
+		wantFormat string
+	}{
+		{"png", pngBytes(t, 120, 90), "png"},
+		{"jpeg", jpegBytes(t, 120, 90), "jpeg"},
+		{"heic", readTestdata(t, "sample.heic"), "heic"},
+		{"webp", readTestdata(t, "sample.webp"), "webp"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			out, format, err := Normalize(bytes.NewReader(tc.input), Options{})
+			if err != nil {
+				t.Fatalf("Normalize(%s): %v", tc.name, err)
+			}
+			if format != tc.wantFormat {
+				t.Errorf("format = %q, want %q", format, tc.wantFormat)
+			}
+			// The output must itself be a decodable JPEG.
+			_, outFormat, err := image.Decode(bytes.NewReader(out))
+			if err != nil {
+				t.Fatalf("output isn't a valid image: %v", err)
+			}
+			if outFormat != "jpeg" {
+				t.Errorf("output format = %q, want jpeg", outFormat)
+			}
+		})
+	}
+}
+
+// TestNormalizeDownscales checks a large image is shrunk to fit MaxDim on its
+// longest edge with aspect ratio preserved, and a small one is left alone.
+func TestNormalizeDownscales(t *testing.T) {
+	// A 2:1 image twice as wide as DefaultMaxDim → clamped to DefaultMaxDim on the
+	// long edge with aspect preserved. Derived from the constant, not hard-coded,
+	// so the test tracks the default rather than silently asserting a magic number.
+	longEdge := DefaultMaxDim * 2
+	big := pngBytes(t, longEdge, longEdge/2)
+	out, _, err := Normalize(bytes.NewReader(big), Options{})
+	if err != nil {
+		t.Fatalf("Normalize: %v", err)
+	}
+	cfg, _, err := image.DecodeConfig(bytes.NewReader(out))
+	if err != nil {
+		t.Fatalf("decode out: %v", err)
+	}
+	if cfg.Width != DefaultMaxDim {
+		t.Errorf("width = %d, want %d (longest edge clamped)", cfg.Width, DefaultMaxDim)
+	}
+	if cfg.Height != DefaultMaxDim/2 {
+		t.Errorf("height = %d, want %d (aspect preserved)", cfg.Height, DefaultMaxDim/2)
+	}
+
+	// A small image within bounds keeps its dimensions.
+	small := pngBytes(t, 100, 80)
+	out, _, err = Normalize(bytes.NewReader(small), Options{})
+	if err != nil {
+		t.Fatalf("Normalize small: %v", err)
+	}
+	cfg, _, err = image.DecodeConfig(bytes.NewReader(out))
+	if err != nil {
+		t.Fatalf("decode small out: %v", err)
+	}
+	if cfg.Width != 100 || cfg.Height != 80 {
+		t.Errorf("small image resized to %dx%d, want 100x80", cfg.Width, cfg.Height)
+	}
+}
+
+// TestNormalizeRejectsOversizeInput: an input past the byte cap is ErrTooLarge,
+// refused without a full decode.
+func TestNormalizeRejectsOversizeInput(t *testing.T) {
+	big := pngBytes(t, 500, 500)
+	_, _, err := Normalize(bytes.NewReader(big), Options{MaxBytes: 100})
+	if err != ErrTooLarge {
+		t.Errorf("over-cap input err = %v, want ErrTooLarge", err)
+	}
+}
+
+// TestNormalizeRejectsGarbage: unreadable-as-image bytes and a truncated image
+// both fail cleanly with ErrUnsupported, not a panic.
+func TestNormalizeRejectsGarbage(t *testing.T) {
+	_, _, err := Normalize(bytes.NewReader([]byte("not an image at all")), Options{})
+	if err != ErrUnsupported {
+		t.Errorf("garbage err = %v, want ErrUnsupported", err)
+	}
+	// A truncated image (valid header, cut body) also fails cleanly, not a panic.
+	png := pngBytes(t, 100, 100)
+	_, _, err = Normalize(bytes.NewReader(png[:len(png)/2]), Options{})
+	if err != ErrUnsupported {
+		t.Errorf("truncated image err = %v, want ErrUnsupported", err)
+	}
+}
+
+// pngHeader builds a valid PNG signature + IHDR chunk (with a correct CRC, which
+// DecodeConfig verifies) for the given dimensions, and nothing else. It's enough
+// for image.DecodeConfig to report width/height without a real bitmap — exactly
+// what's needed to exercise the pre-decode size guard with a tiny input.
+func pngHeader(w, h uint32) []byte {
+	var buf bytes.Buffer
+	buf.Write([]byte{0x89, 'P', 'N', 'G', 0x0d, 0x0a, 0x1a, 0x0a})
+	ihdr := make([]byte, 13)
+	binary.BigEndian.PutUint32(ihdr[0:], w)
+	binary.BigEndian.PutUint32(ihdr[4:], h)
+	ihdr[8] = 8 // bit depth
+	ihdr[9] = 6 // colour type: RGBA
+	// compression/filter/interlace already 0.
+	binary.Write(&buf, binary.BigEndian, uint32(len(ihdr)))
+	chunk := append([]byte("IHDR"), ihdr...)
+	buf.Write(chunk)
+	binary.Write(&buf, binary.BigEndian, crc32.ChecksumIEEE(chunk))
+	return buf.Bytes()
+}
+
+// TestNormalizeRejectsPixelBomb is the guard the review found untested: a small
+// input (a bare ~40-byte PNG header) claiming an enormous canvas is refused with
+// ErrTooLarge from DecodeConfig alone, before image.Decode allocates anything.
+// Covers both the per-side maxDimension trip and the pixel-count trip — and, via
+// the near-2^16-per-side case, that the count math doesn't overflow.
+func TestNormalizeRejectsPixelBomb(t *testing.T) {
+	cases := []struct {
+		name string
+		w, h uint32
+	}{
+		{"huge single side", 60000, 10},             // > maxDimension on width
+		{"huge area within side cap", 40000, 40000}, // sides < cap, area 1.6 GP > maxDecodePixels
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			hdr := pngHeader(tc.w, tc.h)
+			if len(hdr) > 100 {
+				t.Fatalf("header unexpectedly large (%d bytes) — not a bomb test", len(hdr))
+			}
+			// Sanity: the header really does decode to those dimensions.
+			cfg, _, err := image.DecodeConfig(bytes.NewReader(hdr))
+			if err != nil {
+				t.Fatalf("crafted PNG header didn't parse: %v", err)
+			}
+			if uint32(cfg.Width) != tc.w || uint32(cfg.Height) != tc.h {
+				t.Fatalf("header reports %dx%d, want %dx%d", cfg.Width, cfg.Height, tc.w, tc.h)
+			}
+			if _, _, err := Normalize(bytes.NewReader(hdr), Options{}); err != ErrTooLarge {
+				t.Errorf("pixel bomb %dx%d err = %v, want ErrTooLarge", tc.w, tc.h, err)
+			}
+		})
+	}
+}

internal/imagenorm/testdata/README.md

@@ -0,0 +1,14 @@
+# imagenorm test fixtures
+
+Go has no encoder for HEIC or WebP, so these small samples are committed rather
+than generated at test time. They are used by `TestNormalizeAllFormats` to prove
+every accepted format round-trips to JPEG (and, mainly, to catch a dropped blank
+import — see the package doc).
+
+- `sample.heic` — a 240×160 gradient, created from a Go-generated PNG with macOS
+  `sips -s format heic`. HEVC still-image profile.
+- `sample.webp` — a 16×16 image copied from CPython's stdlib test corpus
+  (`Lib/test/test_email/data/python.webp`), verified to decode with
+  `golang.org/x/image/webp` before committing. Used only as a decode fixture.
+
+Neither contains anything meaningful; they exist purely to be decoded.

internal/service/instance_settings.go

@@ -0,0 +1,110 @@
+package service
+
+import (
+	"context"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/agentmodel"
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
+)
+
+// Instance settings (#79): admin-editable, instance-wide configuration. The
+// admin gate lives HERE, in the seam, not in the handler — the same rule every
+// other permission follows. The API's requireAdmin middleware is a cheap early
+// 403, not the authority.
+
+// requireAdmin returns nil iff the actor is an admin, else ErrForbidden.
+//
+// ErrForbidden, not ErrNotFound: settings are not a resource whose existence is
+// masked. A logged-in non-admin knows the instance has settings; they simply may
+// not touch them. (Contrast objects/lots, where no-access masks existence.)
+func (s *Service) requireAdmin(ctx context.Context, actorID int64) error {
+	u, err := s.store.GetUserByID(ctx, actorID)
+	if err != nil {
+		return err
+	}
+	if !u.IsAdmin {
+		return domain.ErrForbidden
+	}
+	return nil
+}
+
+// GetInstanceSettings returns the instance settings for an admin.
+func (s *Service) GetInstanceSettings(ctx context.Context, actorID int64) (*domain.InstanceSettings, error) {
+	if err := s.requireAdmin(ctx, actorID); err != nil {
+		return nil, err
+	}
+	return s.store.GetInstanceSettings(ctx)
+}
+
+// InstanceSettingsPatch is a full replacement of the editable fields plus the
+// current version. Both agent fields carry their "inherit" sentinel: an empty
+// AgentModel means fall back to env, a nil AgentEnabled means inherit.
+type InstanceSettingsPatch struct {
+	AgentModel   string
+	AgentEnabled *bool
+	Version      int64
+}
+
+// UpdateInstanceSettings applies an admin's change, version-guarded. It returns
+// (current row, ErrVersionConflict) on a stale version, like every mutable
+// resource. The model spec is validated before it is stored, so a typo is a 400
+// now rather than a broken assistant on the next turn.
+//
+// It does NOT rebuild the running agent — that is the API layer's job, because
+// the live Runner lives there. The caller rebuilds on success.
+func (s *Service) UpdateInstanceSettings(ctx context.Context, actorID int64, patch InstanceSettingsPatch) (*domain.InstanceSettings, error) {
+	if err := s.requireAdmin(ctx, actorID); err != nil {
+		return nil, err
+	}
+	model := strings.TrimSpace(patch.AgentModel)
+	// Validate a non-empty spec up front. An empty one is the "inherit env"
+	// sentinel and needs no check — the env value was validated at boot.
+	if model != "" {
+		if err := agentmodel.Validate(s.cfg.Agent.OllamaCloudAPIKey, model); err != nil {
+			return nil, domain.ErrInvalidInput
+		}
+	}
+	return s.store.UpdateInstanceSettings(ctx, &domain.InstanceSettings{
+		AgentModel:   model,
+		AgentEnabled: patch.AgentEnabled,
+		Version:      patch.Version,
+	})
+}
+
+// EffectiveAgent resolves the agent configuration actually in force: DB settings
+// override the environment, and the API key always comes from the environment.
+//
+// This is internal plumbing (the API layer calls it to build the Runner), NOT an
+// admin-gated operation — resolving what's configured is not the same as editing
+// it, and the agent bootstrap must work before any user is even authenticated.
+type EffectiveAgent struct {
+	Model   string
+	Enabled bool
+	APIKey  string
+}
+
+// Ready mirrors config.AgentConfig.Ready: enabled, with a key and a model.
+func (e EffectiveAgent) Ready() bool {
+	return e.Enabled && e.APIKey != "" && e.Model != ""
+}
+
+// EffectiveAgent reads the settings row and layers it over the environment.
+func (s *Service) EffectiveAgent(ctx context.Context) (EffectiveAgent, error) {
+	st, err := s.store.GetInstanceSettings(ctx)
+	if err != nil {
+		return EffectiveAgent{}, err
+	}
+	eff := EffectiveAgent{
+		Model:   s.cfg.Agent.Model,
+		Enabled: s.cfg.Agent.Enabled,
+		APIKey:  s.cfg.Agent.OllamaCloudAPIKey,
+	}
+	if st.AgentModel != "" {
+		eff.Model = st.AgentModel
+	}
+	if st.AgentEnabled != nil {
+		eff.Enabled = *st.AgentEnabled
+	}
+	return eff, nil
+}

internal/service/instance_settings_test.go

@@ -0,0 +1,117 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/config"
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
+)
+
+// settingsTestService builds a service whose env config carries the given agent
+// model/enabled/key, so EffectiveAgent's env fallback can be exercised.
+func settingsTestService(t *testing.T, envModel string, envEnabled bool, key string) (*Service, int64) {
+	t.Helper()
+	cfg := openConfig()
+	cfg.Agent = config.AgentConfig{Model: envModel, Enabled: envEnabled, OllamaCloudAPIKey: key}
+	s := newTestService(t, cfg)
+	admin := seedUser(t, s, "[email protected]") // first user is admin
+	return s, admin
+}
+
+// TestRequireAdmin: the first user is admin; a second is not and gets
+// ErrForbidden (not ErrNotFound — settings existence isn't masked).
+func TestRequireAdmin(t *testing.T) {
+	s, admin := settingsTestService(t, "ollama-cloud/x", true, "k")
+	member := seedUser(t, s, "[email protected]")
+
+	if err := s.requireAdmin(context.Background(), admin); err != nil {
+		t.Errorf("admin rejected: %v", err)
+	}
+	if err := s.requireAdmin(context.Background(), member); !errors.Is(err, domain.ErrForbidden) {
+		t.Errorf("member requireAdmin = %v, want ErrForbidden", err)
+	}
+}
+
+// TestEffectiveAgentLayering: DB settings override env; the API key always comes
+// from env; the "inherit" sentinels fall back.
+func TestEffectiveAgentLayering(t *testing.T) {
+	ctx := context.Background()
+	s, admin := settingsTestService(t, "ollama-cloud/env-model", true, "envkey")
+
+	// Untouched: everything inherits env.
+	eff, err := s.EffectiveAgent(ctx)
+	if err != nil {
+		t.Fatalf("effective: %v", err)
+	}
+	if eff.Model != "ollama-cloud/env-model" || !eff.Enabled || eff.APIKey != "envkey" {
+		t.Errorf("inherited effective = %+v, want the env values", eff)
+	}
+
+	// Override the model only; enabled still inherits env (true).
+	cur, _ := s.GetInstanceSettings(ctx, admin)
+	if _, err := s.UpdateInstanceSettings(ctx, admin, InstanceSettingsPatch{
+		AgentModel: "ollama-cloud/glm-5.2:cloud", Version: cur.Version,
+	}); err != nil {
+		t.Fatalf("update model: %v", err)
+	}
+	eff, _ = s.EffectiveAgent(ctx)
+	if eff.Model != "ollama-cloud/glm-5.2:cloud" {
+		t.Errorf("model = %q, want the DB override", eff.Model)
+	}
+	if !eff.Enabled {
+		t.Error("enabled should still inherit env (true) when unset")
+	}
+
+	// Now override enabled to false explicitly.
+	cur, _ = s.GetInstanceSettings(ctx, admin)
+	no := false
+	if _, err := s.UpdateInstanceSettings(ctx, admin, InstanceSettingsPatch{
+		AgentModel: "ollama-cloud/glm-5.2:cloud", AgentEnabled: &no, Version: cur.Version,
+	}); err != nil {
+		t.Fatalf("update enabled: %v", err)
+	}
+	eff, _ = s.EffectiveAgent(ctx)
+	if eff.Enabled {
+		t.Error("enabled should be the explicit false override now")
+	}
+	if eff.Ready() {
+		t.Error("Ready() should be false when disabled")
+	}
+}
+
+// TestUpdateInstanceSettingsRejectsBadModel: a spec that won't resolve is
+// ErrInvalidInput, before it is stored.
+func TestUpdateInstanceSettingsRejectsBadModel(t *testing.T) {
+	ctx := context.Background()
+	s, admin := settingsTestService(t, "ollama-cloud/x", true, "k")
+	cur, _ := s.GetInstanceSettings(ctx, admin)
+
+	if _, err := s.UpdateInstanceSettings(ctx, admin, InstanceSettingsPatch{
+		AgentModel: "nonesuch/model", Version: cur.Version,
+	}); !errors.Is(err, domain.ErrInvalidInput) {
+		t.Errorf("bad model = %v, want ErrInvalidInput", err)
+	}
+
+	// The rejected write didn't touch the row.
+	after, _ := s.GetInstanceSettings(ctx, admin)
+	if after.Version != cur.Version || after.AgentModel != "" {
+		t.Errorf("a rejected update changed the row: %+v", after)
+	}
+}
+
+// TestInstanceSettingsAdminGate: the read/write operations are admin-gated at the
+// service seam, not just in the handler.
+func TestInstanceSettingsAdminGate(t *testing.T) {
+	ctx := context.Background()
+	s, _ := settingsTestService(t, "ollama-cloud/x", true, "k")
+	member := seedUser(t, s, "[email protected]")
+
+	if _, err := s.GetInstanceSettings(ctx, member); !errors.Is(err, domain.ErrForbidden) {
+		t.Errorf("member GetInstanceSettings = %v, want ErrForbidden", err)
+	}
+	if _, err := s.UpdateInstanceSettings(ctx, member, InstanceSettingsPatch{Version: 1}); !errors.Is(err, domain.ErrForbidden) {
+		t.Errorf("member UpdateInstanceSettings = %v, want ErrForbidden", err)
+	}
+}

internal/store/instance_settings.go

@@ -0,0 +1,81 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"gitea.stevedudenhoeffer.com/steve/pansy/internal/domain"
+)
+
+// The instance_settings row is seeded by migration 0010 and there is exactly one
+// (CHECK id = 1), so reads never branch on existence and writes never insert.
+
+const instanceSettingsColumns = `agent_model, agent_enabled, version, updated_at`
+
+// scanInstanceSettings reads the single settings row. agent_enabled is a nullable
+// INTEGER (NULL = inherit env), so it is scanned through sql.NullInt64.
+func scanInstanceSettings(s scanner) (*domain.InstanceSettings, error) {
+	var (
+		out     domain.InstanceSettings
+		enabled sql.NullInt64
+	)
+	if err := s.Scan(&out.AgentModel, &enabled, &out.Version, &out.UpdatedAt); err != nil {
+		return nil, err
+	}
+	if enabled.Valid {
+		b := enabled.Int64 != 0
+		out.AgentEnabled = &b
+	}
+	return &out, nil
+}
+
+// GetInstanceSettings returns the single settings row.
+func (d *DB) GetInstanceSettings(ctx context.Context) (*domain.InstanceSettings, error) {
+	s, err := scanInstanceSettings(d.sql.QueryRowContext(ctx,
+		`SELECT `+instanceSettingsColumns+` FROM instance_settings WHERE id = 1`))
+	if errors.Is(err, sql.ErrNoRows) {
+		// The migration seeds this row, so its absence is a broken database, not a
+		// normal "not found" the caller should paper over.
+		return nil, fmt.Errorf("store: instance_settings row missing (migration 0010 not applied?)")
+	}
+	if err != nil {
+		return nil, fmt.Errorf("store: get instance settings: %w", err)
+	}
+	return s, nil
+}
+
+// UpdateInstanceSettings applies a version-guarded update to the single row,
+// following the same optimistic-concurrency contract as every mutable resource:
+// the updated row on success, (current row, ErrVersionConflict) on a version
+// mismatch. There is no ErrNotFound path — the row always exists.
+//
+// agentEnabled is nil to store SQL NULL (inherit env), or a pointer to store an
+// explicit 0/1.
+func (d *DB) UpdateInstanceSettings(ctx context.Context, s *domain.InstanceSettings) (*domain.InstanceSettings, error) {
+	var enabled any
+	if s.AgentEnabled != nil {
+		enabled = boolToInt(*s.AgentEnabled)
+	}
+	updated, err := scanInstanceSettings(d.sql.QueryRowContext(ctx,
+		`UPDATE instance_settings
+		    SET agent_model = ?, agent_enabled = ?,
+		        version = version + 1,
+		        updated_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now')
+		  WHERE id = 1 AND version = ?
+		  RETURNING `+instanceSettingsColumns,
+		s.AgentModel, enabled, s.Version,
+	))
+	if errors.Is(err, sql.ErrNoRows) {
+		current, gerr := d.GetInstanceSettings(ctx)
+		if gerr != nil {
+			return nil, gerr
+		}
+		return current, domain.ErrVersionConflict
+	}
+	if err != nil {
+		return nil, fmt.Errorf("store: update instance settings: %w", err)
+	}
+	return updated, nil
+}

internal/store/migrations/0010_instance_settings.sql

@@ -0,0 +1,35 @@
+-- Instance settings (#79): the first configuration that lives in the database
+-- rather than the environment.
+--
+-- Until now every preference hung off a garden or object row; this is pansy's
+-- first INSTANCE-level state. A single-row table (CHECK id = 1) is the least
+-- surprising shape for "there is exactly one of these" — a key/value table would
+-- invite typo'd keys and lose the column types.
+--
+-- Only NON-SECRET agent settings live here. OLLAMA_CLOUD_API_KEY stays in the
+-- environment on purpose: a copy in SQLite would land in every backup and in the
+-- blast radius of the undo history. An admin can change WHICH model runs, not
+-- WHOSE account pays for it.
+--
+-- Both agent columns are "inherit from env unless set":
+--   * agent_model = '' means fall back to PANSY_AGENT_MODEL, then the built-in
+--     default. So an instance that never opens Settings behaves exactly as it
+--     did before this migration, and the documented env var keeps working.
+--   * agent_enabled is NULLABLE: NULL means inherit PANSY_AGENT_ENABLED's
+--     behaviour (on when a key is present), 0/1 is an explicit override. A plain
+--     boolean couldn't tell "admin hasn't touched this" from "admin turned it
+--     off", and those must deploy differently.
+--
+-- version drives the same optimistic-concurrency 409 every other mutable row
+-- uses, so two admins editing at once conflict rather than clobber.
+CREATE TABLE instance_settings (
+    id            INTEGER PRIMARY KEY CHECK (id = 1),
+    agent_model   TEXT    NOT NULL DEFAULT '',
+    agent_enabled INTEGER          CHECK (agent_enabled IN (0, 1)),
+    version       INTEGER NOT NULL DEFAULT 1,
+    updated_at    TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+
+-- Seed the single row so every read is a plain SELECT with no "does it exist
+-- yet" branch. Inherits everything from the environment out of the box.
+INSERT INTO instance_settings (id, agent_model, agent_enabled) VALUES (1, '', NULL);

web/src/components/layout/AppShell.tsx

@@ -53,6 +53,19 @@ export function AppShell() {
                   {l.label}
                 </Link>
               ))}
+            {/* Settings is admin-only, matching the server's requireAdmin gate.
+                A non-admin who typed /settings still gets a 403 from the API — the
+                hidden link is convenience, not the security boundary. */}
+            {user?.isAdmin && (
+              <Link
+                to="/settings"
+                className={navLinkBase}
+                activeProps={{ className: navLinkActive }}
+                inactiveProps={{ className: navLinkInactive }}
+              >
+                Settings
+              </Link>
+            )}
           </div>
 
           {user ? (

web/src/lib/agent.ts

@@ -13,13 +13,21 @@ import { historyKey } from './history'
 
 const capabilitiesSchema = z.object({ agent: z.boolean() })
 
-/** Whether this instance has the assistant configured. Without it the panel
- *  isn't rendered at all — a dead button is worse than no button. */
+export const capabilitiesKey = ['capabilities'] as const
+
+/** Whether the assistant is live RIGHT NOW. Without it the panel isn't rendered
+ *  at all — a dead button is worse than no button.
+ *
+ *  Not `staleTime: Infinity` any more: an admin can turn the assistant on or off
+ *  in Settings (#79), so this must be able to change under a running page. The
+ *  settings save invalidates this key directly; the finite staleTime just means
+ *  another admin's change is picked up on the next focus/remount rather than
+ *  never. */
 export function useCapabilities() {
   return useQuery({
-    queryKey: ['capabilities'] as const,
+    queryKey: capabilitiesKey,
     queryFn: async () => capabilitiesSchema.parse(await api.get('/capabilities')),
-    staleTime: Infinity, // server config; it doesn't change under a running page
+    staleTime: 60_000,
   })
 }
 
@@ -153,10 +161,15 @@ export async function streamChat(
     return
   }
   if (!res.ok || !res.body) {
+    // 503 is the assistant being turned off at runtime (#79) — the route exists,
+    // there's just no model behind it. Distinct from a 404, which would mean the
+    // whole endpoint is absent.
     handlers.onError(
-      res.status === 404
-        ? "This instance doesn't have the assistant configured."
-        : 'The assistant is not available right now.',
+      res.status === 503
+        ? "The assistant isn't enabled on this instance."
+        : res.status === 404
+          ? "This instance doesn't have the assistant configured."
+          : 'The assistant is not available right now.',
     )
     return
   }

web/src/lib/settings.ts

@@ -0,0 +1,79 @@
+// Instance settings data layer (#79): admin-only, instance-wide configuration.
+//
+// The GET/PATCH return both the stored settings and a read-only "effective" view
+// — what's actually in force after layering the DB over the environment — so the
+// form can say "inheriting ollama-cloud/glm-5.2:cloud from the environment" and
+// whether the API key is present, without the key ever crossing the wire.
+
+import { queryOptions, useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { z } from 'zod'
+import { ApiError, api } from './api'
+import { capabilitiesKey } from './agent'
+
+export const instanceSettingsSchema = z.object({
+  // '' means "inherit the PANSY_AGENT_MODEL env var".
+  agentModel: z.string(),
+  // null means "inherit PANSY_AGENT_ENABLED"; true/false is an explicit override.
+  agentEnabled: z.boolean().nullable(),
+  version: z.number(),
+  updatedAt: z.string(),
+})
+export type InstanceSettings = z.infer<typeof instanceSettingsSchema>
+
+export const effectiveAgentSchema = z.object({
+  model: z.string(),
+  enabled: z.boolean(),
+  hasApiKey: z.boolean(),
+  agentLive: z.boolean(),
+})
+export type EffectiveAgent = z.infer<typeof effectiveAgentSchema>
+
+export const settingsResponseSchema = z.object({
+  settings: instanceSettingsSchema,
+  effective: effectiveAgentSchema,
+})
+export type SettingsResponse = z.infer<typeof settingsResponseSchema>
+
+export const settingsKey = ['settings'] as const
+
+export const settingsQueryOptions = queryOptions({
+  queryKey: settingsKey,
+  queryFn: async (): Promise<SettingsResponse> =>
+    settingsResponseSchema.parse(await api.get('/settings')),
+})
+
+export function useSettings() {
+  return useQuery(settingsQueryOptions)
+}
+
+export interface SettingsUpdate {
+  agentModel: string
+  agentEnabled: boolean | null
+  version: number
+}
+
+export function useUpdateSettings() {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: async (input: SettingsUpdate): Promise<SettingsResponse> =>
+      settingsResponseSchema.parse(await api.patch('/settings', input)),
+    onSuccess: (res) => {
+      qc.setQueryData(settingsKey, res)
+      // The save may have turned the assistant on or off; the editor keys its
+      // chat tab off /capabilities, so make it re-read rather than trust its
+      // cached answer.
+      qc.invalidateQueries({ queryKey: capabilitiesKey })
+    },
+  })
+}
+
+/** If err is a 409 version conflict, return the fresh settings it carries so a
+ *  form can rebase; otherwise null. */
+export function conflictSettings(err: unknown): InstanceSettings | null {
+  if (err instanceof ApiError && err.isConflict && err.body && typeof err.body === 'object') {
+    const current = (err.body as { current?: unknown }).current
+    const parsed = instanceSettingsSchema.safeParse(current)
+    if (parsed.success) return parsed.data
+  }
+  return null
+}

web/src/pages/SettingsPage.tsx

@@ -0,0 +1,164 @@
+import { useEffect, useState } from 'react'
+import { Alert } from '@/components/ui/Alert'
+import { Button } from '@/components/ui/Button'
+import { Select } from '@/components/ui/Select'
+import { TextField } from '@/components/ui/TextField'
+import { toast } from '@/components/ui/toast'
+import { errorMessage } from '@/lib/api'
+import {
+  conflictSettings,
+  useSettings,
+  useUpdateSettings,
+  type EffectiveAgent,
+  type InstanceSettings,
+} from '@/lib/settings'
+import { usePageTitle } from '@/lib/usePageTitle'
+
+// agentEnabled is a tri-state on the wire (null = inherit env, true, false); the
+// form models it as three named choices so "inherit" is a deliberate pick, not
+// an empty control.
+type EnabledChoice = 'inherit' | 'on' | 'off'
+const toChoice = (v: boolean | null): EnabledChoice => (v === null ? 'inherit' : v ? 'on' : 'off')
+const fromChoice = (c: EnabledChoice): boolean | null => (c === 'inherit' ? null : c === 'on')
+
+/** Admin-only instance settings (#79). The one that matters today is the agent
+ *  model; the API key stays in the environment and is only ever reported as
+ *  present/absent, never shown or edited. */
+export function SettingsPage() {
+  usePageTitle('Settings')
+  const settings = useSettings()
+  const update = useUpdateSettings()
+
+  if (settings.isPending) {
+    return <p className="text-sm text-muted">Loading settings…</p>
+  }
+  if (settings.isError) {
+    return <Alert>{errorMessage(settings.error, "Couldn't load settings.")}</Alert>
+  }
+  return <SettingsForm data={settings.data} update={update} />
+}
+
+function SettingsForm({
+  data,
+  update,
+}: {
+  data: { settings: InstanceSettings; effective: EffectiveAgent }
+  update: ReturnType<typeof useUpdateSettings>
+}) {
+  const [model, setModel] = useState(data.settings.agentModel)
+  const [enabled, setEnabled] = useState<EnabledChoice>(toChoice(data.settings.agentEnabled))
+  const [version, setVersion] = useState(data.settings.version)
+  const [error, setError] = useState<string | null>(null)
+
+  // Rebase the form when the query cache updates (e.g. a successful save writes
+  // the new row back), so the version we submit is never stale.
+  useEffect(() => {
+    setVersion(data.settings.version)
+  }, [data.settings.version])
+
+  const eff = data.effective
+
+  const save = () => {
+    setError(null)
+    update.mutate(
+      { agentModel: model.trim(), agentEnabled: fromChoice(enabled), version },
+      {
+        onSuccess: () => toast.info('Settings saved.'),
+        onError: (err) => {
+          const current = conflictSettings(err)
+          if (current) {
+            // Someone else saved first. Adopt their row so the next attempt is
+            // clean, and say so rather than silently discarding this edit.
+            setModel(current.agentModel)
+            setEnabled(toChoice(current.agentEnabled))
+            setVersion(current.version)
+            setError('Someone else changed these settings just now — reloaded their version. Re-apply your change if you still want it.')
+            return
+          }
+          setError(errorMessage(err, "Couldn't save settings."))
+        },
+      },
+    )
+  }
+
+  return (
+    <div className="flex max-w-2xl flex-col gap-6">
+      <div>
+        <h1 className="text-xl font-semibold text-fg">Settings</h1>
+        <p className="mt-1 text-sm text-muted">
+          Instance-wide, admin-only. Changes take effect immediately — no restart.
+        </p>
+      </div>
+
+      <section className="flex flex-col gap-4 rounded-lg border border-border p-4">
+        <div>
+          <h2 className="text-sm font-semibold text-fg">Garden assistant</h2>
+          <p className="mt-1 text-xs text-muted">
+            The model runs against your Ollama Cloud key, which is set in the environment and never
+            shown here.
+          </p>
+        </div>
+
+        <AgentStatus eff={eff} />
+
+        <TextField
+          label="Model"
+          name="agentModel"
+          placeholder={eff.model || 'ollama-cloud/glm-5.2:cloud'}
+          value={model}
+          onChange={(e) => setModel(e.target.value)}
+          hint={
+            model.trim() === ''
+              ? `Empty — inheriting ${eff.model || 'the built-in default'} from the environment.`
+              : 'A majordomo model spec. A comma-separated list is a failover chain.'
+          }
+        />
+
+        <Select
+          label="Enabled"
+          name="agentEnabled"
+          value={enabled}
+          onChange={(e) => setEnabled(e.target.value as EnabledChoice)}
+          options={[
+            { value: 'inherit', label: 'Inherit from environment' },
+            { value: 'on', label: 'On' },
+            { value: 'off', label: 'Off' },
+          ]}
+        />
+      </section>
+
+      {error && <Alert>{error}</Alert>}
+
+      <div className="flex justify-end">
+        <Button onClick={save} disabled={update.isPending}>
+          {update.isPending ? 'Saving…' : 'Save changes'}
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+// AgentStatus surfaces the gap the capabilities endpoint exists for: enabled +
+// a key does not guarantee the assistant is actually running (an unresolvable
+// model leaves it down), and that's precisely what an admin needs to see.
+function AgentStatus({ eff }: { eff: EffectiveAgent }) {
+  const [tone, text] = eff.agentLive
+    ? (['ok', `Live on ${eff.model}`] as const)
+    : !eff.hasApiKey
+      ? (['warn', 'No API key set in the environment — the assistant is off.'] as const)
+      : !eff.enabled
+        ? (['warn', 'Turned off.'] as const)
+        : (['warn', `Configured but not running — check the model (${eff.model}).`] as const)
+
+  return (
+    <div className="flex items-center gap-2 text-sm">
+      <span
+        className={
+          'inline-block h-2 w-2 rounded-full ' + (tone === 'ok' ? 'bg-emerald-500' : 'bg-amber-500')
+        }
+        aria-hidden
+      />
+      <span className={tone === 'ok' ? 'text-fg' : 'text-muted'}>{text}</span>
+    </div>
+  )
+}

web/src/router.tsx

@@ -14,6 +14,7 @@ import { GardensPage } from '@/pages/GardensPage'
 import { GardenEditorPage } from '@/pages/GardenEditorPage'
 import { PublicGardenPage } from '@/pages/PublicGardenPage'
 import { PlantsPage } from '@/pages/PlantsPage'
+import { SettingsPage } from '@/pages/SettingsPage'
 import { meQueryOptions } from '@/lib/auth'
 import { queryClient } from '@/lib/queryClient'
 import { safeRedirectPath } from '@/lib/redirect'
@@ -48,6 +49,20 @@ async function requireGuest(context: RouterContext, redirectTo: string) {
   }
 }
 
+// requireAdmin: authenticated AND admin. A non-admin who navigates to /settings
+// is sent to /gardens rather than shown a page whose API calls would 403. This
+// is convenience routing, not the security boundary — the server's requireAdmin
+// is authoritative.
+async function requireAdmin(context: RouterContext, path: string) {
+  const me = await context.queryClient.ensureQueryData(meQueryOptions)
+  if (!me) {
+    throw redirect({ to: '/login', search: { redirect: path } })
+  }
+  if (!me.isAdmin) {
+    throw redirect({ to: '/gardens' })
+  }
+}
+
 const indexRoute = createRoute({
   getParentRoute: () => rootRoute,
   path: '/',
@@ -109,6 +124,13 @@ const plantsRoute = createRoute({
   component: PlantsPage,
 })
 
+const settingsRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: 'settings',
+  beforeLoad: ({ context, location }) => requireAdmin(context, location.href),
+  component: SettingsPage,
+})
+
 // Public read-only garden by share token. Deliberately has NO beforeLoad auth
 // guard, so a logged-out visitor viewing a shared link is never redirected to
 // /login or OIDC.
@@ -125,6 +147,7 @@ const routeTree = rootRoute.addChildren([
   gardensRoute,
   gardenEditorRoute,
   plantsRoute,
+  settingsRoute,
   publicGardenRoute,
 ])