Fix dashboard registration to use the real Lovelace API (P1-P3)

P1: The registration was a silent no-op in production — it read
hass.data["lovelace"].dashboards as the DashboardsCollection and
awaited a sync async_items(), and passed "strategy"/"mode" keys the
real create schema rejects. Per the real lovelace source
(components/lovelace/__init__.py, _create_map_dashboard): the metadata
collection lives at hass.data["lovelace"]["dashboards_collection"],
async_items() is a SYNC @callback, the create payload carries metadata
only (url_path/title/icon/show_in_sidebar/allow_single_word), and the
dashboard CONFIG (the strategy reference) is saved as a SECOND step
through the content manager registered under
hass.data["lovelace"]["dashboards"][url_path]. The strategy is saved
only for a dashboard created in this run (or whose config already
carries ours); an existing dashboard skips both steps, so a user's
dashboard config is never overwritten. Collection unavailable / save
raising still warns and continues, never crashing setup.

P2: Declare "lovelace" in manifest.json dependencies (alongside
frontend/http) so hass.data["lovelace"] is populated before setup
instead of relying on boot order.

P3: Guard the check-then-create with a per-hass asyncio.Lock so two
concurrent entry setups cannot both pass the exists-check and race on
the url_path create. Per-hass (attribute on the hass object) rather
than a bare module-level lock, which binds to the first event loop
that awaits it.

The lifecycle tests' fake is rebuilt to mirror the real API shape
(sync async_items, async async_create_item, a dashboards content-
manager dict whose entries expose async async_save), with assertions
that the strategy config was saved with the custom:nestquest-party
type, that a user's existing config is not overwritten, that a failing
save still leaves setup green, and that concurrent registrations
create the dashboard exactly once (verified to fail without the
guard).

.opencode/agents/approver.md

@@ -0,0 +1,32 @@
+---
+description: Independently verify NestQuest merge gates and merge approved heads
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  edit: deny
+  write: deny
+  task: deny
+  bash:
+    "*": deny
+    "/home/overseer/.local/share/nestquest-controller/scripts/nq-approve-merge *": allow
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/nestquest-controller/*": allow
+---
+
+You are the NestQuest feature-to-dev approver, separate from the controller and
+developer sessions. Verify the current PR head equals the independently
+reviewed and approved commit,
+required checks pass, blocking findings are resolved, branch protection is
+satisfied, and Maestro has accurate links. Use only the approver Gitea identity
+for the merge. Do not change code or approve a stale head. Use only the
+installed nq-approve-merge launcher for Gitea inspection and merging. Merge
+only into dev; never merge into main. If any gate is
+missing, refuse the merge and give the exact missing evidence. Report the PR,
+reviewed head, resulting merge commit, and target branch.
+
+Broker syntax: `nq-approve-merge inspect PR_NUMBER` or
+`nq-approve-merge merge PR_NUMBER REVIEWED_HEAD REVIEW_FILE`. Run one broker
+command per Bash call. The broker validates the current PR and review again
+before merging; do not substitute an ad hoc Gitea command.

.opencode/agents/developer.md

@@ -0,0 +1,21 @@
+---
+description: Implement one assigned NestQuest task in an isolated worktree
+mode: primary
+model: openrouter/z-ai/glm-5.3-flash
+permission:
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+---
+
+You are the NestQuest development agent. Implement only the assigned Maestro
+task in the supplied worktree. Follow the task's acceptance criteria and the
+repository's instructions. Run relevant tests, commit on the task branch, and
+report the commit and test results. Keep changes inside the assigned worktree.
+Do not approve your own pull request. You may merge your task PR into the
+feature branch only after the independent reviewer approved its exact current
+head and the controller verified every task merge gate. Never merge a feature
+into dev or a release into main. Do not start another task, change role, or
+use another model. Do not read or print credential files except when the
+approved task merge requires the existing Gitea development credential.

.opencode/agents/orchestrator.md

@@ -0,0 +1,60 @@
+---
+description: Reconcile NestQuest work and dispatch the next verified action
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  doom_loop: deny
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/opencode/tool-output/*": allow
+---
+
+You are the NestQuest controller. Work in the NestQuest repository. Maestro is
+the source of truth for feature and task state; CTXD is the source of truth for
+project instructions. At the start of every invocation, read the current
+NestQuest context in CTXD, including OPENCODE-ORCHESTRATOR-PROMPT.MD, then
+reconcile it with Maestro, Git, pull requests, and checks before dispatching.
+Follow the review, identity, and branch rules in that prompt.
+If the CTXD project or prompt is unavailable, do not dispatch or merge work;
+report the missing source and end with ORCHESTRATOR_STATE: BLOCKED.
+
+One invocation is a controller tick, not an entire feature lifetime. Prefer a
+state-changing action over another identical status query. Never repeat an
+unchanged tool call three times. If work is asynchronous, wait or inspect a
+specific changed result. Do not claim that you are continuing while ending
+the turn without naming the next action.
+
+The NESTQUEST_CONTROL_HOME environment variable names the installed launchers
+(normally /home/overseer/.local/share/nestquest-controller).
+For implementation, run "$NESTQUEST_CONTROL_HOME/scripts/nq-agent" with role
+developer, a task worktree, title, and task prompt file. For independent
+review, run "$NESTQUEST_CONTROL_HOME/scripts/nq-review" with the worktree,
+feature base ref, exact head ref, review prompt file, PR number, and an output
+file under /tmp/opencode. It publishes an exact-head Gitea approval only after
+Claude approves. The developer may merge
+a task PR into its feature branch only after independent approval of the exact
+head and verification of every task gate. For feature-to-dev approval and
+merge, run "$NESTQUEST_CONTROL_HOME/scripts/nq-agent" with role approver in
+a separate session after the independent review. Save the Claude review output
+in a file under /tmp/opencode and give that file and its reviewed head to the
+approver. Never substitute a different model or reviewer silently.
+
+When a feature is integrated into dev, reconcile Maestro, then immediately
+select and dispatch the next eligible feature. Feature completion is a
+transition, not the end of the controller's job. A release awaiting Joshua's
+main merge does not prevent work on independent eligible features.
+
+End each invocation with exactly one final line using one of these values:
+
+ORCHESTRATOR_STATE: CONTINUE
+ORCHESTRATOR_STATE: QUIESCENT
+ORCHESTRATOR_STATE: BLOCKED
+
+Use CONTINUE when there is any eligible or in-flight work; include the feature,
+task, and next concrete action immediately above the final line. Use QUIESCENT
+only after verifying no eligible or in-flight work remains in Maestro and the
+repository. Use BLOCKED only when a specific decision or access is required;
+include evidence and the needed human action. If you cannot establish the
+state, use BLOCKED. Never emit a success claim based only on a child's summary.

.opencode/agents/terminal-orchestrator.md

@@ -0,0 +1,31 @@
+---
+description: Run the NestQuest orchestration loop in this foreground terminal
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  doom_loop: deny
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/opencode/tool-output/*": allow
+---
+
+You are the foreground NestQuest orchestrator. The user explicitly launched
+this session to run the development queue now. Read the supplied terminal
+orchestrator prompt and current CTXD project context, but follow the
+FOREGROUND TERMINAL RUNTIME for this session instead of CTXD's service runtime
+section.
+
+Continuously reconcile Maestro, CTXD, Git, pull requests, checks, and child
+agent results. Execute the next useful transition in this same session. Do
+not finish after dispatch, review, remediation, or merge while eligible work
+remains. Use the installed role launchers for developer, reviewer, and
+approver isolation. Never start or wait for the systemd controller service.
+Never repeat an identical unchanged tool call three times; wait on the
+specific child or inspect newly changed evidence.
+
+End only at a global terminal condition, an explicit user stop, a genuine
+global access/decision block with no other eligible work, or a host-forced
+yield. On a forced yield, return a continuation checkpoint that can be
+resumed in the same OpenCode session.

.opencode/commands/start-development.md

@@ -0,0 +1,11 @@
+---
+description: Run the NestQuest orchestrator now in this OpenCode terminal
+agent: terminal-orchestrator
+---
+
+Run the NestQuest project queue now in this foreground OpenCode session.
+Read the current CTXD prompt and Maestro state, but use the FOREGROUND
+TERMINAL RUNTIME instead of the service runtime. Reconcile repository and
+pull-request state, then execute CONTROLLER_TICK repeatedly until a global
+terminal condition, explicit user stop, genuine global block, or host-forced
+yield. Do not start or wait for the systemd controller.

ORCHESTRATION.md

@@ -0,0 +1,77 @@
+# NestQuest foreground orchestrator
+
+OpenCode 1.18.32 loads the named agents from `.opencode/agents/`. Their
+models match the current NestQuest CTXD prompt: DeepSeek V4.1 Flash for the
+foreground orchestrator and approver, and GLM 5.3 Flash for development.
+Run orchestration directly from a shell:
+
+```bash
+nq-orchestrate
+nq-orchestrate mission.md
+cat mission.md | nq-orchestrate -
+nq-orchestrate --print-prompt > nestquest-orchestrator.md
+```
+
+The launcher renders the project prompt with the foreground terminal runtime,
+stops the dormant legacy service, refuses immediately when another NestQuest
+TUI is open, and then replaces itself with OpenCode using
+`terminal-orchestrator`. There is no background polling process and no wait
+for a controller tick. Exit or interrupt the TUI to stop the foreground run;
+resume that OpenCode session when a host-forced yield needs continuation.
+
+`scripts/nq-agent` launches developer and approver sessions with fixed agent
+definitions and no `--auto` flag. Headless OpenCode runs use `--pure` so the
+global idle-notification plugin does not notify on every controller tick.
+The approver's shell permission permits only the installed
+`nq-approve-merge` broker for Gitea. That broker requires exact-head
+Claude approval evidence, an exact-head Gitea approval by `review_agent`,
+the `dev` target, a mergeable PR, and passing configured checks before it
+requests a squash merge with Gitea's atomic `head_commit_id` guard.
+`scripts/nq-review` launches the independent
+Claude review in a noninteractive read-only session in the task worktree,
+checks the head again afterward, saves
+the output under `/tmp/opencode`, and posts the Gitea approval.
+The approver verifies the reviewed head again before a merge.
+
+The terminal launcher uses a stable copy of this configuration and scripts
+at `/home/overseer/.local/share/nestquest-controller`; it does not depend on
+which task branch is checked out in the primary NestQuest directory. Install
+that copy, run `scripts/nq-controller --check`, and verify the OpenCode
+agents (terminal-orchestrator, developer, and approver)
+with `opencode debug agent <name>` while `OPENCODE_CONFIG_DIR` points at the
+installed `.opencode` directory. Install `scripts/nq-orchestrate` in
+`~/.local/bin/`. For the global slash command, also install
+`.opencode/agents/terminal-orchestrator.md` under
+`~/.config/opencode/agents/` and
+`deploy/opencode-global-commands/start-nestquest-development.md` under
+`~/.config/opencode/commands/`. The old `nestquest-controller.service` remains static and
+inactive only for migration safety; foreground launch stops it.
+
+Inside an already-open OpenCode TUI, `/start-development` (or the global
+`/start-nestquest-development`) switches to the same foreground
+`terminal-orchestrator` behavior immediately. The shell launcher is the
+preferred entry point when supplying a mission prompt file.
+
+`templates/ORCHESTRATOR-PROMPT.template.md` and
+`templates/nestquest.profile.json` make the current CTXD cycle prompt
+adaptable to another project. See `templates/README.md` before publishing a
+rendered prompt for a new project.
+
+The CTXD preflight reads the configured HTTP/MCP server's NestQuest prompt.
+It deliberately does not inspect `/home/overseer/.ctx/ctxd.db`, which belongs
+to a different local store and lacks this project.
+
+All four agent credentials are currently readable by the same Unix account.
+The Gitea review and merge gates enforce normal workflow sequencing, but
+they are not a hard isolation boundary against a process running as that
+account. Strong isolation requires separate OS identities and protected
+credentials for the controller, reviewer, and approver.
+
+The terminal runtime repeatedly executes CONTROLLER_TICK within the foreground
+session. Neither a feature merge nor a progress report ends the run while
+eligible work remains. A host-forced yield returns a continuation checkpoint
+that can be resumed in the same OpenCode session.
+
+Do not put tokens in this repository or in unit files. Existing OpenCode MCP
+connections supply CTXD and Maestro. Rotate those MCP tokens as a coordinated
+operation across every consumer before revoking the old values.

README.md

@@ -174,8 +174,23 @@ is simply a Home Assistant client.
    Assistant user it may also reach other permitted Home Assistant entities
    and services.
 
-2. **Build a dashboard with only the NestQuest panel cards.** Create a
-   Lovelace dashboard whose **URL slug is `nestquest`** (Settings →
+2. **Build a dashboard with only the NestQuest panel cards.** The
+   recommended path is the **zero-config dashboard strategy**: create a
+   Lovelace dashboard whose URL slug is `nestquest` with
+
+   ```yaml
+   strategy:
+     type: custom:nestquest-party
+   ```
+
+   and no views of your own — the strategy generates the party-board and
+   quest-log views (each already in Panel layout) from the household
+   roster at render time. Optional `url_path` and `weather_entity` keys
+   may sit beside `strategy:`. The manual instructions below describe
+   building the two views by hand if you prefer not to use the strategy.
+
+   **Manual alternative:** create a Lovelace dashboard whose **URL slug
+   is `nestquest`** (Settings →
    Dashboards → Edit → URL slug). A functional panel needs **two** views
    in that dashboard, each with its own card config from
    `design/ENTITIES-AND-SERVICES.md` §4. Give the views these exact URL

custom_components/nestquest/__init__.py

@@ -1,375 +1,78 @@
-"""The NestQuest integration."""
+"""The NestQuest integration (Feature 18: a thin client of the NestQuest API service).
+
+The integration owns NO database: the API service (Feature 16) owns the
+SQLite file, the migrations, and every business rule.  Setup builds the
+entry's ONE shared API client, the coordinator that polls the panel
+snapshot through it, and the SSE subscription that re-fires the API's
+transition frames on the HA bus, registers the single
+``nestquest.complete_quest`` proxy service, registers the zero-config
+panel dashboard (Feature 20), and forwards the sensor and
+binary_sensor platforms.
+"""
 from __future__ import annotations
 
-import asyncio
-import datetime
 import inspect
-import sqlite3
 from collections.abc import Callable
 from dataclasses import dataclass
-from pathlib import Path
 from typing import Any
-from zoneinfo import ZoneInfo
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import ConfigEntryNotReady
-from homeassistant.helpers.event import async_track_time_change
 
 from .const import (
-    CONF_ADMIN_USER_IDS,
+    CONF_SNAPSHOT_STALENESS,
     CONF_UPDATE_INTERVAL,
+    DEFAULT_SNAPSHOT_STALENESS,
     DEFAULT_UPDATE_INTERVAL,
     DOMAIN,
     LOGGER,
     PLATFORMS,
 )
-from .core.settings import NestQuestSettings
+from .coordinator import NestQuestCoordinator, coordinator_client_from_entry
+from .dashboard import async_register_dashboard
 from .frontend import async_register_frontend
-from .coordinator import NestQuestCoordinator
-from .db import NestQuestDatabase, make_database
-from .materialize import materialize as _materialize_run
-from .migrations import apply_migrations
 from .services import async_deregister_services, async_register_services
-from .store import async_get_db_path
-from .admin_allowlist import seed_setup_admin
-from .sweep import run_missed_sweep
+from .sse import NestQuestEventStream
 
 _LOGGER = LOGGER
 
-#: SQLite reports "file is not a database" for corruption in every
-#: sqlite3 version this integration targets; the version-specific
-#: "encrypted or malformed" spelling (3.41+) maps to the same failure.
-_CORRUPTION_MARKERS = (
-    "file is not a database",
-    "database disk image is malformed",
-    "encrypted or malformed",
-    "is not a database",
-)
-
-#: Primary sqlite error codes that mean "the file is corrupt" (SQLite
-#: result codes, https://www.sqlite.org/c3ref/c_abort.html).  Extended
-#: codes carry the primary code in their low byte, so the match is on
-#: errcode & 0xff.
-_CORRUPT_PRIMARY_CODES = frozenset({11, 26})  # SQLITE_CORRUPT, SQLITE_NOTADB
-
-
-def _is_corruption_error(error: BaseException) -> bool:
-    """Return True when ``error`` indicates a corrupt database file.
-
-    Classification order: sqlite_errorcode (Python 3.11+) is primary
-    and locale-independent — SQLITE_CORRUPT and SQLITE_NOTADB, matched
-    on the primary byte so extended codes (SQLITE_CORRUPT_VTAB etc.)
-    classify correctly too.  Message matching is the fallback for
-    older Pythons: the corruption spellings are the documented English
-    texts; a non-English locale could evade them, but the code check
-    already covers every locale on supported Pythons.
-    """
-    if not isinstance(error, sqlite3.DatabaseError):
-        return False
-    errorcode = getattr(error, "sqlite_errorcode", None)
-    if errorcode is not None and (errorcode & 0xFF) in _CORRUPT_PRIMARY_CODES:
-        return True
-    message = str(error).lower()
-    return any(marker in message for marker in _CORRUPTION_MARKERS)
-
-
-async def _preflight_existing_file(
-    hass: HomeAssistant, db_path: Path
-) -> None:
-    """Detect corruption in an EXISTING file before it is opened read-write.
-
-    Opening read-write persists WAL mode — for a rollback-journal file
-    that rewrites the header byte 18/19 and can create -wal/-shm
-    sidecars — which would modify a corrupt file before detection and
-    break the leave-untouched guarantee.  This preflight therefore
-    validates the WHOLE file with a READ-ONLY connection (mode=ro +
-    immutable=1 URI, PRAGMA integrity_check, run on the executor like
-    every other DB call): corruption anywhere fails there, before
-    anything is written.  ``immutable=1`` is SQLite's documented
-    guarantee that the connection performs NO writes and creates NO
-    sidecars — even a WAL-header file gets its -wal/-shm reads served
-    without creating the shared-memory file.  Missing/empty files skip
-    the preflight (they are created fresh by the real open).  All
-    filesystem stat/URI work runs inside the executor job with the
-    probe so the event loop never touches disk.
-    """
-    def _probe() -> None:
-        # The file-state check and URI construction live inside the
-        # executor job: exists/stat/resolve are disk I/O.
-        if not db_path.exists():
-            return
-        # A zero-byte file is neither missing nor a valid database: it
-        # is a corrupt (truncated-to-nothing) existing file, likely an
-        # interrupted first write.  The leave-untouched contract applies
-        # to it too: refuse rather than silently initialize over it.
-        if db_path.stat().st_size == 0:
-            raise sqlite3.DatabaseError(
-                "existing database file is empty (zero bytes): file is "
-                "not a database"
-            )
-        # Properly escape the path: '#'/'?'/'%' in a directory or file
-        # name would otherwise be parsed as URI fragments/parameters/
-        # escapes.  immutable=1: SQLite guarantees no writes and no
-        # sidecar creation from this connection.
-        uri = db_path.resolve().as_uri() + "?mode=ro&immutable=1"
-        conn = sqlite3.connect(uri, uri=True)
-        try:
-            row = conn.execute("PRAGMA integrity_check").fetchone()
-        finally:
-            conn.close()
-        verdict = row[0] if row else "missing"
-        if verdict != "ok":
-            # A non-ok integrity verdict IS corruption: raise with the
-            # verdict text (which matches the corruption markers) and
-            # the NOTADB code so classification is code-based.
-            raise sqlite3.DatabaseError(
-                f"integrity_check verdict {verdict!r} on read-only "
-                f"probe: file is not a database"
-            )
-
-    try:
-        # Every DB-touching call goes through the executor (the mock
-        # harness's async_add_executor_job is awaitable too).
-        await hass.async_add_executor_job(_probe)
-    except sqlite3.DatabaseError as err:
-        # Non-ok integrity verdicts are corruption, full stop: there is
-        # no benign reading of a failed whole-file integrity check, so
-        # ANY DatabaseError out of the probe that carries a corruption
-        # marker or code propagates as corruption.  Only exotic probe
-        # failures that classify as non-corruption (e.g. a transient
-        # 'database is locked' on the read) are downgraded to a debug
-        # log, letting the real open path surface them.
-        if _is_corruption_error(err):
-            raise
-        raise sqlite3.DatabaseError(
-            f"read-only corruption probe of {db_path} failed: {err}"
-        ) from err
-
-async def _async_open_database(
-    hass: HomeAssistant, db_path: Path
-) -> NestQuestDatabase:
-    """Open the NestQuest database, mapping failure modes for setup.
-
-    Three startup cases (Feature 02 done-condition):
-
-    - file missing: SQLite creates it fresh on open — no special path,
-      migrations stamp version 1 on the next step.
-    - file present and valid: opens normally.
-    - file present but corrupt: log an ERROR with the path, close
-      anything opened, and raise ConfigEntryNotReady so HA retries —
-      the file is left byte-for-byte untouched so the owner can
-      restore a backup.  No code path here deletes or overwrites an
-      existing database file.
-
-    Corruption can surface at EITHER stage: a truncated header fails
-    in the read-only preflight (before the file is ever opened
-    read-write), while damaged later pages fail during migrations —
-    the preflight guarantees no WAL sidecar or header write happens
-    on a corrupt file before it is detected.  Both are classified the
-    same way.
-    """
-    try:
-        await _preflight_existing_file(hass, db_path)
-        database = await make_database(hass).open(db_path)
-    except asyncio.CancelledError:
-        raise
-    except sqlite3.DatabaseError as err:
-        if _is_corruption_error(err):
-            _LOGGER.error(
-                "NestQuest database at %s is corrupt: %s. Refusing to "
-                "start with a corrupt database; the file was left "
-                "untouched so a backup can be restored. Home Assistant "
-                "will retry setup.",
-                db_path,
-                err,
-            )
-            raise ConfigEntryNotReady(
-                f"NestQuest database corrupt: {db_path}"
-            ) from err
-        # open() failed for a non-corruption reason (locked file,
-        # permission problem): retryable, but nothing was opened.
-        _LOGGER.error(
-            "NestQuest database at %s failed to open: %s. Home "
-            "Assistant will retry setup.",
-            db_path,
-            err,
-        )
-        raise ConfigEntryNotReady(
-            f"NestQuest database unavailable: {db_path}"
-        ) from err
-    try:
-        await apply_migrations(database)
-    except (sqlite3.DatabaseError, RuntimeError) as err:
-        await database.close()
-        if _is_corruption_error(err):
-            _LOGGER.error(
-                "NestQuest database at %s is corrupt: %s. Refusing to "
-                "start with a corrupt database; the file was left "
-                "untouched so a backup can be restored. Home Assistant "
-                "will retry setup.",
-                db_path,
-                err,
-            )
-            raise ConfigEntryNotReady(
-                f"NestQuest database corrupt: {db_path}"
-            ) from err
-        # A non-corruption failure (e.g. a locked file, a future schema
-        # version) is also a retryable setup problem, but without the
-        # corruption framing.
-        _LOGGER.error(
-            "NestQuest database at %s failed to open: %s. Home "
-            "Assistant will retry setup.",
-            db_path,
-            err,
-        )
-        raise ConfigEntryNotReady(
-            f"NestQuest database unavailable: {db_path}"
-        ) from err
-    except asyncio.CancelledError:
-        await database.close()
-        raise
-    return database
-
 
 @dataclass
 class NestQuestRuntimeData:
     """Runtime data stored on a NestQuest config entry."""
 
     entry_id: str
-    settings: NestQuestSettings
-    database: NestQuestDatabase
     remove_update_listener: Callable[[], Any]
-    remove_time_change_listener: Callable[[], Any]
     coordinator: Any = None
-
-
-async def _async_owner_user_ids(hass: HomeAssistant) -> list[str]:
-    """Return every Home Assistant owner-account user id.
-
-    The last-resort admin seed: when no persisted allowlist copy and no
-    flow-context user survive to first setup, the HA owner accounts are
-    seeded so the household is never left with zero admins (an empty
-    allowlist fails closed, which would lock the household out of its
-    own integration).  Owner accounts can already do everything in HA,
-    so granting NestQuest admin is not a privilege escalation.
-    """
-    auth = getattr(hass, "auth", None)
-    if auth is None:
-        return []
-    users = await auth.async_get_users()
-    owners = [
-        user.id
-        for user in users
-        if getattr(user, "is_owner", False) and getattr(user, "id", None)
-    ]
-    return owners
-
-
-async def _run_horizon_materialization(
-    hass: HomeAssistant,
-    database: NestQuestDatabase,
-    settings: NestQuestSettings,
-) -> None:
-    """Materialize the rolling horizon ``[today, today + horizon_days]``.
-
-    "today" is computed in HA local time (``hass.config.time_zone``) rather
-    than the system clock, so the horizon tracks the household's own day.
-    The walk itself runs through :func:`~.materialize.materialize`, whose DB
-    access is executor-only.
-
-    This is the ONE generation path: the startup backfill, the daily rollover
-    listener and the ``regenerate`` service all funnel through it, so there is
-    no duplicated materialization logic.  ``settings`` (REQUIRED — there is no
-    silent default; every caller already passes the entry's validated
-    :class:`NestQuestSettings`) carries the configured ``horizon_days``.  The
-    window itself comes from :meth:`settings.horizon_window` so the helper is
-    real and shared (not recomputed inline here).
-    """
-    time_zone = ZoneInfo(hass.config.time_zone)
-    today = datetime.datetime.now(time_zone).date()
-    start, end = settings.horizon_window(today)
-    await _materialize_run(database, start.isoformat(), end.isoformat(), today=today)
-
-
-def _register_day_rollover_listener(
-    hass: HomeAssistant,
-    database: NestQuestDatabase,
-    settings: NestQuestSettings,
-) -> Callable[[], Any]:
-    """Register the daily rollover listener and return its remover.
-
-    Fires once per day at the configured local ``day_rollover_time``:
-    first re-materializes the rolling horizon
-    ``[today, today + horizon_days]`` through the shared
-    :func:`_run_horizon_materialization` path (the entry's configured,
-    validated ``horizon_days`` carried on ``settings``), then runs the
-    Feature 11 missed sweep — announcing yesterday's still-open quests
-    as missed AFTER today's instances exist, watermark-guarded so a
-    re-fire of the listener the same night announces nothing twice.
-    """
-    hour, minute = settings.day_rollover_hour_minute
-
-    async def _run_materialization(_now: datetime.datetime) -> None:
-        await _run_horizon_materialization(hass, database, settings)
-        await run_missed_sweep(hass, database)
-
-    return async_track_time_change(
-        hass, _run_materialization, hour=hour, minute=minute
-    )
+    event_stream: NestQuestEventStream | None = None
 
 
 def _find_live_runtime_data(hass: HomeAssistant) -> NestQuestRuntimeData | None:
-    """Return a live runtime record with a connected database, or None.
+    """Return a live runtime record with a coordinator, or None.
 
-    The domain-global services (e.g. ``regenerate``) have no database of
-    their own; they resolve whichever config entry's runtime data is
-    currently live at call time, so none of them can hold a stale handle
-    to a closed connection after another entry unloads.  The record also
-    carries that entry's validated ``settings`` (e.g. the configured
-    horizon) so service handlers read horizon days off it rather than
-    re-reading HA config.
+    The domain-global service (the panel completion proxy) has no
+    database of its own; it resolves whichever config entry's runtime
+    data is currently live at call time, so it cannot hold a stale
+    handle to an unloaded entry's coordinator.
     """
     for runtime_data in hass.data.get(DOMAIN, {}).values():
-        database = getattr(runtime_data, "database", None)
-        if database is not None and database.connected:
+        if getattr(runtime_data, "coordinator", None) is not None:
             return runtime_data
     return None
 
 
-def _make_regenerate_handler(hass: HomeAssistant):
-    """Return the Feature 07 ``regenerate`` handler closed over ``hass``."""
-
-    async def _regenerate(_call: Any) -> None:
-        runtime_data = _find_live_runtime_data(hass)
-        if runtime_data is None:
-            _LOGGER.warning(
-                "NestQuest regenerate requested but no config entry has a "
-                "live database; ignoring"
-            )
-            return
-        await _run_horizon_materialization(
-            hass, runtime_data.database, runtime_data.settings
-        )
-
-    return _regenerate
-
-
 def _register_services(hass: HomeAssistant) -> None:
-    """Register domain-global NestQuest services once.
+    """Register the domain-global NestQuest service once.
 
-    Services are DOMAIN-global — registered exactly once (guarded by
-    ``has_service`` on regenerate) and NOT bound to any config entry —
-    so each handler resolves the currently-live database at call time
+    The service is DOMAIN-global — registered exactly once (guarded by
+    ``has_service``) and NOT bound to any config entry — so the panel
+    completion proxy resolves the currently-live runtime at call time
     and a name collision or duplicate setup is impossible.  Removal is
     handled by the unload path only once the LAST entry is removed
     (see :func:`_deregister_services`).
     """
-    async_register_services(
-        hass,
-        find_runtime=_find_live_runtime_data,
-        regenerate_handler=_make_regenerate_handler(hass),
-    )
+    async_register_services(hass, find_runtime=_find_live_runtime_data)
 
 
 def _deregister_services(hass: HomeAssistant) -> None:
@@ -386,48 +89,14 @@ async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up NestQuest from a config entry."""
     await async_register_frontend(hass)
+    # The zero-config panel dashboard (Feature 20): register the
+    # storage-mode strategy dashboard if no dashboard under the stable
+    # url_path exists yet.  Unavailability of the Lovelace dashboards
+    # collection (YAML mode, lovelace not loaded) logs a warning and
+    # NEVER fails setup; an existing dashboard — ours or the user's —
+    # is left untouched, so a reload cannot duplicate it.
+    await async_register_dashboard(hass)
     hass.data.setdefault(DOMAIN, {})
-    existing = hass.data[DOMAIN].get(entry.entry_id)
-    if existing is not None:
-        db = getattr(existing, "database", None)
-        if db is None or not db.connected:
-            # Reopen through the SAME safety path as first setup: a
-            # record without a live connection (a previous setup's
-            # close-on-failure, or a hand-replaced file) must get the
-            # missing/valid/corrupt classification too, never a raw
-            # sqlite3 error and never skipped migrations — and the
-            # same allowlist seeding, so a reopened fresh file is
-            # never ownerless.
-            db = await _async_open_database(
-                hass, await async_get_db_path(hass)
-            )
-            try:
-                stored_admin_ids = (
-                    entry.options.get(CONF_ADMIN_USER_IDS)
-                    or entry.data.get(CONF_ADMIN_USER_IDS)
-                )
-                context = getattr(entry, "context", None)
-                context_user_id = (
-                    context.get("user_id")
-                    if isinstance(context, dict)
-                    else None
-                )
-                await seed_setup_admin(
-                    db,
-                    stored_admin_ids=stored_admin_ids,
-                    context_user_id=context_user_id,
-                    owner_ids=await _async_owner_user_ids(hass),
-                )
-            except BaseException:
-                # A seeding failure must not leak the just-opened
-                # connection: close it before the error propagates, so
-                # HA's setup retry starts from a clean handle (the
-                # first-setup path closes symmetrically).
-                await db.close()
-                raise
-            existing.database = db
-        entry.runtime_data = existing
-        return True
 
     async def _async_update_listener(
         listener_hass: HomeAssistant, listener_entry: ConfigEntry
@@ -435,109 +104,94 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         """Reload the entry when its options change."""
         await listener_hass.config_entries.async_reload(listener_entry.entry_id)
 
-    database = await _async_open_database(hass, await async_get_db_path(hass))
     remove_update_listener: Callable[[], Any] | None = None
-    remove_time_change_listener: Callable[[], Any] | None = None
     coordinator: Any = None
+    event_stream: NestQuestEventStream | None = None
     try:
-        # Seed the admin allowlist on first setup so the owner is never
-        # locked out: an empty database takes the persisted admin copy
-        # — the options flow's saved list first (it is the current
-        # one), else the config flow's user from entry data — and only
-        # then the HA user still present on the entry context.  No-op
-        # on a non-empty list (fail-closed narrowing is deliberate).
-        stored_admin_ids = (
-            entry.options.get(CONF_ADMIN_USER_IDS)
-            or entry.data.get(CONF_ADMIN_USER_IDS)
-        )
-        context = getattr(entry, "context", None)
-        context_user_id = (
-            context.get("user_id")
-            if isinstance(context, dict)
-            else None
-        )
-        owner_ids = await _async_owner_user_ids(hass)
-        await seed_setup_admin(
-            database,
-            stored_admin_ids=stored_admin_ids,
-            context_user_id=context_user_id,
-            owner_ids=owner_ids,
-        )
-        # Build the explicit settings object from entry.options ONCE: the
-        # horizon materialization and the daily-rollover listener both
-        # consume it, so core never reads HA config itself.  A malformed
-        # stored option falls back PER FIELD (via from_options_resilient)
-        # so a single bad sibling option cannot reset the user's
-        # horizon_days or day_rollover_time — the two fields core
-        # consumes — to their defaults.
-        settings = NestQuestSettings.from_options_resilient(entry.options)
         remove_update_listener = entry.add_update_listener(_async_update_listener)
-        remove_time_change_listener = _register_day_rollover_listener(
-            hass, database, settings
-        )
-        # Backfill any days the daily listener missed while the integration
-        # was off (or freshly installed): run the one idempotent walk over
-        # [today, today + horizon_days] once at setup, using the entry's
-        # configured horizon.  This runs through the SAME path as the daily
-        # listener and regenerate service.
-        await _run_horizon_materialization(hass, database, settings)
-        # The missed sweep runs at startup too (Feature 11): if HA was
-        # down at the rollover time, the previous night's still-open
-        # quests are announced as missed now instead of waiting for
-        # the next midnight.  Watermark-guarded, so this is a no-op
-        # when the night's sweep already ran.
-        await run_missed_sweep(hass, database)
         _register_services(hass)
-        # The shared Feature 10 coordinator: one refresh cycle every
-        # entity reads from (CONF_UPDATE_INTERVAL seconds, default
-        # five minutes).  Created AFTER services so a failure below
-        # unwinds them through the except path's listener handling.
+        # ONE API client for the entry, shared by the coordinator's
+        # snapshot polling, the SSE subscription, and the completion
+        # proxy (the client is stateless — one session, one connection
+        # pool).  An entry with no panel token yet gets the
+        # typed-error stub (unavailable entities, never a setup crash).
+        api_client = coordinator_client_from_entry(hass, entry)
+        # The shared coordinator: one refresh cycle every entity reads
+        # from (CONF_UPDATE_INTERVAL seconds, default five minutes).
+        # It polls the API service's panel snapshot; a failed poll
+        # keeps the entities rendering the last-good snapshot within
+        # CONF_SNAPSHOT_STALENESS, unavailable past it.
         coordinator = NestQuestCoordinator(
             hass,
             entry_id=entry.entry_id,
-            database=database,
-            settings=settings,
+            api_client=api_client,
             update_interval_seconds=entry.options.get(
                 CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL
             ),
+            staleness_seconds=entry.options.get(
+                CONF_SNAPSHOT_STALENESS, DEFAULT_SNAPSHOT_STALENESS
+            ),
         )
-        await coordinator.async_config_entry_first_refresh()
+        # The panel event subscription (the SSE task): a background
+        # task consumes the API service's transition-event stream and
+        # re-fires the four documented HA bus events.  It reuses the
+        # coordinator's client, so it only starts when that client
+        # actually offers a stream — an unconfigured-token stub (or a
+        # test snapshot client without ``stream_events``) leaves it
+        # unstarted, and the typed-error path already covers
+        # availability for those entries.
+        if callable(getattr(api_client, "stream_events", None)):
+            event_stream = NestQuestEventStream(hass, api_client)
+            event_stream.start()
         runtime_data = NestQuestRuntimeData(
             entry_id=entry.entry_id,
-            settings=settings,
-            database=database,
             remove_update_listener=remove_update_listener,
-            remove_time_change_listener=remove_time_change_listener,
             coordinator=coordinator,
+            event_stream=event_stream,
         )
-        # runtime_data is assigned BEFORE the platforms forward so each
-        # platform's async_setup_entry reads its coordinator off the
-        # entry (the HA runtime-data contract); a forward failure below
-        # unwinds it through the except path.
+        # The runtime record is registered BEFORE the first refresh:
+        # the service proxy resolves the entry's runtime state through
+        # hass.data, and it must find the live coordinator there —
+        # never a half-set-up entry.  The platforms forward below reads
+        # the coordinator off the entry (the HA runtime-data contract);
+        # a forward failure below unwinds it through the except path.
+        hass.data[DOMAIN][entry.entry_id] = runtime_data
         entry.runtime_data = runtime_data
+        # The first refresh polls the API snapshot; an API failure
+        # (unconfigured token, API service down) does NOT crash setup:
+        # the coordinator reports last_update_success=False, entities
+        # come up unavailable, and HA's standard retry cycle applies
+        # once the API is reachable.  HA's real
+        # ``async_config_entry_first_refresh`` wraps ANY failed update
+        # pass in ConfigEntryNotReady — the original error survives
+        # only as ``__cause__``, never as the raised exception — so the
+        # catch keys on ConfigEntryNotReady, NOT on the typed API
+        # error.  Everything else (a platform-forward failure,
+        # cancellation) still unwinds through the except block below.
+        try:
+            await coordinator.async_config_entry_first_refresh()
+        except ConfigEntryNotReady:
+            pass
         await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
     except BaseException:
-        # A failure anywhere after the database is open must not leak the
-        # listeners already registered against that (now-closed) database:
-        # unwind EVERY remover we acquired before the failure, keeping the
-        # original error as the one raised.  Removal is best-effort — a
-        # failing remover must not mask the setup error that triggered it.
-        for remove_listener in (
-            remove_time_change_listener,
-            remove_update_listener,
-        ):
-            if remove_listener is None:
-                continue
+        # A failure anywhere after the listener was registered must not
+        # leak it (or the SSE task): unwind EVERYTHING acquired before
+        # the failure, keeping the original error as the one raised.
+        # Removal is best-effort — a failing step must not mask the
+        # setup error that triggered it.
+        if event_stream is not None:
             try:
-                result = remove_listener()
-                if inspect.isawaitable(result):
-                    await result
+                await event_stream.stop()
+            except BaseException:
+                pass
+        if remove_update_listener is not None:
+            try:
+                remove_update_listener()
             except BaseException:
                 pass
         # A coordinator created before the failure holds entity
-        # listeners pointed at the database being closed below —
-        # shut it down FIRST so no scheduled refresh can ever run
-        # against a closed connection.
+        # listeners pointed at the never-registered runtime — shut it
+        # down so no scheduled refresh outlives the failed setup.
         if coordinator is not None:
             try:
                 await coordinator.async_shutdown()
@@ -545,13 +199,20 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
                 pass
         # A platform-forward failure reached this unwind AFTER
         # runtime_data was assigned: clear it so no later unload path
-        # closes the already-closed database through the stale record.
+        # re-invokes the already-consumed update-listener remover
+        # through the stale record.
         if getattr(entry, "runtime_data", None) is not None:
             entry.runtime_data = None
-        await database.close()
+        # The runtime record was ALSO registered in hass.data before
+        # the first refresh: remove it here on ANY failure, or a later
+        # unload picks up the stale, already-torn-down record
+        # (hass.data wins over entry.runtime_data there) and
+        # re-invokes the already-consumed update-listener remover.
+        hass.data.get(DOMAIN, {}).pop(entry.entry_id, None)
         raise
-    assert remove_update_listener is not None
-    assert remove_time_change_listener is not None
+    # The runtime record was already registered before the first
+    # refresh; re-assert the (unchanged) record so the return path
+    # stays readable as one registration site.
     hass.data[DOMAIN][entry.entry_id] = runtime_data
     return True
 
@@ -566,58 +227,50 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     if runtime_data is None:
         runtime_data = getattr(entry, "runtime_data", None)
     # Platforms unload FIRST (mirroring HA conventions): entity
-    # listeners must not outlive the database and coordinator the
-    # teardown below closes.
+    # listeners must not outlive the coordinator the teardown below
+    # shuts down.
     platforms_unloaded = await hass.config_entries.async_unload_platforms(
         entry, PLATFORMS
     )
     if platforms_unloaded is False and runtime_data is not None:
         # Home Assistant KEPT one or more platforms loaded — their
-        # entities still live and must keep their database.  Restore
+        # entities still live and must keep their coordinator.  Restore
         # the runtime record popped above and report failure so HA
         # retries the unload later instead of leaving live entities
-        # backed by a closed database.
+        # backed by a torn-down coordinator.
         hass.data.setdefault(DOMAIN, {})[entry.entry_id] = runtime_data
         return False
     unload_error: BaseException | None = None
     if runtime_data is not None:
-        remove_update_listener = getattr(runtime_data, "remove_update_listener", None)
-        remove_time_change_listener = getattr(
-            runtime_data, "remove_time_change_listener", None
+        # The SSE subscription is stopped FIRST: its task must be gone
+        # (no frame can fire) before anything else is torn down.
+        event_stream = getattr(runtime_data, "event_stream", None)
+        if event_stream is not None:
+            stop_stream = getattr(event_stream, "stop", None)
+            if stop_stream is not None:
+                await stop_stream()
+        remove_update_listener = getattr(
+            runtime_data, "remove_update_listener", None
         )
         try:
-            for remove_listener in (
-                remove_update_listener,
-                remove_time_change_listener,
-            ):
-                if remove_listener is None:
-                    continue
-                try:
-                    result = remove_listener()
-                    if inspect.isawaitable(result):
-                        await result
-                except BaseException as err:
-                    # Cancel EVERY listener even when an earlier remover
-                    # raises: a skipped remover would leave a daily
-                    # callback firing against a closed database after
-                    # unload.  The first error is retained and re-raised
-                    # only after both removers (and the DB close) ran.
-                    if unload_error is None:
-                        unload_error = err
+            if remove_update_listener is not None:
+                result = remove_update_listener()
+                if inspect.isawaitable(result):
+                    await result
+        except BaseException as err:
+            # A failing remover must not skip the coordinator shutdown
+            # below; the first error is retained and re-raised only
+            # after the teardown ran.
+            if unload_error is None:
+                unload_error = err
         finally:
-            # The coordinator's entity listeners must stop BEFORE the
-            # database closes: a scheduled refresh starting during the
-            # close await would touch a cleared connection.  (The
-            # platform unload above already removed the entities; this
-            # clears the coordinator's own remaining listeners.)
+            # The coordinator's entity listeners must stop here: a
+            # scheduled refresh must never outlive the unload.
             coordinator = getattr(runtime_data, "coordinator", None)
             if coordinator is not None:
                 shutdown = getattr(coordinator, "async_shutdown", None)
                 if shutdown is not None:
                     await shutdown()
-            database = getattr(runtime_data, "database", None)
-            if database is not None:
-                await database.close()
     # Domain-global services are torn down only once the FINAL entry
     # unloads (``hass.data[DOMAIN]`` is now empty), never when a sibling
     # entry is still loaded.

custom_components/nestquest/admin_allowlist.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.admin_allowlist` for the integration package.
-
-The admin allowlist business layer lives in
-:mod:`custom_components.nestquest.core.admin_allowlist` (extracted in
-task 510c1f78); this module re-exports it so existing
-``from .admin_allowlist import ...`` references inside the integration
-keep working.
-"""
-from __future__ import annotations
-
-from .core.admin_allowlist import *  # noqa: F401,F403

custom_components/nestquest/api_client.py

@@ -0,0 +1,414 @@
+"""Panel-plane API client for the NestQuest integration (Feature 18).
+
+The integration talks to the NestQuest API service (Feature 16) over
+HTTP instead of reading the database: this module is the ONE place that
+speaks the API's panel plane — ``GET /api/v1/panel/snapshot`` (today's
+household snapshot) and ``POST /api/v1/panel/instances/{id}/complete``
+(completion as the tapped child profile) — authenticated with the
+static panel service token as a Bearer credential on every request.
+
+Transport-injected by construction: the constructor takes the base URL,
+the panel token, and the HTTP session to use.  The session speaks the
+aiohttp ``ClientSession`` surface (``request(method, url, headers=...,
+json=...)`` returning an async context manager whose response carries
+``status`` and ``await text()``), so tests stub the transport with NO
+network and NO aiohttp installed; production builds the client through
+:func:`client_from_entry`, which hands in Home Assistant's shared
+aiohttp session (``homeassistant.helpers.aiohttp_client
+.async_get_clientsession``).  The module itself imports NEITHER
+homeassistant NOR aiohttp at runtime (aiohttp appears only behind
+``TYPE_CHECKING`` for annotations), so the client is usable anywhere —
+the HA coupling lives in the one production factory.
+
+Every failure is typed: a transport failure (connection refused, DNS
+failure, timeout — the exchange never produced a response) and every
+non-2xx HTTP response raise :class:`NestQuestApiError`.  The error
+carries the HTTP status where there is one (so 401 and 404 are
+distinguishable at the call site) and ``None`` when there is not; the
+original transport error is chained as ``__cause__`` — nothing is
+swallowed.  There are NO retries and the client logs nothing: refresh
+cadence is the coordinator's concern (the next task), and the panel
+token is a secret that must never reach a log line or an error
+message — the error texts name the method, path, and status only.
+
+The panel plane's SSE event stream (``GET /api/v1/panel/events``) is
+exposed by :meth:`NestQuestApiClient.stream_events` — an async
+generator yielding ``(event_type, payload)`` per Server-Sent Events
+frame (``event: <type>`` / ``data: <json>`` lines separated by a blank
+line).  Opening the stream gets the same one-timeout, typed-error
+contract as every other call; reading it has NO body-wide timeout (a
+healthy stream is long-lived — the subscription manager owns
+reconnection and backoff).
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+from .const import (
+    CONF_API_BASE_URL,
+    CONF_PANEL_TOKEN,
+    DEFAULT_API_BASE_URL,
+    DEFAULT_PANEL_TOKEN,
+)
+
+if TYPE_CHECKING:
+    import aiohttp
+
+__all__ = [
+    "COMPLETE_INSTANCE_PATH",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "EVENTS_PATH",
+    "NestQuestApiError",
+    "NestQuestApiClient",
+    "SNAPSHOT_PATH",
+    "client_from_entry",
+    "is_valid_base_url",
+    "resolve_api_config",
+]
+
+#: The panel plane's snapshot route (Feature 16).
+SNAPSHOT_PATH = "/api/v1/panel/snapshot"
+
+#: The panel plane's SSE event-stream route (Feature 16): each
+#: transition arrives as an ``event: <type>`` / ``data: <json>`` frame.
+EVENTS_PATH = "/api/v1/panel/events"
+
+#: The panel plane's completion route template (Feature 16); the
+#: ``{instance_id}`` placeholder is filled per call.
+COMPLETE_INSTANCE_PATH = "/api/v1/panel/instances/{instance_id}/complete"
+
+#: Request timeout, in seconds.  One attempt, one timeout: a hung API
+#: call surfaces as a typed error for the coordinator to report, never
+#: a retry loop.
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+
+class NestQuestApiError(Exception):
+    """A failed NestQuest API exchange, raised for every failure mode.
+
+    ``status`` carries the HTTP status when a response arrived (a
+    non-2xx response — 401 for a bad token, 404 for an unknown
+    instance) and is ``None`` when the exchange failed at the transport
+    level (connection refused, DNS failure, timeout) — so callers
+    distinguish the two with ``is_transport_error``.  The original
+    transport error, where there is one, is chained as ``__cause__``.
+    Messages carry the method, path, and status — never the request
+    headers, so the panel token can never leak through an error.
+    """
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+    @property
+    def is_transport_error(self) -> bool:
+        """True when the exchange failed before any response arrived."""
+        return self.status is None
+
+
+def is_valid_base_url(value: object) -> bool:
+    """Return True when ``value`` is a usable API base URL.
+
+    A full ``http://`` or ``https://`` URL with a host — the exact
+    shape the options flow validates (form ergonomics) and the client
+    constructor enforces (fail fast, never build requests against a
+    scheme-less or host-less string).
+    """
+    if not isinstance(value, str):
+        return False
+    candidate = value.strip()
+    if not candidate:
+        return False
+    parsed = urlparse(candidate)
+    return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+
+
+def resolve_api_config(entry: Any) -> tuple[str, str]:
+    """Resolve ``(base_url, panel_token)`` off a config entry.
+
+    Precedence mirrors the options flow's stored-values resolution:
+    ``entry.options`` first (the live options-flow copy), then
+    ``entry.data`` (the config-flow-era copy), then the const defaults.
+    The token is a secret: callers must never log the returned pair.
+    """
+    options = getattr(entry, "options", None) or {}
+    data = getattr(entry, "data", None) or {}
+
+    def _pick(key: str, default: str) -> str:
+        if key in options:
+            return options[key]
+        if key in data:
+            return data[key]
+        return default
+
+    return (
+        _pick(CONF_API_BASE_URL, DEFAULT_API_BASE_URL),
+        _pick(CONF_PANEL_TOKEN, DEFAULT_PANEL_TOKEN),
+    )
+
+
+def client_from_entry(hass: Any, entry: Any) -> NestQuestApiClient:
+    """Build the production client for a config entry.
+
+    Reads the configured base URL and panel token off the entry
+    (:func:`resolve_api_config`) and hands the client Home Assistant's
+    SHARED aiohttp session (``homeassistant.helpers.aiohttp_client
+    .async_get_clientsession``) so panel calls ride HA's one connection
+    pool.  The helper import is deferred into this function on purpose:
+    the test harness is mock-only and the module must import (and the
+    client must be stub-transport testable) without homeassistant or
+    aiohttp installed.
+    """
+    from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+    base_url, panel_token = resolve_api_config(entry)
+    return NestQuestApiClient(
+        base_url, panel_token, async_get_clientsession(hass)
+    )
+
+
+class NestQuestApiClient:
+    """Async client for the NestQuest API service's panel plane.
+
+    ONE instance per config entry (the coordinator task wires it into
+    the refresh cycle).  The client is deliberately thin: it adds the
+    Bearer credential and the base URL, enforces one timeout per
+    request, and turns every failure into :class:`NestQuestApiError` —
+    no business logic, no retries, no caching.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        panel_token: str,
+        session: aiohttp.ClientSession,
+        *,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        """Store the connection settings; the session is injected.
+
+        ``session`` is an aiohttp ``ClientSession`` in production and a
+        stub transport in tests.  ``base_url`` must be a full http(s)
+        URL and ``panel_token`` must be non-empty — a client built
+        without either can only fail later at request time with a
+        less-explicable error, so construction fails fast instead.
+        """
+        if not is_valid_base_url(base_url):
+            raise ValueError(
+                f"base_url must be a full http(s) URL, got {base_url!r}"
+            )
+        if not isinstance(panel_token, str) or not panel_token.strip():
+            raise ValueError("panel_token must be a non-empty string")
+        if (
+            not isinstance(timeout_seconds, (int, float))
+            or isinstance(timeout_seconds, bool)
+            or timeout_seconds <= 0
+        ):
+            raise ValueError(
+                f"timeout_seconds must be a positive number, got {timeout_seconds!r}"
+            )
+        self._base_url = base_url.strip().rstrip("/")
+        self._panel_token = panel_token
+        self._session = session
+        self._timeout_seconds = float(timeout_seconds)
+
+    async def get_snapshot(self) -> dict[str, Any]:
+        """Fetch and parse today's household snapshot.
+
+        Returns the JSON the snapshot route returns (``today_iso``,
+        ``cycle_day``, and the per-child list — see
+        ``api/routes_panel.py`` for the documented shape).  Raises
+        :class:`NestQuestApiError` on transport failure, timeout, or a
+        non-2xx response.
+        """
+        return await self._request_json("GET", SNAPSHOT_PATH)
+
+    async def complete_instance(
+        self, instance_id: int, actor_child_id: int
+    ) -> dict[str, Any]:
+        """Complete one quest instance as the tapped child profile.
+
+        POSTs ``{"actor_child_id": actor_child_id}`` to the complete
+        route and returns the parsed response body (the route answers
+        ``{"status": ...}`` both for a first completion and for an
+        idempotent repeat, so a retried panel tap succeeds).  Raises
+        :class:`NestQuestApiError` on transport failure, timeout, or a
+        non-2xx response — 401 for a wrong token, 404 for an unknown
+        instance.
+        """
+        path = COMPLETE_INSTANCE_PATH.format(instance_id=instance_id)
+        return await self._request_json(
+            "POST", path, json_body={"actor_child_id": actor_child_id}
+        )
+
+    async def stream_events(
+        self,
+    ) -> AsyncIterator[tuple[str, dict[str, Any]]]:
+        """Yield ``(event_type, payload)`` for every panel SSE frame.
+
+        Opens ``GET /api/v1/panel/events`` with the Bearer credential
+        and parses the Server-Sent Events framing the API service
+        emits: ``event: <type>`` and ``data: <json>`` lines closed by a
+        blank line (one frame per transition event; a frame's ``data``
+        may span several ``data:`` lines, joined with newlines — the
+        standard SSE rule).  Line splits across chunk boundaries are
+        buffered, so frames are parsed correctly whatever chunking the
+        transport produces.
+
+        Opening the stream carries the SAME one-timeout, typed-error
+        contract as every other call: a non-2xx response raises
+        :class:`NestQuestApiError` with its status and a transport
+        failure (connection refused, DNS, the open timing out) raises
+        one with ``status=None`` and the original error chained.  The
+        reading loop itself has NO timeout — a healthy stream is
+        long-lived — but any failure raised from the transport
+        mid-stream raises typed as well, so the consumer can reconnect.
+        A frame whose ``data`` is not valid JSON is a protocol failure
+        and raises typed, carrying the response status it arrived
+        with.  Cancellation is never converted: closing the generator
+        (``aclose``, i.e. the consumer's task being cancelled) stops
+        cleanly and closes the underlying response in every path.
+        """
+        url = f"{self._base_url}{EVENTS_PATH}"
+        headers = {"Authorization": f"Bearer {self._panel_token}"}
+        # Opening the response gets ONE request timeout, exactly like
+        # ``_request_json``; the read loop below runs WITHOUT one — a
+        # body-wide timeout would kill a healthy long-lived stream.
+        # The response context manager is entered manually (not via
+        # ``async with``) because the block must span the yields below;
+        # the ``finally`` closes it on EVERY exit path.
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                stream_cm = self._session.request(
+                    "GET", url, headers=headers, json=None
+                )
+                response = await stream_cm.__aenter__()
+        except asyncio.CancelledError:
+            # Cancellation is never converted (see ``_request_json``).
+            raise
+        except NestQuestApiError:
+            raise
+        except Exception as err:
+            raise NestQuestApiError(
+                f"NestQuest API GET {EVENTS_PATH} transport failure: {err}",
+                status=None,
+            ) from err
+
+        status = response.status
+        if not 200 <= status < 300:
+            await self._close_stream(stream_cm)
+            raise NestQuestApiError(
+                f"NestQuest API GET {EVENTS_PATH} failed with HTTP {status}",
+                status=status,
+            )
+
+        try:
+            event_type: str | None = None
+            data_lines: list[str] = []
+            buffer = ""
+            async for chunk in response:
+                if isinstance(chunk, (bytes, bytearray)):
+                    chunk = chunk.decode("utf-8")
+                buffer += chunk
+                while "\n" in buffer:
+                    line, buffer = buffer.split("\n", 1)
+                    if line.startswith("event:"):
+                        event_type = line[len("event:"):].strip()
+                    elif line.startswith("data:"):
+                        data_lines.append(line[len("data:"):].strip())
+                    elif not line and event_type is not None:
+                        # A blank line ends the frame.  A trailing
+                        # incomplete frame (stream ends without its
+                        # closing blank line) is discarded, per the
+                        # SSE spec's treatment of incomplete events.
+                        try:
+                            payload = json.loads("\n".join(data_lines))
+                        except ValueError as err:
+                            raise NestQuestApiError(
+                                f"NestQuest API GET {EVENTS_PATH} "
+                                f"delivered a malformed SSE frame: {err}",
+                                status=status,
+                            ) from err
+                        yield event_type, payload
+                        event_type = None
+                        data_lines = []
+        except asyncio.CancelledError:
+            raise
+        except NestQuestApiError:
+            raise
+        except Exception as err:
+            raise NestQuestApiError(
+                f"NestQuest API GET {EVENTS_PATH} transport failure: {err}",
+                status=None,
+            ) from err
+        finally:
+            await self._close_stream(stream_cm)
+
+    @staticmethod
+    async def _close_stream(stream_cm: Any) -> None:
+        """Close an opened streaming response context manager.
+
+        Works for aiohttp's response context manager (whose
+        ``__aexit__`` is a coroutine) and for test stubs that return
+        either a coroutine or a plain value.
+        """
+        result = stream_cm.__aexit__(None, None, None)
+        if inspect.isawaitable(result):
+            await result
+
+    async def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        """Run ONE request and return the parsed JSON body.
+
+        The Bearer token rides the Authorization header only.  A
+        non-2xx response raises :class:`NestQuestApiError` with its
+        status; anything the transport raises (connection, timeout) is
+        wrapped as a transport-level :class:`NestQuestApiError` with
+        the original error chained — never swallowed, never retried.
+        A 2xx body that is not valid JSON is a protocol failure and
+        raises typed too, carrying the status it arrived with.
+        """
+        url = f"{self._base_url}{path}"
+        headers = {"Authorization": f"Bearer {self._panel_token}"}
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                async with self._session.request(
+                    method, url, headers=headers, json=json_body
+                ) as response:
+                    status = response.status
+                    if not 200 <= status < 300:
+                        raise NestQuestApiError(
+                            f"NestQuest API {method} {path} failed with "
+                            f"HTTP {status}",
+                            status=status,
+                        )
+                    body_text = await response.text()
+        except asyncio.CancelledError:
+            # Cancellation is never converted: a shutting-down event
+            # loop must stop, not read a synthesized API error.
+            raise
+        except NestQuestApiError:
+            raise
+        except Exception as err:
+            raise NestQuestApiError(
+                f"NestQuest API {method} {path} transport failure: {err}",
+                status=None,
+            ) from err
+        try:
+            return json.loads(body_text)
+        except ValueError as err:
+            raise NestQuestApiError(
+                f"NestQuest API {method} {path} returned malformed "
+                f"JSON: {err}",
+                status=status,
+            ) from err

custom_components/nestquest/children.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.children` for the integration package.
-
-The children registry business layer lives in
-:mod:`custom_components.nestquest.core.children` (extracted in
-task 510c1f78); this module re-exports it so existing
-``from .children import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.children import *  # noqa: F401,F403

custom_components/nestquest/completion.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.completion` for the integration package.
-
-The completion business layer lives in
-:mod:`custom_components.nestquest.core.completion` (extracted in
-task 510c1f78); this module re-exports it so existing
-``from .completion import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.completion import *  # noqa: F401,F403

custom_components/nestquest/config_flow.py

@@ -7,7 +7,7 @@ from homeassistant import config_entries
 from homeassistant.core import callback
 from homeassistant.data_entry_flow import FlowResult
 
-from .const import CONF_ADMIN_USER_IDS, DOMAIN
+from .const import DOMAIN
 
 
 class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
@@ -30,11 +30,11 @@ class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
     ) -> FlowResult:
         """Handle the user step of the config flow.
 
-        The HA user completing the flow is persisted into the entry
-        data as the initial admin allowlist copy: real HA does not
-        guarantee the flow context survives to setup, and entry data is
-        the persisted record first setup seeds from — the owner is
-        never locked out.
+        The integration needs no configuration to start (the API
+        connection is set in the options flow), so the user input is
+        stored as-is.  The former admin-allowlist copy is gone: with
+        the database removed the allowlist lives in the API service's
+        own store, not on the entry.
         """
         await self.async_set_unique_id(DOMAIN, raise_on_progress=False)
         if self._async_in_progress() or self._async_current_entries():
@@ -43,12 +43,4 @@ class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
         if user_input is None:
             return self.async_show_form(step_id="user")
 
-        data = dict(user_input)
-        flow_user_id = (
-            self.context.get("user_id")
-            if isinstance(self.context, dict)
-            else None
-        )
-        if flow_user_id:
-            data[CONF_ADMIN_USER_IDS] = [flow_user_id]
-        return self.async_create_entry(title="NestQuest", data=data)
+        return self.async_create_entry(title="NestQuest", data=dict(user_input))

custom_components/nestquest/coordinator.py

@@ -1,4 +1,4 @@
-"""The shared NestQuest DataUpdateCoordinator (Feature 10).
+"""The shared NestQuest DataUpdateCoordinator (Feature 10, Feature 18).
 
 ONE refresh pass builds the whole entity snapshot: active children,
 today's instances with their derived states (open / done / missed via
@@ -7,54 +7,81 @@ per-child rollup counts.  Every Feature 10 entity reads
 ``coordinator.data`` — no entity queries the database itself, so one
 refresh updates the whole board coherently.
 
-"Today" and "now" are HA-local (``hass.config.time_zone``), never the
-host clock and never UTC, matching the materialization and completion
-layers.
+Since Feature 18 the snapshot no longer comes from the local database:
+the coordinator polls the NestQuest API service's panel plane —
+``GET /api/v1/panel/snapshot`` through
+:class:`~.api_client.NestQuestApiClient` on its update interval — and
+RECONSTRUCTS the same core dataclasses the local builder produced
+(:class:`~.core.snapshot.NestQuestSnapshot`,
+:class:`~.core.snapshot.ChildDaySnapshot`,
+:class:`~.core.snapshot.QuestInstanceView`).  ``sensor.py`` and
+``binary_sensor.py`` read ``coordinator.data`` and
+:func:`~.core.snapshot.instance_payload` exactly as before, so every
+entity_id and attribute payload shape is unchanged: the panel cards and
+the four blueprints keep working untouched.
 
-The snapshot assembly itself lives in the Home-Assistant-free
-:mod:`custom_components.nestquest.core.snapshot` module
-(:func:`~core.snapshot.build_snapshot`); this coordinator is now a thin
-HA wrapper that resolves the local timezone and reads the settings handed
-into its constructor, then delegates to that builder, passing the SAME
-HA-local ``now`` it resolved in one clock read.  The API service's panel
-snapshot route shares the same builder, so both consumers render ONE
-snapshot shape.
+One loss is deliberate and documented (D-009 revisited): the panel
+payload OMITS missed instances, so a snapshot rebuilt from the API can
+no longer carry them — ``admin_instances`` (``include_missed=True``)
+now equals ``instances`` (they can hold only open and completed rows).
+The admin surface for missed quests is the PWA, which reads the API
+service directly; the integration's entities never needed missed rows
+for their states or counts (the counts arrive precomputed).
 
-Presence is resolved through the SAME engine the materializer uses
-(:class:`~.presence.PresenceEngine`): schedules and overrides are read
-with the public DAO methods and the engine's anchor-date arithmetic
-answers ``is this child at this house today`` (D-004 — never ISO week
-parity).
+Failure handling: constructing the client fails fast (ValueError) when
+the entry has no panel token configured, and a fetch failure raises the
+typed :class:`~.api_client.NestQuestApiError`.  Neither crashes
+integration setup: the constructor logs a clear message and hands back
+a client-shaped stub whose refresh raises the same typed error, and
+``_async_update_data`` converts every typed error into
+:class:`~homeassistant.helpers.update_coordinator.UpdateFailed` — the
+exception a HA ``DataUpdateCoordinator`` records as a failed pass
+(``last_update_success = False``, ``data = None``), so the entities
+come up unavailable.  The typed error is never swallowed silently: it
+is logged with its message and chained into the UpdateFailed.  (The
+conversion matters at setup: HA's real
+``async_config_entry_first_refresh`` wraps any failed pass in
+``ConfigEntryNotReady``, so a setup that keys on the original
+exception type would never match it.)
 
-``cycle_day`` reports where today falls in the custody cycle of the
-first active child (display order) that HAS a schedule — 1-based day
-``N`` of ``cycle_length_weeks * 7``, computed from that schedule's
-anchor date.  ``0`` means no active child has a schedule at all, so
-the admin header degrades to a harmless zero instead of guessing.
+Last-good cache and staleness: every successful pass refreshes a cache
+of the rebuilt snapshot stamped with the :func:`time.monotonic`
+instant of the success.  A typed failure is checked against that stamp
+BEFORE the pass is declared failed: within the configured staleness
+threshold (``CONF_SNAPSHOT_STALENESS``, seconds, default three update
+intervals) the pass SUCCEEDS with the cached snapshot — the panel
+keeps rendering last-good data and the entities stay available — and
+the outage is logged as a warning.  Entities go unavailable only once
+the cache is older than the threshold (or before the first success);
+a later successful fetch refreshes the cache and the entities recover
+on their own, without a config-entry reload.
 """
 from __future__ import annotations
 
 import asyncio
 import datetime
-from zoneinfo import ZoneInfo
+import time
+from typing import Any
 
 from homeassistant.core import HomeAssistant
-from homeassistant.helpers.update_coordinator import DataUpdateCoordinator
+from homeassistant.helpers.update_coordinator import (
+    DataUpdateCoordinator,
+    UpdateFailed,
+)
 
+from .api_client import NestQuestApiClient, NestQuestApiError, resolve_api_config
 from .const import (
     CONF_UPDATE_INTERVAL,
+    DEFAULT_SNAPSHOT_STALENESS,
     DEFAULT_UPDATE_INTERVAL,
     DOMAIN,
     LOGGER,
     MIN_UPDATE_INTERVAL,
 )
-from .core.db import NestQuestDatabase
-from .core.settings import NestQuestSettings
 from .core.snapshot import (
     ChildDaySnapshot,
     NestQuestSnapshot,
     QuestInstanceView,
-    build_snapshot,
 )
 
 __all__ = [
@@ -65,9 +92,131 @@ __all__ = [
 ]
 
 
+def snapshot_from_api_payload(payload: dict[str, Any]) -> NestQuestSnapshot:
+    """Reconstruct the core snapshot dataclasses from the API's JSON.
+
+    The panel snapshot route (``api/routes_panel.py``) returns today's
+    household as plain JSON — ``today_iso``, ``cycle_day``, and the
+    per-child list with precomputed counts and the instances in the
+    documented payload shape.  This function maps that shape BACK onto
+    the dataclasses ``sensor.py`` / ``binary_sensor.py`` read, field by
+    field:
+
+    - the API's ``state`` ``"completed"`` maps back to the core view's
+      ``"done"`` (so :func:`~.core.snapshot.instance_payload` renders
+      ``"completed"`` again — the round-trip is identity for open and
+      completed rows);
+    - ``overdue``, ``on_time`` (→ ``was_on_time``), ``completed_at``,
+      ``window``, ``due_time``, ``icon`` and the per-child counts pass
+      through verbatim;
+    - ``present`` and ``next_present`` pass through verbatim (the API
+      resolved them through the same presence engine server-side);
+    - the instance list is rebuilt IN ORDER, so the panel payload the
+      sensors emit matches the route's order byte for byte.
+
+    Because the route omits missed instances (D-009), a snapshot built
+    here cannot contain any ``missed`` view — see the module docstring.
+    """
+    children: list[ChildDaySnapshot] = []
+    for child in payload.get("children", []):
+        views = tuple(
+            QuestInstanceView(
+                instance_id=instance["id"],
+                definition_id=instance["definition_id"],
+                child_id=instance["child_id"],
+                title=instance["title"],
+                icon=instance.get("icon"),
+                window=instance["window"],
+                # The API payload does not carry due_date: every row
+                # is TODAY's instance (the route queries
+                # [today, today]), so the view's due_date is the
+                # snapshot's today_iso — the same value the local
+                # builder stamped on every today row.
+                due_date=payload["today_iso"],
+                due_time=instance.get("due_time"),
+                state=(
+                    "done" if instance["state"] == "completed" else
+                    instance["state"]
+                ),
+                overdue=instance["overdue"],
+                completed_at=instance.get("completed_at"),
+                was_on_time=instance.get("on_time"),
+            )
+            for instance in child.get("instances", [])
+        )
+        children.append(
+            ChildDaySnapshot(
+                child_id=child["child_id"],
+                child_name=child["child_name"],
+                instances=views,
+                present=child["present"],
+                due_today=child["due_today"],
+                completed_today=child["completed_today"],
+                remaining_today=child["remaining_today"],
+                completion_pct=child["completion_pct"],
+                next_present=child.get("next_present"),
+            )
+        )
+    return NestQuestSnapshot(
+        today_iso=payload["today_iso"],
+        children=tuple(children),
+        cycle_day=payload["cycle_day"],
+    )
+
+
+class _UnconfiguredApiClient:
+    """Client-shaped stand-in used when the entry has no panel token.
+
+    Constructing a real :class:`~.api_client.NestQuestApiClient` with an
+    empty token raises ValueError by design (fail fast on a client that
+    could only ever 401).  An entry that simply has not been configured
+    yet must not crash integration setup, so the coordinator swaps in
+    this stub: every refresh raises the SAME typed
+    :class:`~.api_client.NestQuestApiError` a transport failure would,
+    carrying a clear "API not configured" message;
+    :meth:`NestQuestCoordinator._async_update_data` converts it to
+    :class:`~homeassistant.helpers.update_coordinator.UpdateFailed`, so
+    the coordinator marks the entities unavailable and the HA standard
+    retry cycle applies.  The error is logged, never silent.
+    """
+
+    __slots__ = ()
+
+    async def get_snapshot(self) -> dict[str, Any]:
+        """Always raise: there is no configured API to fetch from."""
+        raise NestQuestApiError(
+            "NestQuest API not configured: set the panel token in the "
+            "integration options"
+        )
+
+
+def _monotonic() -> float:
+    """The monotonic clock the staleness math reads.
+
+    A one-line indirection over :func:`time.monotonic` so the staleness
+    tests can drive the clock deterministically (patch THIS function,
+    never the stdlib clock).  Monotonic is deliberate: wall-clock jumps
+    (NTP corrections, suspends) must not shorten or extend the window.
+    """
+    return time.monotonic()
+
+
 class NestQuestCoordinator(DataUpdateCoordinator):
     """Shared refresh cycle for every NestQuest entity.
 
+    One refresh pass = one ``GET /api/v1/panel/snapshot`` through the
+    API client, reconstructed into the core snapshot dataclasses every
+    entity reads.  A failed pass (unconfigured API, transport failure,
+    non-2xx response) raises the typed error out of the client;
+    ``_async_update_data`` converts it to
+    :class:`~homeassistant.helpers.update_coordinator.UpdateFailed`, the
+    exception HA's coordinator machinery records as a failed pass: the
+    coordinator's ``data`` keeps its last good value while
+    ``last_update_success`` goes False — HA marks the entities
+    unavailable until a later pass succeeds.  An unexpected
+    non-typed error still propagates out of ``_async_update_data``
+    and is logged (with its traceback) by HA's machinery, the same way.
+
     Forced refreshes (the service paths pushing an immediate update
     after a completion) are SERIALIZED per entry: overlapping
     complete/uncomplete calls must not interleave their snapshot
@@ -75,6 +224,15 @@ class NestQuestCoordinator(DataUpdateCoordinator):
     newer one and leave entities wrong until the next poll.  Real
     HA's coordinator already serializes internally; the lock keeps
     the same guarantee on the stand-in and costs nothing upstream.
+
+    Last-good cache: a successful pass stamps the rebuilt snapshot
+    with the :func:`~.coordinator._monotonic` instant of the success;
+    a typed failure within the configured staleness threshold
+    (``staleness_seconds``, from ``CONF_SNAPSHOT_STALENESS``) serves
+    that cached snapshot instead of failing the pass, so a short API
+    outage keeps the board up.  Past the threshold — or before the
+    first success — the pass fails as above, and a later successful
+    pass refreshes the cache and recovers the entities on its own.
     """
 
     def __init__(
@@ -82,9 +240,9 @@ class NestQuestCoordinator(DataUpdateCoordinator):
         hass: HomeAssistant,
         *,
         entry_id: str,
-        database: NestQuestDatabase,
-        settings: NestQuestSettings,
+        api_client: NestQuestApiClient,
         update_interval_seconds: int | None = None,
+        staleness_seconds: int | None = None,
     ) -> None:
         interval = update_interval_seconds
         if (
@@ -93,6 +251,19 @@ class NestQuestCoordinator(DataUpdateCoordinator):
             or interval < MIN_UPDATE_INTERVAL
         ):
             interval = DEFAULT_UPDATE_INTERVAL
+        staleness = staleness_seconds
+        if (
+            not isinstance(staleness, int)
+            or isinstance(staleness, bool)
+            or staleness < interval
+        ):
+            # A missing or nonsensical threshold falls back to the
+            # shipped default; a configured-but-too-short one (below
+            # even one poll interval) falls back to whichever of
+            # default/interval spans at least one failed poll, so the
+            # cache is never dead on arrival.  (The options flow
+            # validates the same rule at the form.)
+            staleness = max(DEFAULT_SNAPSHOT_STALENESS, interval)
         super().__init__(
             hass,
             LOGGER,
@@ -100,9 +271,16 @@ class NestQuestCoordinator(DataUpdateCoordinator):
             update_interval=datetime.timedelta(seconds=interval),
         )
         self.entry_id = entry_id
-        self.database = database
-        self.settings = settings
+        self.api_client = api_client
         self._refresh_lock = asyncio.Lock()
+        #: The configured last-good window, in SECONDS (const.py:
+        #: CONF_SNAPSHOT_STALENESS / DEFAULT_SNAPSHOT_STALENESS).
+        self._staleness_seconds = staleness
+        #: The last-good cache: the snapshot from the most recent
+        #: SUCCESSFUL fetch and the :func:`time.monotonic` instant it
+        #: landed.  Both stay None until the first success.
+        self._last_good_snapshot: NestQuestSnapshot | None = None
+        self._last_good_monotonic: float | None = None
 
     async def async_refresh(self) -> None:
         """One refresh at a time; a queued refresh runs AFTER the
@@ -111,12 +289,98 @@ class NestQuestCoordinator(DataUpdateCoordinator):
         async with self._refresh_lock:
             await super().async_refresh()
 
-    def _local_now(self) -> datetime.datetime:
-        time_zone = ZoneInfo(self.hass.config.time_zone)
-        return datetime.datetime.now(time_zone)
-
     async def _async_update_data(self) -> NestQuestSnapshot:
-        now = self._local_now()
-        return await build_snapshot(
-            self.database, self.settings, now
+        """One refresh pass: fetch the panel snapshot and rebuild it.
+
+        A successful pass rebuilds the snapshot and refreshes the
+        last-good cache (the snapshot plus the
+        :func:`time.monotonic` instant of the success).
+
+        A typed API failure (unconfigured token stub, transport
+        failure, non-2xx response) is first checked against that
+        stamp: WITHIN the configured staleness threshold (elapsed time
+        since the last successful fetch, inclusive of the threshold
+        itself) the pass SUCCEEDS with the cached snapshot — the panel
+        keeps rendering last-good data, the entities stay available —
+        and the outage is logged as a clear warning (never silent).
+        With no cache yet, or past the threshold, the typed error is
+        converted to
+        :class:`~homeassistant.helpers.update_coordinator.UpdateFailed`
+        — the exception HA's coordinator machinery records as a failed
+        pass (``last_update_success = False``, ``data`` unchanged) so
+        entities go unavailable and the setup-time first refresh
+        arrives as ``ConfigEntryNotReady`` — with the typed error
+        logged and chained.  Anything else still propagates.
+        """
+        try:
+            payload = await self.api_client.get_snapshot()
+        except NestQuestApiError as err:
+            now = _monotonic()
+            cached = self._last_good_snapshot
+            fetched_at = self._last_good_monotonic
+            if (
+                cached is not None
+                and fetched_at is not None
+                and now - fetched_at <= self._staleness_seconds
+            ):
+                LOGGER.warning(
+                    "NestQuest API refresh failed (%s); serving the "
+                    "last-good snapshot fetched %.0f s ago, within the "
+                    "%d s staleness threshold",
+                    err,
+                    now - fetched_at,
+                    self._staleness_seconds,
+                )
+                return cached
+            LOGGER.error(
+                "NestQuest coordinator refresh failed: %s", err
+            )
+            raise UpdateFailed(str(err)) from err
+        snapshot = snapshot_from_api_payload(payload)
+        self._last_good_snapshot = snapshot
+        self._last_good_monotonic = _monotonic()
+        return snapshot
+
+
+def coordinator_client_from_entry(
+    hass: HomeAssistant, entry: Any, *, session_factory: Any = None
+) -> Any:
+    """Build the refresh client for a config entry, tolerating no token.
+
+    Reads ``(base_url, panel_token)`` off the entry and constructs the
+    real client.  An entry with no panel token configured (the shipped
+    default is the empty string) makes the constructor raise ValueError
+    by design; integration setup must not crash on an unconfigured
+    entry, so this factory swaps in the typed-error stub instead and
+    logs ONE clear message.  The ValueError itself is never re-raised
+    past this point — it is converted, with the reason logged.
+
+    ``session_factory`` overrides where the HTTP session comes from
+    (production: HA's shared aiohttp session via
+    :func:`~.api_client.client_from_entry`); it exists so tests can
+    inject a stub transport without importing aiohttp — the mock-only
+    test harness has no ``homeassistant.helpers.aiohttp_client``.
+    """
+    base_url, panel_token = resolve_api_config(entry)
+    if not isinstance(panel_token, str) or not panel_token.strip():
+        LOGGER.warning(
+            "NestQuest API panel token is not configured for entry %s: "
+            "entities will stay unavailable until a token is set in the "
+            "integration options",
+            entry.entry_id,
         )
+        return _UnconfiguredApiClient()
+    if session_factory is not None:
+        return NestQuestApiClient(
+            base_url, panel_token, session_factory(hass)
+        )
+    from custom_components.nestquest.api_client import client_from_entry
+
+    return client_from_entry(hass, entry)
+
+
+#: Test seam: entry_id → client, consulted by the conftest's client
+#: factory BEFORE the production path.  Always empty in production
+#: (nothing in the integration writes to it); tests register scripted
+#: clients through it and clear it between tests.
+_COORDINATOR_CLIENT_OVERRIDES: dict[str, Any] = {}

custom_components/nestquest/core/const.py

@@ -20,44 +20,41 @@ TIME_PATTERN = re.compile(r"(?:[01]\d|2[0-3]):[0-5]\d")
 PLATFORMS: list[str] = ["sensor", "binary_sensor"]
 
 # Home Assistant bus events (design/ENTITIES-AND-SERVICES.md §3).  The
-# panel and admin cards listen for these; Feature 10 fires completed,
-# uncompleted, and child_day_complete from the service paths, and
-# Feature 11's nightly sweep fires quest_missed.
+# panel and admin cards listen for these; since Feature 18 the
+# completed/uncompleted/day-complete transitions are published by the
+# API service on its SSE stream and re-fired on the bus by the
+# integration's subscription, and Feature 11's nightly sweep fires
+# quest_missed.
 EVENT_QUEST_COMPLETED = "nestquest_quest_completed"
 EVENT_QUEST_UNCOMPLETED = "nestquest_quest_uncompleted"
 EVENT_QUEST_MISSED = "nestquest_quest_missed"
 EVENT_CHILD_DAY_COMPLETE = "nestquest_child_day_complete"
 
-#: Canonical domain-global service names (design/ENTITIES-AND-SERVICES.md §2
-#: plus the existing Feature 07 regenerate service).
+#: Canonical domain-global service name (design/ENTITIES-AND-SERVICES.md §2).
+#: Since Feature 18 only the panel completion service remains: the admin
+#: surface is the PWA and the API service's admin routes, so the former
+#: HA admin services (uncomplete, quest-definition and presence
+#: management, CSV export, child management, regenerate) are gone.
 SERVICE_COMPLETE_QUEST = "complete_quest"
-SERVICE_UNCOMPLETE_QUEST = "uncomplete_quest"
-SERVICE_CREATE_QUEST_DEFINITION = "create_quest_definition"
-SERVICE_UPDATE_QUEST_DEFINITION = "update_quest_definition"
-SERVICE_SET_QUEST_DEFINITION_ACTIVE = "set_quest_definition_active"
-SERVICE_SET_PRESENCE_PATTERN = "set_presence_pattern"
-SERVICE_CREATE_PRESENCE_OVERRIDE = "create_presence_override"
-SERVICE_DELETE_PRESENCE_OVERRIDE = "delete_presence_override"
-SERVICE_EXPORT_HISTORY_CSV = "export_history_csv"
-SERVICE_MANAGE_CHILD = "manage_child"
-SERVICE_REGENERATE = "regenerate"
 
 DOMAIN_SERVICES: tuple[str, ...] = (
     SERVICE_COMPLETE_QUEST,
-    SERVICE_UNCOMPLETE_QUEST,
-    SERVICE_CREATE_QUEST_DEFINITION,
-    SERVICE_UPDATE_QUEST_DEFINITION,
-    SERVICE_SET_QUEST_DEFINITION_ACTIVE,
-    SERVICE_SET_PRESENCE_PATTERN,
-    SERVICE_CREATE_PRESENCE_OVERRIDE,
-    SERVICE_DELETE_PRESENCE_OVERRIDE,
-    SERVICE_EXPORT_HISTORY_CSV,
-    SERVICE_MANAGE_CHILD,
-    SERVICE_REGENERATE,
 )
 
 SQLITE_DB_FILENAME = "nestquest.db"
 
+# Zero-config panel dashboard (Feature 20): ONE storage-mode Lovelace
+# dashboard registered on setup whose config carries the bundle's
+# ``custom:nestquest-party`` strategy (frontend/src/strategy.ts) — the
+# views are generated at render time from the household roster.  The
+# url_path IS the domain: the stable key idempotency is keyed on (a
+# reload or a second entry never duplicates it, and a dashboard already
+# registered under it — ours or the user's — is left untouched).
+DASHBOARD_URL_PATH = DOMAIN
+DASHBOARD_TITLE = "NestQuest"
+DASHBOARD_ICON = "mdi:party-popper"
+DASHBOARD_STRATEGY_TYPE = "custom:nestquest-party"
+
 # Configuration keys and default values
 CONF_HORIZON_DAYS = "horizon_days"
 DEFAULT_HORIZON_DAYS = 14
@@ -81,6 +78,21 @@ CONF_UPDATE_INTERVAL = "update_interval"
 DEFAULT_UPDATE_INTERVAL = 300
 MIN_UPDATE_INTERVAL = 30
 
+# Last-good snapshot staleness (Feature 18), in SECONDS: how long the
+# coordinator keeps SERVING the last good snapshot after the API stops
+# answering.  A failed poll whose elapsed time since the last successful
+# fetch is within the threshold returns the cached snapshot (the panel
+# keeps rendering last-good data, entities stay available); past it the
+# poll fails the HA way and the entities go unavailable.  The default is
+# 3x the default update interval (900 s = 15 minutes): three consecutive
+# failed five-minute polls before the board is declared stale — enough
+# to ride out an API service restart, short enough not to render a
+# days-old board all day.  Validation floor: the threshold must be at
+# least the configured update interval, or the cache could never span
+# even one failed poll.
+CONF_SNAPSHOT_STALENESS = "snapshot_staleness"
+DEFAULT_SNAPSHOT_STALENESS = 3 * DEFAULT_UPDATE_INTERVAL
+
 # Notification automations (Feature 11).  The notify target is a free-text
 # Home Assistant service name (e.g. "notify.mobile_app_dads_phone") the
 # household fills in — never a hard-coded personal target; the times are
@@ -101,6 +113,32 @@ CONF_END_OF_DAY_REPORT_ENABLED = "end_of_day_report_enabled"
 CONF_CELEBRATION_ENABLED = "celebration_enabled"
 DEFAULT_AUTOMATION_ENABLED = True
 
+# Panel-plane API client (Feature 18): the integration reaches the
+# NestQuest API service (Feature 16) over HTTP instead of the database.
+# The base URL points at the API service host serving ``/api/v1/panel/*``
+# (uvicorn's default host/port is the sensible starting point); the panel
+# service token is the static Bearer credential the panel plane requires
+# (``NESTQUEST_PANEL_TOKEN`` on the API side).  Both are stored on the
+# entry like every other setting — options first, then the entry-data
+# copy, then defaults.  The TOKEN IS A SECRET: it is never logged, never
+# echoed into error messages, and never committed.  The shipped default
+# token IS the empty string (DEFAULT_PANEL_TOKEN) — an entry with no
+# configured token is therefore NOT a working client: the options flow
+# accepts an empty token as "not configured yet" and only rejects
+# malformed (padded/whitespace-only/non-string) values — the actual
+# non-emptiness guard is enforced at client construction, where
+# NestQuestApiClient fails fast on an empty/whitespace token
+# (api_client.py).  So a caller building the client from a bare
+# entry must either ensure a token is configured first or handle the
+# construction ValueError and surface an "API not configured" state —
+# an unconfigured entry never yields a client that can only 401.
+# This mirrors the API service's fail-closed stance (api/config.py: no
+# default token exists).
+CONF_API_BASE_URL = "api_base_url"
+DEFAULT_API_BASE_URL = "http://127.0.0.1:8000"
+CONF_PANEL_TOKEN = "panel_token"
+DEFAULT_PANEL_TOKEN = ""
+
 # Quest windows (D-008): a definition may declare several day windows;
 # each produces its own instance per day and groups the panel's Quest
 # Log into three columns.  The clock ranges are stored here so they stay

custom_components/nestquest/core/service_policy.py

@@ -1,46 +0,0 @@
-"""Explicit admin-only versus open service registry (Feature 09).
-
-One mapping, one file: every registered ``nestquest`` service name is
-either ``open`` or ``admin_only``.  The permission decorator (later
-Feature 09 tasks) reads this table; it does not take per-handler
-policy arguments.
-"""
-from __future__ import annotations
-
-from .const import (
-    DOMAIN_SERVICES,
-    SERVICE_COMPLETE_QUEST,
-    SERVICE_CREATE_PRESENCE_OVERRIDE,
-    SERVICE_CREATE_QUEST_DEFINITION,
-    SERVICE_DELETE_PRESENCE_OVERRIDE,
-    SERVICE_EXPORT_HISTORY_CSV,
-    SERVICE_MANAGE_CHILD,
-    SERVICE_REGENERATE,
-    SERVICE_SET_PRESENCE_PATTERN,
-    SERVICE_SET_QUEST_DEFINITION_ACTIVE,
-    SERVICE_UNCOMPLETE_QUEST,
-    SERVICE_UPDATE_QUEST_DEFINITION,
-)
-
-OPEN = "open"
-ADMIN_ONLY = "admin_only"
-
-SERVICE_POLICY: dict[str, str] = {
-    SERVICE_COMPLETE_QUEST: OPEN,
-    SERVICE_UNCOMPLETE_QUEST: ADMIN_ONLY,
-    SERVICE_CREATE_QUEST_DEFINITION: ADMIN_ONLY,
-    SERVICE_UPDATE_QUEST_DEFINITION: ADMIN_ONLY,
-    SERVICE_SET_QUEST_DEFINITION_ACTIVE: ADMIN_ONLY,
-    SERVICE_SET_PRESENCE_PATTERN: ADMIN_ONLY,
-    SERVICE_CREATE_PRESENCE_OVERRIDE: ADMIN_ONLY,
-    SERVICE_DELETE_PRESENCE_OVERRIDE: ADMIN_ONLY,
-    SERVICE_EXPORT_HISTORY_CSV: ADMIN_ONLY,
-    SERVICE_MANAGE_CHILD: ADMIN_ONLY,
-    SERVICE_REGENERATE: ADMIN_ONLY,
-}
-
-if frozenset(SERVICE_POLICY) != frozenset(DOMAIN_SERVICES):
-    raise RuntimeError(
-        "SERVICE_POLICY must name exactly the registered nestquest services, "
-        f"got {sorted(SERVICE_POLICY)} vs {list(DOMAIN_SERVICES)}"
-    )

custom_components/nestquest/dao_children.py

@@ -1,12 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.dao_children` for the integration package.
-
-The children/admin DAO lives in
-:mod:`custom_components.nestquest.core.dao_children` (extracted in
-task d0b691d8); this module re-exports it so existing
-``from .dao_children import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.dao_children import *  # noqa: F401,F403
-from .core.dao_children import _CONNECTION_LOCKS, _connection_lock  # noqa: F401

custom_components/nestquest/dao_instances.py

@@ -1,12 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.dao_instances` for the integration package.
-
-The instances/completion-events DAO lives in
-:mod:`custom_components.nestquest.core.dao_instances`
-(extracted in task d0b691d8); this module re-exports it so existing
-``from .dao_instances import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.dao_instances import *  # noqa: F401,F403
-from .core.dao_instances import _resolve_today  # noqa: F401

custom_components/nestquest/dao_meta.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.dao_meta` for the integration package.
-
-The meta-state DAO lives in
-:mod:`custom_components.nestquest.core.dao_meta` (extracted in task
-d0b691d8); this module re-exports it so existing
-``from .dao_meta import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.dao_meta import *  # noqa: F401,F403

custom_components/nestquest/dao_presence.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.dao_presence` for the integration package.
-
-The presence DAOs live in
-:mod:`custom_components.nestquest.core.dao_presence` (extracted in
-task d0b691d8); this module re-exports them so existing
-``from .dao_presence import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.dao_presence import *  # noqa: F401,F403

custom_components/nestquest/dao_rules.py

@@ -1,17 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.dao_rules` for the integration package.
-
-The schedule-rules/quest-definitions DAO lives in
-:mod:`custom_components.nestquest.core.dao_rules` (extracted in task
-d0b691d8); this module re-exports it so existing
-``from .dao_rules import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.dao_rules import *  # noqa: F401,F403
-from .core.dao_rules import (  # noqa: F401
-    _UNSET,
-    _validate_date,
-    _validate_time,
-    _validate_window,
-)

custom_components/nestquest/dashboard.py

@@ -0,0 +1,215 @@
+"""Zero-config panel dashboard registration for NestQuest (Feature 20).
+
+On setup the integration registers ONE storage-mode Lovelace dashboard
+whose CONFIG uses the bundle's ``custom:nestquest-party`` strategy (see
+``frontend/src/strategy.ts``): the views themselves are GENERATED at
+render time from the household roster, so the stored dashboard config
+carries nothing but the strategy reference.
+
+Registration mirrors the REAL two-step sequence the lovelace
+integration itself uses when it creates the onboarding map dashboard
+(``homeassistant/components/lovelace/__init__.py``,
+``_create_map_dashboard``):
+
+1. create the dashboard METADATA through the ``DashboardsCollection``
+   (``hass.data["lovelace"]["dashboards_collection"]``) — url_path,
+   title, icon, sidebar visibility.  The strategy reference is NOT part
+   of the create payload: the collection's create schema allows only
+   the metadata fields, so a ``strategy`` key there fails the whole
+   create (this was the silent no-op the first implementation shipped).
+2. save the dashboard CONFIG — ``{"strategy": ...}`` — through the
+   per-url_path CONTENT manager that the collection's change listener
+   registers under ``hass.data["lovelace"]["dashboards"][url_path]``
+   (a ``LovelaceStorage``), exactly the second step HA performs.
+
+Registration is IDEMPOTENT — a dashboard already under the stable
+``url_path`` (ours or a user's) skips BOTH steps and its stored config
+is never overwritten — and the Lovelace surfaces being unavailable
+(YAML mode, lovelace not loaded) is a logged warning, never a setup
+failure.
+"""
+from __future__ import annotations
+
+import asyncio
+
+from homeassistant.core import HomeAssistant
+
+from .const import (
+    DASHBOARD_ICON,
+    DASHBOARD_STRATEGY_TYPE,
+    DASHBOARD_TITLE,
+    DASHBOARD_URL_PATH,
+    LOGGER,
+)
+
+_LOGGER = LOGGER
+
+# Single-flight guard for the check-then-create below: HA can set up
+# several config entries CONCURRENTLY, and two overlapping setups would
+# both pass the exists-check and race on the url_path create.  The lock
+# is per hass instance (kept as an attribute on the hass object, since
+# hass.data is the integrations' shared registry the unload path
+# empties) rather than one module-level asyncio.Lock — a bare
+# module-level lock binds to whichever event loop first awaits it and
+# raises RuntimeError on any other loop, while the race it must prevent
+# only exists between setups running on the SAME hass anyway.
+_REGISTRATION_LOCK_ATTR = "_nestquest_dashboard_registration_lock"
+
+
+def _registration_lock(hass: HomeAssistant) -> asyncio.Lock:
+    """Return the per-hass registration lock, creating it on first use."""
+    lock = getattr(hass, _REGISTRATION_LOCK_ATTR, None)
+    if lock is None:
+        lock = asyncio.Lock()
+        setattr(hass, _REGISTRATION_LOCK_ATTR, lock)
+    return lock
+
+
+def _lovelace_data(hass: HomeAssistant) -> dict | None:
+    """Return ``hass.data["lovelace"]`` when it is the real dict shape.
+
+    The lovelace integration stores a plain DICT of surfaces (``mode``,
+    ``dashboards``, ``dashboards_collection``, ``resources``,
+    ``yaml_dashboards``) under the ``lovelace`` key; anything else
+    (missing key, unexpected object) means the surfaces below cannot be
+    reached and registration must warn and continue.
+    """
+    lovelace_data = hass.data.get("lovelace")
+    if not isinstance(lovelace_data, dict):
+        return None
+    return lovelace_data
+
+
+def _dashboards_collection(hass: HomeAssistant):
+    """Return the Lovelace dashboards METADATA collection, or None.
+
+    The collection lives at ``hass.data["lovelace"]
+    ["dashboards_collection"]`` — NOT under ``["dashboards"]``, which
+    maps url_path to the per-dashboard CONTENT managers
+    (``LovelaceStorage``/``LovelaceYAML``).  A missing key (lovelace
+    not loaded) and a missing/None entry (YAML mode never sets the
+    collection) both mean "cannot create storage dashboards here" —
+    callers log and continue.  The presence of the surface is verified
+    by capability (``async_create_item`` callable), not by type, so no
+    lovelace import is needed.
+    """
+    lovelace_data = _lovelace_data(hass)
+    if lovelace_data is None:
+        return None
+    collection = lovelace_data.get("dashboards_collection")
+    if collection is None or not callable(
+        getattr(collection, "async_create_item", None)
+    ):
+        return None
+    return collection
+
+
+def _dashboard_store(hass: HomeAssistant, url_path: str):
+    """Return a url_path's dashboard CONTENT manager, or None.
+
+    After a metadata create, the collection's change listener registers
+    a ``LovelaceStorage`` for the new dashboard under
+    ``hass.data["lovelace"]["dashboards"][url_path]``; the dashboard
+    CONFIG (the strategy reference) is saved through THAT manager —
+    the second step of HA's own dashboard creation.
+    """
+    lovelace_data = _lovelace_data(hass)
+    if lovelace_data is None:
+        return None
+    dashboards = lovelace_data.get("dashboards")
+    if not isinstance(dashboards, dict):
+        return None
+    store = dashboards.get(url_path)
+    if store is None or not callable(getattr(store, "async_save", None)):
+        return None
+    return store
+
+
+def _item_url_path(item) -> str | None:
+    """Read a dashboard item's ``url_path`` through either access shape.
+
+    The collection hands back storage items as dicts while builtin
+    dashboards come back as config objects; the url_path is reachable
+    through ``item["url_path"]`` or ``item.url_path`` respectively.
+    """
+    url_path = getattr(item, "url_path", None)
+    if isinstance(url_path, str):
+        return url_path
+    get_url_path = getattr(item, "get", None)
+    if callable(get_url_path):
+        value = get_url_path("url_path")
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def _existing_dashboard(items) -> bool:
+    """Whether a dashboard under the stable url_path already exists."""
+    return any(_item_url_path(item) == DASHBOARD_URL_PATH for item in items)
+
+
+async def async_register_dashboard(hass: HomeAssistant) -> bool:
+    """Register the NestQuest panel dashboard exactly once.
+
+    Returns True when a dashboard under the stable ``url_path`` exists
+    after the call (pre-existing or created here), False when the
+    Lovelace surfaces were unavailable or refused.  A dashboard already
+    registered under the stable ``url_path`` — whether ours from a
+    previous setup or a user's own — skips BOTH steps and is left
+    COMPLETELY alone: its stored config is never overwritten, it is
+    never deleted, never a duplicate.  The strategy config is saved
+    ONLY for the dashboard created in THIS call, whose fresh content
+    store is empty, so the save cannot clobber anything.
+    """
+    collection = _dashboards_collection(hass)
+    if collection is None:
+        _LOGGER.warning(
+            "Lovelace dashboards collection unavailable; the NestQuest "
+            "panel dashboard was not registered. Enable the Lovelace "
+            "integration in storage mode or create a dashboard with "
+            "strategy %s manually.",
+            DASHBOARD_STRATEGY_TYPE,
+        )
+        return False
+    try:
+        # Single-flight: two concurrent entry setups must not both pass
+        # the exists-check and race on the url_path create.
+        async with _registration_lock(hass):
+            # async_items() is a SYNC @callback on the real collection
+            # (helpers/collection.py ObservableCollection) — not awaited.
+            if _existing_dashboard(collection.async_items()):
+                return True
+            await collection.async_create_item(
+                {
+                    "url_path": DASHBOARD_URL_PATH,
+                    "title": DASHBOARD_TITLE,
+                    "icon": DASHBOARD_ICON,
+                    "show_in_sidebar": True,
+                    "allow_single_word": True,
+                }
+            )
+            # Step two (mirroring HA's _create_map_dashboard): the
+            # strategy CONFIG goes through the fresh dashboard's
+            # content manager, not through the metadata collection.
+            store = _dashboard_store(hass, DASHBOARD_URL_PATH)
+            if store is None:
+                _LOGGER.warning(
+                    "The NestQuest panel dashboard was registered but its "
+                    "Lovelace content manager never appeared; add the "
+                    "strategy %s to the dashboard manually.",
+                    DASHBOARD_STRATEGY_TYPE,
+                )
+                return False
+            await store.async_save(
+                {"strategy": {"type": DASHBOARD_STRATEGY_TYPE}}
+            )
+    except Exception:
+        _LOGGER.warning(
+            "Registering the NestQuest panel dashboard in the Lovelace "
+            "dashboards collection failed; set it up manually with "
+            "strategy %s.",
+            DASHBOARD_STRATEGY_TYPE,
+            exc_info=True,
+        )
+        return False
+    return True

custom_components/nestquest/db.py

@@ -1,31 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.db` for the integration package.
-
-The async SQLite wrapper lives in :mod:`custom_components.nestquest.core.db` (extracted in task
-d0b691d8) and is Home-Assistant-free: :class:`NestQuestDatabase` takes
-an executor callable rather than a ``hass`` object.  This module
-re-exports it and provides :func:`make_database`, a thin adapter that
-constructs a wrapper backed by ``hass.async_add_executor_job``, so the
-integration constructs the database the same way it always did.
-"""
-from __future__ import annotations
-
-from typing import Any, TypeVar
-
-from homeassistant.core import HomeAssistant
-
-from .core.db import ExecutionResult, NestQuestDatabase
-
-__all__ = ["ExecutionResult", "NestQuestDatabase", "make_database"]
-
-T = TypeVar("T")
-
-
-def make_database(hass: HomeAssistant) -> NestQuestDatabase:
-    """Construct a :class:`NestQuestDatabase` wired to ``hass``'s executor.
-
-    Mirrors the pre-extraction ``NestQuestDatabase(hass)`` call: the
-    wrapper's executor is ``hass.async_add_executor_job``, so every
-    sqlite3 call runs on the HA executor thread and the event loop
-    never blocks.
-    """
-    return NestQuestDatabase(hass.async_add_executor_job)

custom_components/nestquest/events.py

@@ -1,79 +0,0 @@
-"""Re-export / HA wiring of :mod:`custom_components.nestquest.core.events` for the integration package.
-
-The transition-event payload construction lives in
-:mod:`custom_components.nestquest.core.events` (extracted in
-task 510c1f78) and is HA-free: it builds and RETURNS the events.  This
-shim keeps the integration's old ``fire_quest_completed`` /
-``fire_quest_uncompleted`` API (the complete/uncomplete service
-handlers call them with ``hass``), reads the HA-local timezone from
-``hass.config.time_zone`` to derive ``today``, asks the core builder
-for the events, and fires each on ``hass.bus`` with the documented
-payloads.  The four blueprints keep working with identical payloads.
-
-The completed event is fired BEFORE the day-complete rule evaluates:
-``fire_quest_completed`` asks
-:func:`build_quest_completed_event` for the completed event and fires
-it immediately, THEN reads the HA-local ``today``, asks
-:func:`build_child_day_complete_event` for the day-complete event, and
-fires it (if any) afterwards.  This restores the pre-extraction
-ordering — a failure in the day-complete DB reads or the ZoneInfo
-lookup cannot suppress the completed event.
-"""
-from __future__ import annotations
-
-import datetime
-from zoneinfo import ZoneInfo
-
-from .core.db import NestQuestDatabase
-from .core.events import (
-    build_child_day_complete_event,
-    build_quest_completed_event,
-    build_quest_uncompleted_events,
-)
-
-__all__ = ["fire_quest_completed", "fire_quest_uncompleted"]
-
-
-async def fire_quest_completed(
-    hass,
-    database: NestQuestDatabase,
-    instance_id: int,
-    *,
-    was_on_time: bool | None,
-) -> None:
-    """Fire ``nestquest_quest_completed`` and, when the completion
-    cleared the child's whole day, ``nestquest_child_day_complete``.
-
-    Thin HA wiring over the HA-free
-    :func:`custom_components.nestquest.core.events.build_quest_completed_event`
-    and
-    :func:`build_child_day_complete_event`: the completed event is
-    built and fired FIRST (so a failure in the day-complete DB reads
-    or the HA-local ``today`` lookup cannot suppress it), then the
-    HA-local ``today`` (the day-complete rule's input) is read from
-    ``hass.config.time_zone`` and the day-complete builder is asked
-    whether the child's whole day cleared.  Identical payloads and
-    day-complete rule to the pre-extraction implementation.
-    """
-    completed = await build_quest_completed_event(
-        database,
-        instance_id,
-        was_on_time=was_on_time,
-    )
-    hass.bus.async_fire(*completed)
-
-    today = datetime.datetime.now(ZoneInfo(hass.config.time_zone)).date()
-    day_complete = await build_child_day_complete_event(
-        database, completed[1], today=today
-    )
-    if day_complete is not None:
-        hass.bus.async_fire(*day_complete)
-
-
-async def fire_quest_uncompleted(
-    hass, database: NestQuestDatabase, instance_id: int
-) -> None:
-    """Fire ``nestquest_quest_uncompleted`` for an actual reversal."""
-    events = await build_quest_uncompleted_events(database, instance_id)
-    for event_type, payload in events:
-        hass.bus.async_fire(event_type, payload)

custom_components/nestquest/manifest.json

@@ -7,7 +7,8 @@
   "config_flow": true,
   "dependencies": [
     "frontend",
-    "http"
+    "http",
+    "lovelace"
   ],
   "documentation": "https://github.com/Maniacs-Mansion/NestQuest",
   "integration_type": "hub",

custom_components/nestquest/materialize.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.materialize` for the integration package.
-
-The materialization walk lives in
-:mod:`custom_components.nestquest.core.materialize` (extracted in
-task 510c1f78); this module re-exports it so existing
-``from .materialize import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.materialize import *  # noqa: F401,F403

custom_components/nestquest/migrations.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.migrations` for the integration package.
-
-The versioned migration runner lives in
-:mod:`custom_components.nestquest.core.migrations`
-(extracted in task d0b691d8); this module re-exports it so existing
-``from .migrations import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.migrations import *  # noqa: F401,F403

custom_components/nestquest/options_flow.py

@@ -1,4 +1,15 @@
-"""Options flow for NestQuest post-setup settings."""
+"""Options flow for NestQuest post-setup settings.
+
+Since the DB removal (Feature 18) the integration is a thin client of
+the NestQuest API service: the settings that only served the local
+database (the generation horizon, the day rollover, the notification
+defaults, the admin allowlist) are gone — the API service owns those in
+its own settings store, and the automations take their behaviour from
+blueprint inputs.  What remains is what the CLIENT itself consumes: the
+panel-plane API connection (base URL + token), the shared coordinator's
+refresh interval, the last-good staleness threshold, and the
+panel-facing idle timeout.
+"""
 from __future__ import annotations
 
 from typing import Any
@@ -6,61 +17,39 @@ from typing import Any
 import voluptuous as vol
 from homeassistant import config_entries
 from homeassistant.data_entry_flow import FlowResult
-from homeassistant.helpers import config_validation as cv
 
 from .const import (
-    CONF_ADMIN_USER_IDS,
-    CONF_AFTERNOON_REMINDER_ENABLED,
-    CONF_AFTERNOON_REMINDER_TIME,
-    CONF_CELEBRATION_ENABLED,
-    CONF_DAY_ROLLOVER_TIME,
-    CONF_END_OF_DAY_REPORT_ENABLED,
-    CONF_END_OF_DAY_REPORT_TIME,
-    CONF_HORIZON_DAYS,
-    CONF_MORNING_SUMMARY_ENABLED,
-    CONF_MORNING_SUMMARY_TIME,
-    CONF_NOTIFY_TARGET,
+    CONF_API_BASE_URL,
     CONF_PANEL_IDLE_TIMEOUT,
+    CONF_PANEL_TOKEN,
+    CONF_SNAPSHOT_STALENESS,
     CONF_UPDATE_INTERVAL,
-    DEFAULT_AFTERNOON_REMINDER_TIME,
-    DEFAULT_AUTOMATION_ENABLED,
-    DEFAULT_DAY_ROLLOVER_TIME,
-    DEFAULT_END_OF_DAY_REPORT_TIME,
-    DEFAULT_HORIZON_DAYS,
-    DEFAULT_MORNING_SUMMARY_TIME,
+    DEFAULT_API_BASE_URL,
     DEFAULT_PANEL_IDLE_TIMEOUT,
+    DEFAULT_PANEL_TOKEN,
+    DEFAULT_SNAPSHOT_STALENESS,
     DEFAULT_UPDATE_INTERVAL,
-    DOMAIN,
     MIN_UPDATE_INTERVAL,
-    TIME_PATTERN,
 )
-from .admin_allowlist import list_admin_ids, set_admin_ids
+from .api_client import is_valid_base_url
 
-MIN_HORIZON_DAYS = 1
 MIN_PANEL_IDLE_TIMEOUT = 30
 
 
-def _parse_time(value: str) -> bool:
-    """Return True when value is a valid 24-hour HH:MM string."""
-    return TIME_PATTERN.fullmatch(value) is not None
+def _async_validate(
+    user_input: dict[str, Any],
+    current: dict[str, Any] | None = None,
+) -> dict[str, str]:
+    """Validate user input and return field-level errors instead of raising.
 
-
-def _async_validate(user_input: dict[str, Any]) -> dict[str, str]:
-    """Validate user input and return field-level errors instead of raising."""
+    ``current`` carries the stored values (entry options → entry data →
+    defaults) so a raw submit that sets one field but omits a sibling it
+    is validated against (the staleness threshold vs. the update
+    interval) can still check the effective pair; raw submits omitting
+    BOTH keys keep their stored values untouched.
+    """
     errors: dict[str, str] = {}
 
-    horizon_days = user_input.get(CONF_HORIZON_DAYS)
-    if (
-        isinstance(horizon_days, bool)
-        or not isinstance(horizon_days, int)
-        or horizon_days < MIN_HORIZON_DAYS
-    ):
-        errors[CONF_HORIZON_DAYS] = "invalid"
-
-    day_rollover_time = user_input.get(CONF_DAY_ROLLOVER_TIME)
-    if not isinstance(day_rollover_time, str) or not _parse_time(day_rollover_time):
-        errors[CONF_DAY_ROLLOVER_TIME] = "invalid_time"
-
     panel_idle_timeout = user_input.get(CONF_PANEL_IDLE_TIMEOUT)
     if (
         isinstance(panel_idle_timeout, bool)
@@ -81,270 +70,127 @@ def _async_validate(user_input: dict[str, Any]) -> dict[str, str]:
     ):
         errors[CONF_UPDATE_INTERVAL] = "invalid"
 
-    # The notification section (Feature 11) is OPTIONAL in raw submits
-    # the same way: a missing key keeps the current value.  The three
-    # times are strict HH:MM; the notify target is a non-empty HA
-    # service name; the toggles are real booleans.
-    for time_key in (
-        CONF_MORNING_SUMMARY_TIME,
-        CONF_AFTERNOON_REMINDER_TIME,
-        CONF_END_OF_DAY_REPORT_TIME,
+    # The last-good staleness threshold (Feature 18) is OPTIONAL in raw
+    # submits the same way: a missing key keeps the current value.  It
+    # must be a positive int, and at least the EFFECTIVE update interval
+    # (the one this submit carries, else the stored or default one) — a
+    # threshold shorter than the poll cadence could never serve even one
+    # cached snapshot.
+    staleness = user_input.get(CONF_SNAPSHOT_STALENESS)
+    if staleness is not None and (
+        isinstance(staleness, bool)
+        or not isinstance(staleness, int)
+        or staleness < 1
     ):
-        time_value = user_input.get(time_key)
-        if time_value is not None and (
-            not isinstance(time_value, str) or not _parse_time(time_value)
+        errors[CONF_SNAPSHOT_STALENESS] = "invalid"
+    elif staleness is not None and not errors.get(CONF_UPDATE_INTERVAL):
+        stored_interval = (current or {}).get(CONF_UPDATE_INTERVAL)
+        effective_interval = update_interval
+        if effective_interval is None and (
+            isinstance(stored_interval, int)
+            and not isinstance(stored_interval, bool)
+            and stored_interval >= MIN_UPDATE_INTERVAL
         ):
-            errors[time_key] = "invalid_time"
-    notify_target = user_input.get(CONF_NOTIFY_TARGET)
-    if notify_target is not None and not isinstance(notify_target, str):
-        errors[CONF_NOTIFY_TARGET] = "invalid"
-    elif isinstance(notify_target, str) and notify_target != (
-        notify_target.strip()
+            effective_interval = stored_interval
+        if effective_interval is None:
+            effective_interval = DEFAULT_UPDATE_INTERVAL
+        if staleness < effective_interval:
+            errors[CONF_SNAPSHOT_STALENESS] = "invalid_staleness"
+
+    # The panel-plane API connection (Feature 18) is OPTIONAL in raw
+    # submits the same way: a missing key keeps the current value.  The
+    # base URL must be a full http(s) URL with a host — the same check
+    # the client's constructor enforces, so a malformed URL fails at
+    # the form, not at the first request.  The token may be EMPTY (the
+    # API connection is simply not configured yet) but a non-empty one
+    # must be pasted unpadded: a padded or whitespace-only value is a
+    # clipboard mistake that would fail the token check at request
+    # time.
+    api_base_url = user_input.get(CONF_API_BASE_URL)
+    if api_base_url is not None and not is_valid_base_url(api_base_url):
+        errors[CONF_API_BASE_URL] = "invalid_url"
+    panel_token = user_input.get(CONF_PANEL_TOKEN)
+    if panel_token is not None and (
+        not isinstance(panel_token, str)
+        or panel_token != panel_token.strip()
     ):
-        # An EMPTY target is valid — it means "no notifications
-        # configured yet" and is the shipped default; a value that
-        # differs from its own trim (padded or whitespace-only) is
-        # malformed and rejected.
-        errors[CONF_NOTIFY_TARGET] = "invalid"
-    for toggle_key in (
-        CONF_MORNING_SUMMARY_ENABLED,
-        CONF_AFTERNOON_REMINDER_ENABLED,
-        CONF_END_OF_DAY_REPORT_ENABLED,
-        CONF_CELEBRATION_ENABLED,
-    ):
-        toggle_value = user_input.get(toggle_key)
-        if toggle_value is not None and not isinstance(toggle_value, bool):
-            errors[toggle_key] = "invalid"
+        errors[CONF_PANEL_TOKEN] = "invalid"
 
     return errors
 
 
-def _strict_bool(value: object) -> bool:
-    """Require a real bool; voluptuous ``bool`` would coerce strings."""
-    if not isinstance(value, bool):
-        raise vol.Invalid(f"expected a boolean, got {value!r}")
-    return value
-
-
-def _build_schema(
-    current: dict[str, Any],
-    *,
-    admin_choices: dict[str, str] | None = None,
-    admin_default: list[str] | None = None,
-) -> vol.Schema:
+def _build_schema(current: dict[str, Any]) -> vol.Schema:
     """Build the form schema, pre-filled with the current values.
 
-    The admin picker is a multi-select of EXISTING Home Assistant users
-    (never a free-text field — the allowlist stores user IDs); its
-    default is the current database allowlist, so an untouched submit
-    re-saves exactly who is already allowed.  The notification section
-    (Feature 11) carries the household's notify target, the three
-    automation times, and four enable toggles — defaults from
-    :mod:`~.const`, never a hard-coded personal target.
+    The API connection (Feature 18) carries the base URL the API client
+    talks to and the panel service token it presents as the Bearer
+    credential.  Schema-validated submits always carry every field (the
+    defaults pre-fill from the stored values); raw callers omitting one
+    keep its stored value (see _async_validate).
     """
-    fields: dict[Any, Any] = {
-        vol.Required(
-            CONF_HORIZON_DAYS, default=current[CONF_HORIZON_DAYS]
-        ): int,
-        vol.Required(
-            CONF_DAY_ROLLOVER_TIME, default=current[CONF_DAY_ROLLOVER_TIME]
-        ): str,
-        vol.Required(
-            CONF_PANEL_IDLE_TIMEOUT, default=current[CONF_PANEL_IDLE_TIMEOUT]
-        ): int,
-        vol.Required(
-            CONF_UPDATE_INTERVAL, default=current[CONF_UPDATE_INTERVAL]
-        ): int,
-        vol.Required(
-            CONF_NOTIFY_TARGET, default=current[CONF_NOTIFY_TARGET]
-        ): str,
-        vol.Required(
-            CONF_MORNING_SUMMARY_TIME,
-            default=current[CONF_MORNING_SUMMARY_TIME],
-        ): str,
-        vol.Required(
-            CONF_AFTERNOON_REMINDER_TIME,
-            default=current[CONF_AFTERNOON_REMINDER_TIME],
-        ): str,
-        vol.Required(
-            CONF_END_OF_DAY_REPORT_TIME,
-            default=current[CONF_END_OF_DAY_REPORT_TIME],
-        ): str,
-        vol.Required(
-            CONF_MORNING_SUMMARY_ENABLED,
-            default=current[CONF_MORNING_SUMMARY_ENABLED],
-        ): _strict_bool,
-        vol.Required(
-            CONF_AFTERNOON_REMINDER_ENABLED,
-            default=current[CONF_AFTERNOON_REMINDER_ENABLED],
-        ): _strict_bool,
-        vol.Required(
-            CONF_END_OF_DAY_REPORT_ENABLED,
-            default=current[CONF_END_OF_DAY_REPORT_ENABLED],
-        ): _strict_bool,
-        vol.Required(
-            CONF_CELEBRATION_ENABLED,
-            default=current[CONF_CELEBRATION_ENABLED],
-        ): _strict_bool,
-    }
-    if admin_choices is not None:
-        # HA's supported multi-select validator: the frontend can
-        # serialize the field as a real picker of the given choices.
-        fields[
-            vol.Optional(
-                CONF_ADMIN_USER_IDS, default=list(admin_default or [])
-            )
-        ] = cv.multi_select(admin_choices)
-    return vol.Schema(fields)
+    return vol.Schema(
+        {
+            vol.Required(
+                CONF_PANEL_IDLE_TIMEOUT,
+                default=current[CONF_PANEL_IDLE_TIMEOUT],
+            ): int,
+            vol.Required(
+                CONF_UPDATE_INTERVAL, default=current[CONF_UPDATE_INTERVAL]
+            ): int,
+            # The last-good staleness threshold (Feature 18): how long
+            # the coordinator keeps serving the cached snapshot after
+            # the API stops answering.
+            vol.Required(
+                CONF_SNAPSHOT_STALENESS,
+                default=current[CONF_SNAPSHOT_STALENESS],
+            ): int,
+            # Panel-plane API connection (Feature 18): the base URL the
+            # API client talks to and the panel service token it
+            # presents as the Bearer credential.
+            vol.Required(
+                CONF_API_BASE_URL, default=current[CONF_API_BASE_URL]
+            ): str,
+            vol.Required(
+                CONF_PANEL_TOKEN, default=current[CONF_PANEL_TOKEN]
+            ): str,
+        }
+    )
 
 
 class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
     """Handle the options flow for NestQuest."""
 
-    def _async_database(self):
-        """Return the runtime database for this entry, or None.
-
-        Real HA only opens the options flow for an existing entry, so
-        the runtime record (and its database) exists; the None branch
-        covers direct construction in tests and degraded states.
-        """
-        hass_data = getattr(self.hass, "data", None)
-        if not isinstance(hass_data, dict):
-            return None
-        record = hass_data.get(DOMAIN, {}).get(self.config_entry.entry_id)
-        database = getattr(record, "database", None)
-        return database if getattr(database, "connected", False) else None
-
-    async def _async_admin_choices(self) -> dict[str, str]:
-        """Map HA user id -> display name for the picker.
-
-        Real Home Assistant always provides ``hass.auth``; a missing
-        one (direct construction in tests, degraded harness) degrades
-        to an empty picker rather than crashing the form.
-        """
-        auth = getattr(self.hass, "auth", None)
-        if auth is None:
-            return {}
-        users = await auth.async_get_users()
-        return {
-            user.id: user.name
-            for user in users
-            if getattr(user, "id", None)
-        }
-
-    async def _async_current_admin_ids(self) -> list[str]:
-        """Return the current allowlist, or [] without a database."""
-        database = self._async_database()
-        if database is None:
-            return []
-        return await list_admin_ids(database)
-
     async def async_step_init(
         self, user_input: dict[str, Any] | None = None
     ) -> FlowResult:
         """Manage the NestQuest options."""
-        admin_choices = await self._async_admin_choices()
-        admin_default = await self._async_current_admin_ids()
         if user_input is None:
             return self.async_show_form(
                 step_id="init",
-                data_schema=_build_schema(
-                    self._current_values(),
-                    admin_choices=admin_choices,
-                    admin_default=admin_default,
-                ),
+                data_schema=_build_schema(self._current_values()),
             )
 
-        errors = _async_validate(user_input)
-        # The admin ids are validated only when the key is present:
-        # schema-validated submits always carry it (vol.Optional's
-        # default fills from the current allowlist), while raw callers
-        # omitting the key keep the field untouched.
-        admin_ids_present = CONF_ADMIN_USER_IDS in user_input
-        admin_ids = user_input.get(CONF_ADMIN_USER_IDS)
+        errors = _async_validate(user_input, self._current_values())
         if errors:
             return self.async_show_form(
                 step_id="init",
-                data_schema=_build_schema(
-                    self._current_values(),
-                    admin_choices=admin_choices,
-                    admin_default=admin_default,
-                ),
-                errors=errors,
-            )
-        if admin_ids_present and (
-            not isinstance(admin_ids, list)
-            or any(not isinstance(value, str) for value in admin_ids)
-        ):
-            errors[CONF_ADMIN_USER_IDS] = "invalid_admin"
-        elif admin_ids_present and not admin_ids:
-            # An empty allowlist fails closed: saving zero admins is
-            # refused, never silently applied.
-            errors[CONF_ADMIN_USER_IDS] = "no_admins"
-        elif admin_ids_present and any(
-            value not in admin_choices for value in admin_ids
-        ):
-            # The schema enforces membership for real HA submits; this
-            # backs the raw-input path up so an unknown id can never
-            # reach the allowlist.
-            errors[CONF_ADMIN_USER_IDS] = "invalid_admin"
-        elif admin_ids_present and len(set(admin_ids)) != len(admin_ids):
-            # set_admin_ids refuses duplicates with ValueError; a flow
-            # submission must surface that as a field error instead of
-            # an unhandled crash.
-            errors[CONF_ADMIN_USER_IDS] = "invalid_admin"
-        if errors:
-            return self.async_show_form(
-                step_id="init",
-                data_schema=_build_schema(
-                    self._current_values(),
-                    admin_choices=admin_choices,
-                    admin_default=admin_default,
-                ),
+                data_schema=_build_schema(self._current_values()),
                 errors=errors,
             )
 
-        # Apply the picker's selection to the allowlist when the
-        # runtime database is reachable; the selection is always
-        # stored on the entry as the disaster-recovery copy.
-        database = self._async_database()
-        if database is not None and admin_ids_present:
-            await set_admin_ids(database, admin_ids)
-        data = {
-            CONF_HORIZON_DAYS: user_input[CONF_HORIZON_DAYS],
-            CONF_DAY_ROLLOVER_TIME: user_input[CONF_DAY_ROLLOVER_TIME],
-            CONF_PANEL_IDLE_TIMEOUT: user_input[CONF_PANEL_IDLE_TIMEOUT],
-            CONF_UPDATE_INTERVAL: user_input.get(
-                CONF_UPDATE_INTERVAL,
-                self._current_values()[CONF_UPDATE_INTERVAL],
-            ),
-        }
-        # The notification section (Feature 11) stores the household's
-        # choices the same fall-back-to-current way, so raw submits
-        # that predate the section keep their stored values.
+        # Every remaining key is stored the fall-back-to-current way, so
+        # raw submits that predate a section keep that section's stored
+        # values.
         current = self._current_values()
-        for notification_key in (
-            CONF_NOTIFY_TARGET,
-            CONF_MORNING_SUMMARY_TIME,
-            CONF_AFTERNOON_REMINDER_TIME,
-            CONF_END_OF_DAY_REPORT_TIME,
-            CONF_MORNING_SUMMARY_ENABLED,
-            CONF_AFTERNOON_REMINDER_ENABLED,
-            CONF_END_OF_DAY_REPORT_ENABLED,
-            CONF_CELEBRATION_ENABLED,
+        data: dict[str, Any] = {}
+        for key in (
+            CONF_PANEL_IDLE_TIMEOUT,
+            CONF_UPDATE_INTERVAL,
+            CONF_SNAPSHOT_STALENESS,
+            CONF_API_BASE_URL,
+            CONF_PANEL_TOKEN,
         ):
-            data[notification_key] = user_input.get(
-                notification_key, current[notification_key]
-            )
-        if admin_ids_present:
-            data[CONF_ADMIN_USER_IDS] = admin_ids
-        elif admin_default:
-            # HA replaces entry.options wholesale, so an omitted picker
-            # field must carry the CURRENT allowlist forward: dropping
-            # it would leave only the stale config-flow copy in entry
-            # data, and a later database loss would resurrect admins
-            # the owner has since removed.
-            data[CONF_ADMIN_USER_IDS] = list(admin_default)
+            data[key] = user_input.get(key, current[key])
         return self.async_create_entry(title="NestQuest", data=data)
 
     def _current_values(self) -> dict[str, Any]:
@@ -353,18 +199,11 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
         entry_data = getattr(self.config_entry, "data", None) or {}
         values: dict[str, Any] = {}
         for key, default in (
-            (CONF_HORIZON_DAYS, DEFAULT_HORIZON_DAYS),
-            (CONF_DAY_ROLLOVER_TIME, DEFAULT_DAY_ROLLOVER_TIME),
             (CONF_PANEL_IDLE_TIMEOUT, DEFAULT_PANEL_IDLE_TIMEOUT),
             (CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL),
-            (CONF_NOTIFY_TARGET, ""),
-            (CONF_MORNING_SUMMARY_TIME, DEFAULT_MORNING_SUMMARY_TIME),
-            (CONF_AFTERNOON_REMINDER_TIME, DEFAULT_AFTERNOON_REMINDER_TIME),
-            (CONF_END_OF_DAY_REPORT_TIME, DEFAULT_END_OF_DAY_REPORT_TIME),
-            (CONF_MORNING_SUMMARY_ENABLED, DEFAULT_AUTOMATION_ENABLED),
-            (CONF_AFTERNOON_REMINDER_ENABLED, DEFAULT_AUTOMATION_ENABLED),
-            (CONF_END_OF_DAY_REPORT_ENABLED, DEFAULT_AUTOMATION_ENABLED),
-            (CONF_CELEBRATION_ENABLED, DEFAULT_AUTOMATION_ENABLED),
+            (CONF_SNAPSHOT_STALENESS, DEFAULT_SNAPSHOT_STALENESS),
+            (CONF_API_BASE_URL, DEFAULT_API_BASE_URL),
+            (CONF_PANEL_TOKEN, DEFAULT_PANEL_TOKEN),
         ):
             if key in options:
                 values[key] = options[key]
@@ -372,4 +211,4 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
                 values[key] = entry_data[key]
             else:
                 values[key] = default
-        return values
+        return values

custom_components/nestquest/permissions.py

@@ -1,90 +0,0 @@
-"""Permission gate for NestQuest services (Feature 09).
-
-A wrapper factory, applied to EVERY registered service at registration
-time (no handler is exempt), reads ``call.context.user_id``, consults
-the :data:`~.service_policy.SERVICE_POLICY` registry and
-:func:`~.admin_allowlist.is_admin`, and raises
-:class:`homeassistant.exceptions.Unauthorized` for an admin-only
-operation called by a non-admin — including a call with NO user
-context, which fails closed.  ``complete_quest`` (policy ``open``)
-proceeds regardless of the allowlist.
-
-Logging (later Feature 09 tasks): every denied admin-only call logs a
-warning and every successful one logs a debug line, both carrying the
-service, the user id (or ``none``), and a UTC timestamp.
-"""
-from __future__ import annotations
-
-import datetime
-import logging
-from collections.abc import Awaitable, Callable
-from typing import Any
-
-from homeassistant.exceptions import Unauthorized
-
-from .admin_allowlist import is_admin
-from .service_policy import ADMIN_ONLY
-
-LOGGER = logging.getLogger(__name__)
-
-ServiceHandler = Callable[[Any], Awaitable[None]]
-
-
-def _context_user_id(call: Any) -> str | None:
-    context = getattr(call, "context", None)
-    user_id = getattr(context, "user_id", None) if context is not None else None
-    if isinstance(user_id, str) and user_id:
-        return user_id
-    return None
-
-
-def _stamp() -> str:
-    return datetime.datetime.now(datetime.timezone.utc).isoformat(
-        timespec="seconds"
-    )
-
-
-def permission_gate(
-    service: str,
-    policy: str,
-    database_of: Callable[[Any], Any],
-) -> Callable[[ServiceHandler], ServiceHandler]:
-    """Wrap ``handler`` with the Feature 09 permission check.
-
-    ``database_of`` resolves the live database from the call-time
-    runtime (the same ``find_runtime`` the handler uses), so the gate
-    never opens its own connection.  The verdict is fail-closed:
-    absent allowlist row, unknown id, no user context — all not admin.
-    """
-
-    def _wrap(handler: ServiceHandler) -> ServiceHandler:
-        if policy != ADMIN_ONLY:
-            return handler
-
-        async def _gated(call: Any) -> None:
-            user_id = _context_user_id(call)
-            allowed = user_id is not None and await is_admin(
-                database_of(call), user_id
-            )
-            if not allowed:
-                LOGGER.warning(
-                    "NestQuest denied %s: caller user_id=%s at %s",
-                    service,
-                    user_id if user_id is not None else "none",
-                    _stamp(),
-                )
-                raise Unauthorized(
-                    f"User '{user_id if user_id is not None else 'none'}' "
-                    f"is not allowed to call nestquest.{service}"
-                )
-            LOGGER.debug(
-                "NestQuest allowed %s: caller user_id=%s at %s",
-                service,
-                user_id,
-                _stamp(),
-            )
-            await handler(call)
-
-        return _gated
-
-    return _wrap

custom_components/nestquest/presence.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.presence` for the integration package.
-
-The presence and custody model lives in
-:mod:`custom_components.nestquest.core.presence` (extracted in
-task 510c1f78); this module re-exports it so existing
-``from .presence import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.presence import *  # noqa: F401,F403

custom_components/nestquest/presence_management.py

@@ -1,10 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.presence_management` for the integration package.
-
-The presence-write business layer lives in
-:mod:`custom_components.nestquest.core.presence_management` (added for
-task e4a9d31b); this module re-exports it so the integration's service
-handlers call the ONE implementation the API admin plane shares.
-"""
-from __future__ import annotations
-
-from .core.presence_management import *  # noqa: F401,F403

custom_components/nestquest/quest_definitions.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.quest_definitions` for the integration package.
-
-The quest definitions business layer lives in
-:mod:`custom_components.nestquest.core.quest_definitions` (extracted in
-task 510c1f78); this module re-exports it so existing
-``from .quest_definitions import ...`` references inside the integration
-keep working.
-"""
-from __future__ import annotations
-
-from .core.quest_definitions import *  # noqa: F401,F403

custom_components/nestquest/recurrence.py

@@ -1,10 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.recurrence` for the integration package.
-
-The recurrence model lives in :mod:`custom_components.nestquest.core.recurrence`
-(extracted in task d0b691d8); this module re-exports it so existing
-``from .recurrence import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.recurrence import *  # noqa: F401,F403

custom_components/nestquest/schema.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.schema` for the integration package.
-
-The declarative schema DDL lives in
-:mod:`custom_components.nestquest.core.schema` (extracted in
-task d0b691d8); this module re-exports it so existing
-``from .schema import ...`` references inside the integration keep
-working.
-"""
-from __future__ import annotations
-
-from .core.schema import *  # noqa: F401,F403

custom_components/nestquest/sensor.py

@@ -21,6 +21,8 @@ missed instances, and ``admin_instances`` includes them (D-009).
 """
 from __future__ import annotations
 
+import re
+import unicodedata
 from collections.abc import Callable, Iterable
 from typing import Any
 
@@ -41,13 +43,18 @@ from .coordinator import (
 )
 from .core.snapshot import instance_payload
 
-#: Home Assistant's state machine refuses states longer than 255
+#: HA's state machine refuses states longer than 255
 #: characters (its hard recorder/state limit).  These sensors' states
 #: are numeric, but the guard is applied uniformly: a payload-bearing
 #: sensor can never crash the state write, and later string-state
 #: sensors reuse the same helper.
 MAX_STATE_LENGTH = 255
 
+#: Entity-id length cap the slug mirror applies: HA truncates the
+#: entity_id (``sensor.`` + slug) at MAX_LENGTH_STATE_ENTITY_ID (64),
+#: so the slugged object id alone may not exceed 64 - len("sensor.").
+_MAX_SLUG_LENGTH = 64 - len("sensor.")
+
 
 def _state_within_limit(state: Any) -> Any:
     """Return ``state`` unchanged, refusing strings over HA's limit.
@@ -98,6 +105,56 @@ def _next_open_quest(
     )
 
 
+def _slugify(text: str) -> str:
+    """Slugify a display name the way Home Assistant derives entity ids.
+
+    Mirrors ``homeassistant.util.slugify`` (the unicode path HA runs
+    entity names through) for accented-Latin names: NFKD-normalize,
+    fold to ASCII (accents drop out with their combining marks),
+    lowercase, and turn every run of non-alphanumerics into one
+    underscore, capped at HA's entity-id length like the registry does.
+    The documented divergence from HA's vendored slugifier is unidecode:
+    HA transliterates any script to ASCII (so e.g. non-Latin names
+    survive), this mirror drops those characters instead, and a name
+    that then slugs to nothing falls through to HA's ``unknown``
+    sentinel — the same answer HA's wrapper gives.  (The harness is
+    mock-only — no real HA to import the helper from — and entity ids
+    are registry identity, so the mirror is deliberate.)
+    """
+    slug = unicodedata.normalize("NFKD", text)
+    slug = slug.encode("ascii", "ignore").decode("ascii")
+    slug = re.sub(r"[^a-z0-9]+", "_", slug.lower()).strip("_")
+    return (slug or "unknown")[:_MAX_SLUG_LENGTH]
+
+
+def _child_roster(children: Iterable[ChildDaySnapshot]) -> list[dict[str, Any]]:
+    """The ordered child roster the panel cards discover children from.
+
+    One entry per ACTIVE child in the snapshot's order (the API's
+    sort_order, then id): ``child_id``, ``name``, and the ``slug`` the
+    entity-id derivation produces for the child's name — the piece the
+    cards need to build ``sensor.nestquest_<slug>_...`` ids.  Duplicate
+    display names get the registry's ``_2``/``_3`` suffix in snapshot
+    order, matching how HA resolves the collision at registration.  The
+    rollups' ``children`` attribute (per-child counts) is unchanged and
+    carries a different shape on purpose.
+    """
+    slugs: dict[str, int] = {}
+    roster: list[dict[str, Any]] = []
+    for child in children:
+        base = _slugify(child.child_name)
+        taken = slugs.get(base, 0) + 1
+        slugs[base] = taken
+        roster.append(
+            {
+                "child_id": child.child_id,
+                "name": child.child_name,
+                "slug": base if taken == 1 else f"{base}_{taken}",
+            }
+        )
+    return roster
+
+
 class _NestQuestChildDaySensor(CoordinatorEntity, SensorEntity):
     """Base for the per-child day sensors.
 
@@ -356,7 +413,12 @@ class _NestQuestHouseholdSensor(CoordinatorEntity, SensorEntity):
 
 
 class NestQuestHouseholdDueTodaySensor(_NestQuestHouseholdSensor):
-    """Total quests due today across active children."""
+    """Total quests due today across active children.
+
+    Also publishes ``child_roster`` (see :func:`_child_roster`): the
+    ordered child identity list the panel cards read to discover the
+    board's children when the card config carries no ``child_order``.
+    """
 
     _attr_name = "NestQuest household quests due today"
     _attr_state_class = SensorStateClass.MEASUREMENT
@@ -380,7 +442,8 @@ class NestQuestHouseholdDueTodaySensor(_NestQuestHouseholdSensor):
             "children": {
                 str(child.child_id): child.due_today
                 for child in data.children
-            }
+            },
+            "child_roster": _child_roster(data.children),
         }
 
 

custom_components/nestquest/service_policy.py

@@ -1,11 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.service_policy` for the integration package.
-
-The service policy registry lives in
-:mod:`custom_components.nestquest.core.service_policy` (extracted in
-task 510c1f78); this module re-exports it so existing
-``from .service_policy import ...`` references inside the integration
-keep working.
-"""
-from __future__ import annotations
-
-from .core.service_policy import *  # noqa: F401,F403

custom_components/nestquest/services.py

@@ -1,61 +1,36 @@
-"""Domain-global NestQuest service schemas and handlers (Feature 09).
+"""The domain-global ``nestquest.complete_quest`` service (Feature 18).
 
 Registration is domain-scoped and happens once (see
-:func:`async_register_services`); handlers resolve a live database at
-call time through the injected ``find_runtime`` callable.  Permission
-checks are Feature 09 later tasks — this module only validates payload
-shape and forwards to the Feature 03/06/08 business layers (the
-presence writes included, through :mod:`.presence_management` — the
-ONE implementation the API admin plane shares).
-``export_history_csv`` is registered with a schema but raises until
-Feature 13.  ``regenerate`` is supplied by the caller so
-the Feature 07 handler stays the one in ``__init__``.
+:func:`async_register_services`).  Since Feature 18 the integration is
+a client of the NestQuest API service, so ``complete_quest`` proxies
+to the API's panel complete route through the entry's shared API
+client instead of writing any database.  The former HA admin services
+(uncomplete, quest-definition and presence management, CSV export,
+child management, regenerate) are removed: the admin surface is the
+PWA and the API service's admin routes, so the only HA service left is
+the panel completion path.
 """
 from __future__ import annotations
 
-import datetime
 from collections.abc import Awaitable, Callable
 from typing import Any
-from zoneinfo import ZoneInfo
 
 import voluptuous as vol
 from homeassistant.core import HomeAssistant
 from homeassistant.exceptions import HomeAssistantError
 
-from . import children as children_layer
-from . import completion as completion_layer
-from . import presence_management as presence_management_layer
-from . import quest_definitions as quest_definitions_layer
+from .api_client import NestQuestApiError
 from .const import (
     DOMAIN,
     DOMAIN_SERVICES,
-    QUEST_WINDOWS,
     SERVICE_COMPLETE_QUEST,
-    SERVICE_CREATE_PRESENCE_OVERRIDE,
-    SERVICE_CREATE_QUEST_DEFINITION,
-    SERVICE_DELETE_PRESENCE_OVERRIDE,
-    SERVICE_EXPORT_HISTORY_CSV,
-    SERVICE_MANAGE_CHILD,
-    SERVICE_REGENERATE,
-    SERVICE_SET_PRESENCE_PATTERN,
-    SERVICE_SET_QUEST_DEFINITION_ACTIVE,
-    SERVICE_UNCOMPLETE_QUEST,
-    SERVICE_UPDATE_QUEST_DEFINITION,
 )
-from .events import fire_quest_completed, fire_quest_uncompleted
-from .permissions import permission_gate
-from .recurrence import ScheduleRule
-from .service_policy import SERVICE_POLICY
 
 FindRuntime = Callable[[HomeAssistant], Any]
 ServiceHandler = Callable[[Any], Awaitable[None]]
 
 ACTOR_PANEL = "panel"
 ACTOR_USER = "user"
-MANAGE_CHILD_CREATE = "create"
-MANAGE_CHILD_EDIT = "edit"
-MANAGE_CHILD_SET_ACTIVE = "set_active"
-MANAGE_CHILD_REORDER = "reorder"
 
 
 def _strict_int(value: object) -> int:
@@ -65,82 +40,6 @@ def _strict_int(value: object) -> int:
     return value
 
 
-def _strict_bool(value: object) -> bool:
-    """Reject ints and other truthy values; require a real bool."""
-    if type(value) is not bool:
-        raise vol.Invalid(f"expected bool, got {value!r}")
-    return value
-
-
-def _weekday_list(value: object) -> list[int]:
-    if type(value) is not list:
-        raise vol.Invalid(f"expected a list of weekday ints, got {value!r}")
-    return [_strict_int(item) for item in value]
-
-
-def _presence_pattern(value: object) -> dict[int, list[int]]:
-    if not isinstance(value, dict):
-        raise vol.Invalid(f"pattern must be a mapping, got {value!r}")
-    pattern: dict[int, list[int]] = {}
-    for week, days in value.items():
-        if isinstance(week, str):
-            try:
-                week_index = int(week)
-            except ValueError as err:
-                raise vol.Invalid(
-                    f"pattern week index must be an integer, got {week!r}"
-                ) from err
-            if str(week_index) != week:
-                raise vol.Invalid(
-                    f"pattern week index must be an integer, got {week!r}"
-                )
-        else:
-            week_index = _strict_int(week)
-        pattern[week_index] = _weekday_list(days)
-    return pattern
-
-
-def _window_entry(value: object) -> str | tuple[str, str | None]:
-    if isinstance(value, str):
-        if value not in QUEST_WINDOWS:
-            raise vol.Invalid(f"unknown window {value!r}")
-        return value
-    if isinstance(value, dict):
-        parsed = vol.Schema(
-            {
-                vol.Required("window"): vol.In(QUEST_WINDOWS),
-                vol.Optional("due_time"): str,
-            }
-        )(value)
-        due_time = parsed.get("due_time")
-        if due_time is None:
-            return parsed["window"]
-        return (parsed["window"], due_time)
-    raise vol.Invalid(
-        f"windows entry must be a window name or object, got {value!r}"
-    )
-
-
-def _windows(value: object) -> list[str | tuple[str, str | None]]:
-    if type(value) is not list:
-        raise vol.Invalid(f"windows must be a list, got {value!r}")
-    if not value:
-        raise vol.Invalid("windows must not be empty")
-    return [_window_entry(entry) for entry in value]
-
-
-def _int_list(value: object) -> list[int]:
-    if type(value) is not list:
-        raise vol.Invalid(f"expected a list of ints, got {value!r}")
-    return [_strict_int(item) for item in value]
-
-
-def _rule_dict(value: object) -> dict:
-    if not isinstance(value, dict):
-        raise vol.Invalid(f"rule must be a dict, got {value!r}")
-    return value
-
-
 SCHEMA_COMPLETE_QUEST = vol.Schema(
     {
         vol.Required("instance_id"): _strict_int,
@@ -150,102 +49,22 @@ SCHEMA_COMPLETE_QUEST = vol.Schema(
     }
 )
 
-SCHEMA_UNCOMPLETE_QUEST = SCHEMA_COMPLETE_QUEST
-
-SCHEMA_CREATE_QUEST_DEFINITION = vol.Schema(
-    {
-        vol.Required("title"): str,
-        vol.Required("rule"): _rule_dict,
-        vol.Required("assignee_child_ids"): vol.All(
-            _int_list, vol.Length(min=1)
-        ),
-        vol.Required("windows"): _windows,
-        vol.Optional("description"): str,
-        vol.Optional("icon"): str,
-    }
-)
-
-SCHEMA_UPDATE_QUEST_DEFINITION = vol.Schema(
-    {
-        vol.Required("definition_id"): _strict_int,
-        vol.Optional("title"): str,
-        vol.Optional("description"): vol.Any(str, None),
-        vol.Optional("icon"): vol.Any(str, None),
-        vol.Optional("rule"): _rule_dict,
-        vol.Optional("windows"): _windows,
-    }
-)
-
-SCHEMA_SET_QUEST_DEFINITION_ACTIVE = vol.Schema(
-    {
-        vol.Required("definition_id"): _strict_int,
-        vol.Required("is_active"): _strict_bool,
-    }
-)
-
-SCHEMA_SET_PRESENCE_PATTERN = vol.Schema(
-    {
-        vol.Required("child_id"): _strict_int,
-        vol.Required("cycle_length_weeks"): _strict_int,
-        vol.Required("anchor_date"): str,
-        vol.Required("pattern"): _presence_pattern,
-    }
-)
-
-SCHEMA_CREATE_PRESENCE_OVERRIDE = vol.Schema(
-    {
-        vol.Required("child_id"): _strict_int,
-        vol.Required("start_date"): str,
-        vol.Required("end_date"): str,
-        vol.Required("is_present"): _strict_bool,
-        vol.Optional("note"): str,
-    }
-)
-
-SCHEMA_DELETE_PRESENCE_OVERRIDE = vol.Schema(
-    {
-        vol.Required("override_id"): _strict_int,
-    }
-)
-
-SCHEMA_EXPORT_HISTORY_CSV = vol.Schema({})
-
-SCHEMA_MANAGE_CHILD = vol.Schema(
-    {
-        vol.Required("action"): vol.In(
-            [
-                MANAGE_CHILD_CREATE,
-                MANAGE_CHILD_EDIT,
-                MANAGE_CHILD_SET_ACTIVE,
-                MANAGE_CHILD_REORDER,
-            ]
-        ),
-        vol.Optional("child_id"): _strict_int,
-        vol.Optional("display_name"): str,
-        vol.Optional("colour"): str,
-        vol.Optional("avatar_ref"): str,
-        vol.Optional("sort_order"): _strict_int,
-        vol.Optional("is_active"): _strict_bool,
-        vol.Optional("ordered_ids"): _int_list,
-    }
-)
-
 
 def _require_runtime(hass: HomeAssistant, find_runtime: FindRuntime):
     runtime = find_runtime(hass)
     if runtime is None:
         raise HomeAssistantError(
-            "NestQuest has no live database; cannot run this service"
+            "NestQuest is not loaded; cannot run this service"
         )
     return runtime
 
 
 async def _refresh_entities(runtime: Any) -> None:
-    """Force an immediate coordinator refresh after a service mutation.
+    """Force an immediate coordinator refresh after the service call.
 
-    Only the SERVICE paths call this — the scheduled materialize and
+    Only the SERVICE path calls this — the scheduled materialize and
     rollover internals are direct function calls and never widen this
-    gate — so entities reflect a completion the moment the service
+    gate — so the entities reflect a completion the moment the service
     call returns instead of waiting for the poll interval.
     """
     coordinator = getattr(runtime, "coordinator", None)
@@ -253,12 +72,6 @@ async def _refresh_entities(runtime: Any) -> None:
         await coordinator.async_refresh()
 
 
-def _generation_kwargs(hass: HomeAssistant, runtime: Any) -> dict[str, Any]:
-    time_zone = ZoneInfo(hass.config.time_zone)
-    today = datetime.datetime.now(time_zone).date()
-    return {"today": today, "horizon_days": runtime.settings.horizon_days}
-
-
 def _actor_kwargs(call: Any) -> dict[str, Any]:
     actor = call.data["actor"]
     if actor == ACTOR_PANEL:
@@ -301,223 +114,50 @@ def _complete_quest(
     async def _handler(call: Any) -> None:
         runtime = _require_runtime(hass, find_runtime)
         instance_id = call.data["instance_id"]
-        # ``appended`` is decided under the same lock as the write, so
-        # a concurrent duplicate call (a double tap) can not produce a
-        # second transition event: the loser appends nothing.
-        result = await completion_layer.complete_instance(
-            runtime.database,
-            instance_id,
-            **_actor_kwargs(call),
-        )
-        if result.appended:
-            await fire_quest_completed(
-                hass,
-                runtime.database,
-                instance_id,
-                was_on_time=result.was_on_time,
-            )
-            await _refresh_entities(runtime)
-
-    return _with_errors(_handler)
-
-
-def _uncomplete_quest(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        runtime = _require_runtime(hass, find_runtime)
-        instance_id = call.data["instance_id"]
-        result = await completion_layer.uncomplete_instance(
-            runtime.database,
-            instance_id,
-            **_actor_kwargs(call),
-        )
-        if result.appended:
-            await fire_quest_uncompleted(
-                hass, runtime.database, instance_id
-            )
-            await _refresh_entities(runtime)
-
-    return _with_errors(_handler)
-
-
-def _create_quest_definition(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        database = _require_runtime(hass, find_runtime).database
-        data = call.data
-        await quest_definitions_layer.create_quest_definition(
-            database,
-            data["title"],
-            ScheduleRule.from_dict(data["rule"]),
-            data["assignee_child_ids"],
-            data["windows"],
-            description=data.get("description"),
-            icon=data.get("icon"),
-        )
-
-    return _with_errors(_handler)
-
-
-def _update_quest_definition(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        runtime = _require_runtime(hass, find_runtime)
-        data = call.data
-        kwargs: dict[str, Any] = _generation_kwargs(hass, runtime)
-        if "title" in data:
-            kwargs["title"] = data["title"]
-        if "description" in data:
-            kwargs["description"] = data["description"]
-        if "icon" in data:
-            kwargs["icon"] = data["icon"]
-        if "rule" in data:
-            kwargs["rule"] = ScheduleRule.from_dict(data["rule"])
-        if "windows" in data:
-            kwargs["windows"] = data["windows"]
-        await quest_definitions_layer.edit_quest_definition(
-            runtime.database, data["definition_id"], **kwargs
-        )
-
-    return _with_errors(_handler)
-
-
-def _set_quest_definition_active(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        runtime = _require_runtime(hass, find_runtime)
-        await quest_definitions_layer.set_quest_definition_active(
-            runtime.database,
-            call.data["definition_id"],
-            call.data["is_active"],
-            **_generation_kwargs(hass, runtime),
-        )
-
-    return _with_errors(_handler)
-
-
-def _set_presence_pattern(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        runtime = _require_runtime(hass, find_runtime)
-        data = call.data
-        await presence_management_layer.set_presence_schedule(
-            runtime.database,
-            data["child_id"],
-            data["cycle_length_weeks"],
-            data["anchor_date"],
-            data["pattern"],
-            **_generation_kwargs(hass, runtime),
-        )
-
-    return _with_errors(_handler)
-
-
-def _create_presence_override(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        runtime = _require_runtime(hass, find_runtime)
-        data = call.data
-        await presence_management_layer.create_presence_override(
-            runtime.database,
-            data["child_id"],
-            data["start_date"],
-            data["end_date"],
-            data["is_present"],
-            note=data.get("note"),
-            **_generation_kwargs(hass, runtime),
-        )
-
-    return _with_errors(_handler)
-
-
-def _delete_presence_override(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        runtime = _require_runtime(hass, find_runtime)
-        await presence_management_layer.delete_presence_override(
-            runtime.database,
-            call.data["override_id"],
-            **_generation_kwargs(hass, runtime),
-        )
-
-    return _with_errors(_handler)
-
-
-async def _export_history_csv(_call: Any) -> None:
-    raise HomeAssistantError(
-        "CSV history export is not implemented until Feature 13"
-    )
-
-
-def _manage_child(
-    hass: HomeAssistant, find_runtime: FindRuntime
-) -> ServiceHandler:
-    async def _handler(call: Any) -> None:
-        database = _require_runtime(hass, find_runtime).database
-        data = call.data
-        action = data["action"]
-        if action == MANAGE_CHILD_CREATE:
-            display_name = data.get("display_name")
-            if display_name is None:
-                raise HomeAssistantError(
-                    "display_name is required when action is create"
-                )
-            kwargs: dict[str, Any] = {}
-            if "colour" in data:
-                kwargs["colour"] = data["colour"]
-            if "avatar_ref" in data:
-                kwargs["avatar_ref"] = data["avatar_ref"]
-            if "sort_order" in data:
-                kwargs["sort_order"] = data["sort_order"]
-            await children_layer.create_child(
-                database, display_name, **kwargs
-            )
-            return
-        if action == MANAGE_CHILD_EDIT:
-            child_id = data.get("child_id")
-            if child_id is None:
-                raise HomeAssistantError(
-                    "child_id is required when action is edit"
-                )
-            kwargs = {}
-            if "display_name" in data:
-                kwargs["display_name"] = data["display_name"]
-            if "colour" in data:
-                kwargs["colour"] = data["colour"]
-            if "avatar_ref" in data:
-                kwargs["avatar_ref"] = data["avatar_ref"]
-            if "sort_order" in data:
-                kwargs["sort_order"] = data["sort_order"]
-            await children_layer.edit_child(database, child_id, **kwargs)
-            return
-        if action == MANAGE_CHILD_SET_ACTIVE:
-            child_id = data.get("child_id")
-            is_active = data.get("is_active")
-            if child_id is None:
-                raise HomeAssistantError(
-                    "child_id is required when action is set_active"
-                )
-            if is_active is None:
-                raise HomeAssistantError(
-                    "is_active is required when action is set_active"
-                )
-            await children_layer.set_child_active(
-                database, child_id, is_active
-            )
-            return
-        ordered_ids = data.get("ordered_ids")
-        if ordered_ids is None:
+        # The panel contract (decision 9): a tap completes as the
+        # tapped child profile, the only actor shape the API's panel
+        # route accepts.  The payload schema is unchanged — the panel
+        # cards call it with instance_id, actor=panel, actor_child_id.
+        actor = _actor_kwargs(call)
+        if actor["actor_source"] != ACTOR_PANEL:
             raise HomeAssistantError(
-                "ordered_ids is required when action is reorder"
+                "nestquest.complete_quest completes through the API's "
+                "panel route as the tapped child profile; actor must "
+                "be 'panel' with actor_child_id"
             )
-        await children_layer.reorder_children(database, ordered_ids)
+        # The entry's ONE shared API client (built at setup): the
+        # coordinator's snapshot poll, the SSE subscription, and this
+        # proxy all ride the same instance.  An entry with no panel
+        # token runs the unconfigured stub, which has no completion
+        # surface — fail fast with a clear, token-free message.
+        complete_instance = getattr(
+            getattr(runtime.coordinator, "api_client", None),
+            "complete_instance",
+            None,
+        )
+        if complete_instance is None:
+            raise HomeAssistantError(
+                "NestQuest API is not configured; cannot complete a "
+                "quest"
+            )
+        try:
+            await complete_instance(instance_id, actor["actor_child_id"])
+        except NestQuestApiError as err:
+            # The typed API failure surfaces as a service error the
+            # caller sees — never swallowed, never retried here.  The
+            # typed message names method, path, and status only; the
+            # panel token never appears in it.
+            raise HomeAssistantError(
+                f"NestQuest quest completion failed: {err}"
+            ) from err
+        # NO local completion write and NO local event: the API service
+        # emits the transition on its SSE stream and the integration's
+        # subscription re-fires it on the bus — firing it here too
+        # would double-fire.  The immediate refresh keeps the old
+        # behaviour where the sensors reflect the completion the
+        # moment the service call returns instead of waiting for the
+        # poll interval.
+        await _refresh_entities(runtime)
 
     return _with_errors(_handler)
 
@@ -526,84 +166,25 @@ def async_register_services(
     hass: HomeAssistant,
     *,
     find_runtime: FindRuntime,
-    regenerate_handler: ServiceHandler,
 ) -> None:
-    """Register every canonical service once at domain scope.
+    """Register the panel completion service once at domain scope.
 
-    Every service — regenerate included — passes through the Feature
-    09 permission gate before its handler runs; the gate reads
-    :data:`~.service_policy.SERVICE_POLICY`, so no service can be
-    registered exempt from the policy.
+    The one remaining HA service is the panel completion path; every
+    admin operation moved to the API service's admin routes, so there
+    is no permission gate to apply here.
     """
-    if hass.services.has_service(DOMAIN, SERVICE_REGENERATE):
+    if hass.services.has_service(DOMAIN, SERVICE_COMPLETE_QUEST):
         return
-    gate = permission_gate
-    specs: list[tuple[str, ServiceHandler, object]] = [
-        (SERVICE_REGENERATE, regenerate_handler, None),
-        (
-            SERVICE_COMPLETE_QUEST,
-            _complete_quest(hass, find_runtime),
-            SCHEMA_COMPLETE_QUEST,
-        ),
-        (
-            SERVICE_UNCOMPLETE_QUEST,
-            _uncomplete_quest(hass, find_runtime),
-            SCHEMA_UNCOMPLETE_QUEST,
-        ),
-        (
-            SERVICE_CREATE_QUEST_DEFINITION,
-            _create_quest_definition(hass, find_runtime),
-            SCHEMA_CREATE_QUEST_DEFINITION,
-        ),
-        (
-            SERVICE_UPDATE_QUEST_DEFINITION,
-            _update_quest_definition(hass, find_runtime),
-            SCHEMA_UPDATE_QUEST_DEFINITION,
-        ),
-        (
-            SERVICE_SET_QUEST_DEFINITION_ACTIVE,
-            _set_quest_definition_active(hass, find_runtime),
-            SCHEMA_SET_QUEST_DEFINITION_ACTIVE,
-        ),
-        (
-            SERVICE_SET_PRESENCE_PATTERN,
-            _set_presence_pattern(hass, find_runtime),
-            SCHEMA_SET_PRESENCE_PATTERN,
-        ),
-        (
-            SERVICE_CREATE_PRESENCE_OVERRIDE,
-            _create_presence_override(hass, find_runtime),
-            SCHEMA_CREATE_PRESENCE_OVERRIDE,
-        ),
-        (
-            SERVICE_DELETE_PRESENCE_OVERRIDE,
-            _delete_presence_override(hass, find_runtime),
-            SCHEMA_DELETE_PRESENCE_OVERRIDE,
-        ),
-        (
-            SERVICE_EXPORT_HISTORY_CSV,
-            _export_history_csv,
-            SCHEMA_EXPORT_HISTORY_CSV,
-        ),
-        (
-            SERVICE_MANAGE_CHILD,
-            _manage_child(hass, find_runtime),
-            SCHEMA_MANAGE_CHILD,
-        ),
-    ]
-
-    def _database_of(_call: Any) -> Any:
-        return _require_runtime(hass, find_runtime).database
-
-    for service, handler, schema in specs:
-        gated = gate(
-            service, SERVICE_POLICY[service], _database_of
-        )(handler)
-        hass.services.async_register(DOMAIN, service, gated, schema=schema)
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        _complete_quest(hass, find_runtime),
+        schema=SCHEMA_COMPLETE_QUEST,
+    )
 
 
 def async_deregister_services(hass: HomeAssistant) -> None:
     """Remove every canonical service when the last entry unloads."""
     for service in DOMAIN_SERVICES:
         if hass.services.has_service(DOMAIN, service):
-            hass.services.async_remove(DOMAIN, service)
+            hass.services.async_remove(DOMAIN, service)

custom_components/nestquest/services.yaml

@@ -1,15 +1,8 @@
 # Service declarations for the NestQuest integration (Home Assistant
 # services.yaml metadata). Services are domain-scoped: nested under the
-# "nestquest" domain, not repeated per config entry.
-
-regenerate:
-  name: Regenerate quest instances
-  description: >-
-    Regenerate every future quest instance for the household over the rolling
-    horizon, using the same idempotent materialization as the daily rollover
-    and the startup backfill. Safe to call at any time: a re-run refreshes the
-    same rows instead of duplicating them, and completed instances are never
-    touched.
+# "nestquest" domain, not repeated per config entry.  Since Feature 18
+# only the panel completion service remains — every admin operation
+# moved to the PWA and the API service's admin routes.
 
 complete_quest:
   name: Complete quest
@@ -43,284 +36,4 @@ complete_quest:
       description: Home Assistant user id when actor is user and no call context is present.
       required: false
       selector:
-        text:
-
-uncomplete_quest:
-  name: Uncomplete quest
-  description: Undo a quest instance completion.
-  fields:
-    instance_id:
-      name: Instance ID
-      description: The quest instance to uncomplete.
-      required: true
-      selector:
-        number:
-          mode: box
-    actor:
-      name: Actor
-      description: Who is undoing the completion (panel or user).
-      required: true
-      selector:
-        select:
-          options:
-            - panel
-            - user
-    actor_child_id:
-      name: Actor child ID
-      description: The tapped child profile. Required when actor is panel.
-      required: false
-      selector:
-        number:
-          mode: box
-    actor_user_id:
-      name: Actor user ID
-      description: Home Assistant user id when actor is user and no call context is present.
-      required: false
-      selector:
-        text:
-
-create_quest_definition:
-  name: Create quest definition
-  description: Create a quest definition with its schedule rule, assignees and windows.
-  fields:
-    title:
-      name: Title
-      description: Display title for the quest.
-      required: true
-      selector:
-        text:
-    rule:
-      name: Rule
-      description: Recurrence rule as a mapping (rule_type plus shape fields).
-      required: true
-      selector:
-        object:
-    assignee_child_ids:
-      name: Assignee child IDs
-      description: Child ids this definition is assigned to.
-      required: true
-      selector:
-        object:
-    windows:
-      name: Windows
-      description: Day windows (morning, afternoon, evening), optionally with a due time.
-      required: true
-      selector:
-        object:
-    description:
-      name: Description
-      description: Optional longer description.
-      required: false
-      selector:
-        text:
-    icon:
-      name: Icon
-      description: Optional icon name.
-      required: false
-      selector:
-        text:
-
-update_quest_definition:
-  name: Update quest definition
-  description: Edit a quest definition's title, description, icon, rule or windows.
-  fields:
-    definition_id:
-      name: Definition ID
-      description: The quest definition to update.
-      required: true
-      selector:
-        number:
-          mode: box
-    title:
-      name: Title
-      description: Replacement display title.
-      required: false
-      selector:
-        text:
-    description:
-      name: Description
-      description: Replacement description, or null to clear.
-      required: false
-      selector:
-        text:
-    icon:
-      name: Icon
-      description: Replacement icon, or null to clear.
-      required: false
-      selector:
-        text:
-    rule:
-      name: Rule
-      description: Replacement recurrence rule as a mapping.
-      required: false
-      selector:
-        object:
-    windows:
-      name: Windows
-      description: Replacement day windows.
-      required: false
-      selector:
-        object:
-
-set_quest_definition_active:
-  name: Set quest definition active
-  description: Deactivate or reactivate a quest definition.
-  fields:
-    definition_id:
-      name: Definition ID
-      description: The quest definition to update.
-      required: true
-      selector:
-        number:
-          mode: box
-    is_active:
-      name: Active
-      description: Whether the definition should generate future instances.
-      required: true
-      selector:
-        boolean:
-
-set_presence_pattern:
-  name: Set presence pattern
-  description: Upsert a child's repeating presence schedule.
-  fields:
-    child_id:
-      name: Child ID
-      description: The child whose schedule is being set.
-      required: true
-      selector:
-        number:
-          mode: box
-    cycle_length_weeks:
-      name: Cycle length weeks
-      description: Number of weeks in the repeating cycle (1 to 4).
-      required: true
-      selector:
-        number:
-          mode: box
-          min: 1
-          max: 4
-    anchor_date:
-      name: Anchor date
-      description: Cycle anchor as a YYYY-MM-DD date.
-      required: true
-      selector:
-        date:
-    pattern:
-      name: Pattern
-      description: Mapping of week index to present weekday ints (Monday is 0).
-      required: true
-      selector:
-        object:
-
-create_presence_override:
-  name: Create presence override
-  description: Create a date-range presence override for a child.
-  fields:
-    child_id:
-      name: Child ID
-      description: The child the override applies to.
-      required: true
-      selector:
-        number:
-          mode: box
-    start_date:
-      name: Start date
-      description: Inclusive start date (YYYY-MM-DD).
-      required: true
-      selector:
-        date:
-    end_date:
-      name: End date
-      description: Inclusive end date (YYYY-MM-DD).
-      required: true
-      selector:
-        date:
-    is_present:
-      name: Present
-      description: Whether the child is present for this range.
-      required: true
-      selector:
-        boolean:
-    note:
-      name: Note
-      description: Optional note stored with the override.
-      required: false
-      selector:
-        text:
-
-delete_presence_override:
-  name: Delete presence override
-  description: Delete a presence override by id.
-  fields:
-    override_id:
-      name: Override ID
-      description: The override to delete.
-      required: true
-      selector:
-        number:
-          mode: box
-
-export_history_csv:
-  name: Export history CSV
-  description: Export completion history as CSV. Not implemented until Feature 13.
-
-manage_child:
-  name: Manage child
-  description: Create, edit, activate or reorder child profiles.
-  fields:
-    action:
-      name: Action
-      description: create, edit, set_active, or reorder.
-      required: true
-      selector:
-        select:
-          options:
-            - create
-            - edit
-            - set_active
-            - reorder
-    child_id:
-      name: Child ID
-      description: Required for edit and set_active.
-      required: false
-      selector:
-        number:
-          mode: box
-    display_name:
-      name: Display name
-      description: Required for create; optional for edit.
-      required: false
-      selector:
-        text:
-    colour:
-      name: Colour
-      description: Optional colour string.
-      required: false
-      selector:
-        text:
-    avatar_ref:
-      name: Avatar
-      description: Optional avatar reference.
-      required: false
-      selector:
-        text:
-    sort_order:
-      name: Sort order
-      description: Optional panel sort order.
-      required: false
-      selector:
-        number:
-          mode: box
-    is_active:
-      name: Active
-      description: Required for set_active.
-      required: false
-      selector:
-        boolean:
-    ordered_ids:
-      name: Ordered IDs
-      description: Complete permutation of child ids. Required for reorder.
-      required: false
-      selector:
-        object:
+        text:

custom_components/nestquest/sse.py

@@ -0,0 +1,172 @@
+"""HA-bus subscription over the API service's panel SSE stream.
+
+The NestQuest API service (Feature 16) publishes every quest
+transition on ``GET /api/v1/panel/events`` as Server-Sent Events
+frames.  This module is the integration-side subscriber: ONE
+background task consumes :meth:`~.api_client.NestQuestApiClient
+.stream_events` and re-fires each frame on ``hass.bus`` with the SAME
+event type and payload fields the local transition path
+(:mod:`~.events`) emits — ``nestquest_quest_completed``,
+``nestquest_quest_uncompleted``, ``nestquest_quest_missed`` and
+``nestquest_child_day_complete`` — so the four blueprints fire
+identically whether a completion happens through the integration's own
+service or through the API service's panel route.
+
+Failure handling: a failed stream (API down, network blip, non-2xx, a
+dropped connection) is retried FOREVER with a bounded exponential
+backoff — :data:`RECONNECT_MIN_SECONDS` after the first failure,
+doubling up to :data:`RECONNECT_MAX_SECONDS` — so a long API outage
+neither pins the event loop nor spams the log, and a frame received on
+a healthy stream resets the backoff.  Nothing escapes the task: every
+failure is logged with its reason and the loop reconnects; a
+:class:`asyncio.CancelledError` (from :meth:`stop` or integration
+unload) is the only thing that ends it, and it stops cleanly — no
+frame fires after :meth:`stop` returns and the response is closed.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from .const import LOGGER
+
+__all__ = [
+    "NestQuestEventStream",
+    "RECONNECT_MAX_SECONDS",
+    "RECONNECT_MIN_SECONDS",
+]
+
+#: Delay before the FIRST reconnect attempt after a stream failure.
+#: One failed frame must not turn into a hot reconnect loop.
+RECONNECT_MIN_SECONDS = 5.0
+
+#: Ceiling for the exponential reconnect backoff: a long API outage
+#: retries at a calm fixed cadence instead of growing without bound.
+RECONNECT_MAX_SECONDS = 60.0
+
+
+class NestQuestEventStream:
+    """Consume the panel SSE stream in the background, fire the HA bus.
+
+    ONE instance per config entry, built in integration setup with the
+    SAME API client the coordinator polls (the client is stateless —
+    one shared session, one connection pool).  ``start()`` schedules
+    the background task; ``stop()`` cancels and awaits it, so unload
+    never leaks the task and no frame fires after teardown.  The task
+    itself is failure-proof: any exception from the stream (typed
+    :class:`~.api_client.NestQuestApiError` or anything else) is
+    logged and retried after the current backoff, never allowed to
+    escape the task.
+    """
+
+    def __init__(
+        self,
+        hass: Any,
+        client: Any,
+        *,
+        reconnect_min_seconds: float = RECONNECT_MIN_SECONDS,
+        reconnect_max_seconds: float = RECONNECT_MAX_SECONDS,
+    ) -> None:
+        """Store the hass bus target, the API client, and the backoff.
+
+        The client is anything exposing ``stream_events()`` (the real
+        :class:`~.api_client.NestQuestApiClient` in production, a stub
+        in tests).  The backoff bounds must be positive and the minimum
+        must not exceed the maximum — a misconfiguration should fail
+        loudly at construction, not quietly reconnect at delay 0.
+        """
+        if (
+            not isinstance(reconnect_min_seconds, (int, float))
+            or isinstance(reconnect_min_seconds, bool)
+            or reconnect_min_seconds <= 0
+            or reconnect_min_seconds > reconnect_max_seconds
+        ):
+            raise ValueError(
+                "reconnect_min_seconds must be a positive number no "
+                f"greater than reconnect_max_seconds, got "
+                f"{reconnect_min_seconds!r}"
+            )
+        if (
+            not isinstance(reconnect_max_seconds, (int, float))
+            or isinstance(reconnect_max_seconds, bool)
+            or reconnect_max_seconds <= 0
+        ):
+            raise ValueError(
+                f"reconnect_max_seconds must be a positive number, got "
+                f"{reconnect_max_seconds!r}"
+            )
+        self._hass = hass
+        self._client = client
+        self._min_backoff = float(reconnect_min_seconds)
+        self._max_backoff = float(reconnect_max_seconds)
+        self._backoff = float(reconnect_min_seconds)
+        self._task: asyncio.Task | None = None
+
+    @property
+    def task(self) -> asyncio.Task | None:
+        """The background task, or ``None`` when never started/stopped."""
+        return self._task
+
+    def start(self) -> None:
+        """Schedule the subscription task (idempotent while it runs)."""
+        if self._task is not None and not self._task.done():
+            return
+        self._backoff = self._min_backoff
+        self._task = asyncio.create_task(
+            self._run(), name="nestquest-sse-subscription"
+        )
+
+    async def stop(self) -> None:
+        """Cancel and await the subscription task.
+
+        Returns only after the task has actually finished, so unload
+        can rely on: no further frame is fired after ``stop()``, and
+        the underlying stream response has been closed.  Safe to call
+        when the task was never started or already stopped.
+        """
+        task, self._task = self._task, None
+        if task is None:
+            return
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            # The task's own cancellation surfaces here — expected and
+            # swallowed; a cancelling the CALLER would re-raise out of
+            # the surrounding await on its own.
+            pass
+
+    async def _run(self) -> None:
+        """Consume stream frames forever, reconnecting on failure."""
+        while True:
+            try:
+                async for event_type, payload in self._client.stream_events():
+                    # A frame arrived on a healthy stream: the next
+                    # failure reconnects quickly again.
+                    self._backoff = self._min_backoff
+                    try:
+                        self._hass.bus.async_fire(event_type, dict(payload))
+                    except Exception as err:
+                        # Firing one frame must never tear down a
+                        # healthy connection: log and keep consuming.
+                        LOGGER.error(
+                            "NestQuest panel event %s could not be fired "
+                            "on the Home Assistant event bus: %s",
+                            event_type,
+                            err,
+                        )
+            except asyncio.CancelledError:
+                # Unload / shutdown: stop cleanly, never converted.
+                raise
+            except Exception as err:
+                delay = self._backoff
+                self._backoff = min(
+                    self._backoff * 2, self._max_backoff
+                )
+                LOGGER.warning(
+                    "NestQuest panel event stream failed (%s); "
+                    "reconnecting in %.1f s",
+                    err,
+                    delay,
+                )
+                await asyncio.sleep(delay)

custom_components/nestquest/store.py

@@ -1,32 +0,0 @@
-"""Re-export of :mod:`custom_components.nestquest.core.store` for the integration package.
-
-The path resolver lives in
-:mod:`custom_components.nestquest.core.store` (extracted in task
-d0b691d8) and is Home-Assistant-free:
-:func:`custom_components.nestquest.core.store.async_get_db_path`
-takes the full database path.  This module re-exports it and provides
-the original ``async_get_db_path(hass)`` signature so the integration
-resolves the path from ``hass.config.path`` exactly as before.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-from homeassistant.core import HomeAssistant
-
-from .core.const import SQLITE_DB_FILENAME
-from .core.store import async_get_db_path as _core_async_get_db_path
-from .core.store import _ensure_dir
-
-__all__ = ["async_get_db_path", "_ensure_dir"]
-
-
-async def async_get_db_path(hass: HomeAssistant) -> Path:
-    """Return the absolute path to the NestQuest SQLite database file.
-
-    Resolves the database file from ``hass.config.path`` and delegates to
-    :func:`custom_components.nestquest.core.store.async_get_db_path`,
-    which ensures the parent directory exists off the event loop via
-    :func:`asyncio.to_thread`.
-    """
-    return await _core_async_get_db_path(hass.config.path(SQLITE_DB_FILENAME))

custom_components/nestquest/strings.json

@@ -18,20 +18,19 @@
     "step": {
       "init": {
         "title": "NestQuest Settings",
-        "description": "Adjust how NestQuest plans, rolls over days, and idles its panel.",
+        "description": "Adjust how the NestQuest API client polls and reaches the NestQuest API service.",
         "data": {
-          "horizon_days": "Generation horizon (days)",
-          "day_rollover_time": "Day rollover time (HH:MM)",
           "panel_idle_timeout": "Panel idle timeout (seconds)",
-          "admin_user_ids": "Admin users (parents)"
+          "snapshot_staleness": "Last-good snapshot staleness (seconds)",
+          "api_base_url": "NestQuest API base URL (http://host:port)",
+          "panel_token": "Panel service token"
         }
       }
     },
     "errors": {
       "invalid": "Invalid value.",
-      "invalid_time": "Time must use 24-hour HH:MM format.",
-      "no_admins": "Select at least one admin user; an empty allowlist would lock everyone out.",
-      "invalid_admin": "Invalid admin selection."
+      "invalid_url": "Enter the API base URL as a full http:// or https:// URL with a host.",
+      "invalid_staleness": "Last-good snapshot staleness must be at least the update interval."
     }
   }
 }

custom_components/nestquest/sweep.py

@@ -1,72 +0,0 @@
-"""The nightly missed-quest sweep (Feature 11) — the Home Assistant shim.
-
-The sweep's policy is the HA-free core's :mod:`~.core.sweep`: the
-watermark read → ``list_missed_unswept`` query → payload build →
-watermark span, all inside the per-database sweep lock, shared with
-the API plane.  This module is the integration's thin adapter over it:
-at the configured day-rollover time (the same HA-local listener that
-re-materializes the rolling horizon) and once at setup it calls the
-core's :func:`~.core.sweep.run_missed_sweep` and fires each returned
-event on ``hass.bus`` — ONE ``nestquest_quest_missed`` per past-due
-open instance with the documented payload.  The core never touches
-Home Assistant; the firing lives here.
-
-Idempotency is the core's watermark: after a run, ``nestquest_meta_state``
-records the HA-local date the sweep ran, and the next run only sweeps
-instances due in ``[watermark, today)`` — a second run the same night
-fires nothing new, and a run after days of downtime sweeps exactly the
-accumulated window once.  An instance swept as missed that is later
-completed simply gains its completion event; the sweep is read-only
-over the domain tables (``missed`` is derived state, never an
-event_type — Feature 08's contract).
-"""
-from __future__ import annotations
-
-import datetime
-import logging
-from zoneinfo import ZoneInfo
-
-from .core.sweep import (
-    SWEEP_WATERMARK_KEY,
-    run_missed_sweep as _run_core_missed_sweep,
-)
-from .db import NestQuestDatabase
-
-LOGGER = logging.getLogger(__name__)
-
-__all__ = ["SWEEP_WATERMARK_KEY", "run_missed_sweep"]
-
-
-async def run_missed_sweep(
-    hass,
-    database: NestQuestDatabase,
-    *,
-    today: datetime.date | None = None,
-) -> int:
-    """Fire one missed event per unswept past-due open instance.
-
-    ``today`` optionally pins the HA-local date (threaded like the
-    materialization and completion layers); when omitted it is read
-    from ``hass.config.time_zone``.  Returns the number of events
-    fired.  Fires nothing and returns 0 when the watermark already
-    covers ``today`` (a same-night rerun) — the watermark read, the
-    query, the payload build and the watermark write all live in the
-    core's locked
-    :func:`~.core.sweep.run_missed_sweep`; this shim only fires each
-    returned event on the bus and counts them.
-    """
-    today_date = (
-        today
-        if today is not None
-        else datetime.datetime.now(ZoneInfo(hass.config.time_zone)).date()
-    )
-    events = await _run_core_missed_sweep(database, today=today_date)
-    for event_type, payload in events:
-        hass.bus.async_fire(event_type, payload)
-    fired = len(events)
-    LOGGER.info(
-        "NestQuest missed sweep for %s fired %d event(s)",
-        today_date.isoformat(),
-        fired,
-    )
-    return fired

custom_components/nestquest/translations/en.json

@@ -18,20 +18,19 @@
     "step": {
       "init": {
         "title": "NestQuest Settings",
-        "description": "Adjust how NestQuest plans, rolls over days, and idles its panel.",
+        "description": "Adjust how the NestQuest API client polls and reaches the NestQuest API service.",
         "data": {
-          "horizon_days": "Generation horizon (days)",
-          "day_rollover_time": "Day rollover time (HH:MM)",
           "panel_idle_timeout": "Panel idle timeout (seconds)",
-          "admin_user_ids": "Admin users (parents)"
+          "snapshot_staleness": "Last-good snapshot staleness (seconds)",
+          "api_base_url": "NestQuest API base URL (http://host:port)",
+          "panel_token": "Panel service token"
         }
       }
     },
     "errors": {
       "invalid": "Invalid value.",
-      "invalid_time": "Time must use 24-hour HH:MM format.",
-      "no_admins": "Select at least one admin user; an empty allowlist would lock everyone out.",
-      "invalid_admin": "Invalid admin selection."
+      "invalid_url": "Enter the API base URL as a full http:// or https:// URL with a host.",
+      "invalid_staleness": "Last-good snapshot staleness must be at least the update interval."
     }
   }
 }

deploy/nestquest-controller.service

@@ -0,0 +1,14 @@
+[Unit]
+Description=NestQuest OpenCode controller
+
+[Service]
+Type=simple
+WorkingDirectory=/mnt/ai-storage/projects/NestQuest
+ExecStartPre=/home/overseer/.local/share/nestquest-controller/scripts/nq-controller --check
+ExecStart=/home/overseer/.local/share/nestquest-controller/scripts/nq-controller
+Restart=on-failure
+RestartSec=60s
+RestartPreventExitStatus=77
+TimeoutStartSec=0
+KillMode=control-group
+Environment=PYTHONUNBUFFERED=1

deploy/opencode-global-commands/start-nestquest-development.md

@@ -0,0 +1,11 @@
+---
+description: Run the NestQuest orchestrator now in this OpenCode terminal
+agent: terminal-orchestrator
+---
+
+Run the NestQuest project queue now in this foreground OpenCode session.
+Read the current CTXD prompt and Maestro state, but use the FOREGROUND
+TERMINAL RUNTIME instead of the service runtime. Reconcile repository and
+pull-request state, then execute CONTROLLER_TICK repeatedly until a global
+terminal condition, explicit user stop, genuine global block, or host-forced
+yield. Do not start or wait for the systemd controller.

frontend/package-lock.json

@@ -9,10 +9,197 @@
         "lit": "^3.3.0"
       },
       "devDependencies": {
+        "jsdom": "^30.1.1",
         "typescript": "^5.9.2",
         "vite": "^7.1.5"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-7.0.1.tgz",
+      "integrity": "sha512-C9duntabagkBZ1LebM7FKmphR4Q1pBclLxVbZETQV0akkFjV0ooFxo8FlvAQyKj9F6l8rEnmidgcTlpyxFYizg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/css-calc": "^3.4.0",
+        "@csstools/css-color-parser": "^4.2.3",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.1",
+        "lru-cache": "^11.5.3"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector": {
+      "version": "9.2.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-9.2.1.tgz",
+      "integrity": "sha512-NT4s3yZLjovPpliRpTvdsdzyPjqRqiCZj9MxnarBihbaY5MbAG7DWAJcrLlhmC7xKTNCXsTELcqB8YsqpLnUFQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bidi-js": "^1.1.0",
+        "css-tree": "^3.2.1",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.5.3"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
+    "node_modules/@bramus/specificity": {
+      "version": "2.4.2",
+      "resolved": "https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz",
+      "integrity": "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "^3.0.0"
+      },
+      "bin": {
+        "specificity": "bin/cli.js"
+      }
+    },
+    "node_modules/@csstools/color-helpers": {
+      "version": "6.1.1",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.1.1.tgz",
+      "integrity": "sha512-gLNsunvwf3mCi5u5o46/Z/JcJMnhbHSaZ69rkgPzNM3J4s8hWwpPUQB6/tt0EDFyCiWzxANlx+2LJwpYj4zS1w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.4.0.tgz",
+      "integrity": "sha512-XQKj5B7QiZcHiegCOCAzcAOJdhGgWOHbbu62h5e5mkHnn8lWcfiJhllkqWmxu5zWR9jucPHuo1iTB56P033hcg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.2.3.tgz",
+      "integrity": "sha512-y4LpL+lmpuyKDiEFq2PnZUVFdAjsoB/qQJod79yLNokXyW7jewi+/WJ69EfItj8A2unWtxXnGjw6LYXgXu5ZjA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.1.1",
+        "@csstools/css-calc": "^3.4.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz",
+      "integrity": "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-syntax-patches-for-csstree": {
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.14.tgz",
+      "integrity": "sha512-HpbVXyrofRXpHpgkNIjU/3EWR4WJvOkO3emNK/L6X/mTJU7bGUI3AkkpoTNXznQLp0KRjLHELTGeKI5dIkI9JQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "peerDependencies": {
+        "css-tree": "^3.2.1"
+      },
+      "peerDependenciesMeta": {
+        "css-tree": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.1.tgz",
+      "integrity": "sha512-bPlN9S9O1A0euCpEWE4qnvB5YDuyYVsUTrxSgmAM1Is0j4tICHoVyOVAXfWMP/kS9ZrjvyIXWV2PmomiAXXqOw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.28.2",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
@@ -455,6 +642,24 @@
         "node": ">=18"
       }
     },
+    "node_modules/@exodus/bytes": {
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.16.0.tgz",
+      "integrity": "sha512-IcpW84uEn3N7ETtNZMlxKhfl6Pec8rUNGOTBtWbK1FKhJxIFAptZyVrvVRVBimAJxJCgc3PxepxkdWWG4DVzfA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "@noble/hashes": "^1.8.0 || ^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@noble/hashes": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@lit-labs/ssr-dom-shim": {
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/@lit-labs/ssr-dom-shim/-/ssr-dom-shim-1.6.0.tgz",
@@ -892,6 +1097,79 @@
       "integrity": "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==",
       "license": "MIT"
     },
+    "node_modules/bidi-js": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.1.0.tgz",
+      "integrity": "sha512-fX1Onk0tdVPC7obPWB5EbJ1z7NVhLq4m2xZLq2YXBkxzMXIGRpNMU88n0EPgWseKl12J7zXs7qrDxPK4sRs2fg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
+    "node_modules/css-tree": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
+      "integrity": "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.27.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
+    "node_modules/data-urls": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz",
+      "integrity": "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/data-urls/node_modules/whatwg-url": {
+      "version": "16.0.1",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
+      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.11.0",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/entities": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-8.1.0.tgz",
+      "integrity": "sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
     "node_modules/esbuild": {
       "version": "0.28.2",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
@@ -967,6 +1245,66 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
+    "node_modules/html-encoding-sniffer": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-7.0.0.tgz",
+      "integrity": "sha512-UikN5yr7xsCDAq87Or5or0PAlD3HJJOKVzM05az588WnpDJ4Ux7a2A53Qi6gofGg2/EtvF/H4hCi/TXfCW4Y6w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.15.1"
+      },
+      "engines": {
+        "node": "^22.13.0 || >=24.0.0"
+      }
+    },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/jsdom": {
+      "version": "30.1.1",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-30.1.1.tgz",
+      "integrity": "sha512-FahmoPK5vbPc+jxV1iErMHmAZypCZ942NHF4+qqaWAuvaKKTBZxawnmAtrbGWLU7MtlxfqIP0qw6aSI+aWGtLg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/css-color": "^7.0.0",
+        "@asamuzakjp/dom-selector": "^9.2.1",
+        "@bramus/specificity": "^2.4.2",
+        "@csstools/css-syntax-patches-for-csstree": "^1.1.13",
+        "@exodus/bytes": "^1.15.1",
+        "css-tree": "^3.2.1",
+        "data-urls": "^7.0.0",
+        "decimal.js": "^10.6.0",
+        "html-encoding-sniffer": "^7.0.0",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.5.2",
+        "parse5": "^8.0.1",
+        "saxes": "^6.0.0",
+        "tough-cookie": "^6.0.2",
+        "undici": "^8.10.2",
+        "w3c-xmlserializer": "^6.0.0",
+        "webidl-conversions": "^8.0.1",
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^17.1.1",
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      },
+      "peerDependencies": {
+        "canvas": "^3.2.3"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/lit": {
       "version": "3.3.3",
       "resolved": "https://registry.npmjs.org/lit/-/lit-3.3.3.tgz",
@@ -998,6 +1336,23 @@
         "@types/trusted-types": "^2.0.2"
       }
     },
+    "node_modules/lru-cache": {
+      "version": "11.5.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz",
+      "integrity": "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/mdn-data": {
+      "version": "2.27.1",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
+      "integrity": "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==",
+      "dev": true,
+      "license": "CC0-1.0"
+    },
     "node_modules/nanoid": {
       "version": "3.3.19",
       "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.19.tgz",
@@ -1017,6 +1372,19 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
+      "integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^8.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -1066,6 +1434,26 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/rollup": {
       "version": "4.63.4",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.63.4.tgz",
@@ -1112,6 +1500,19 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -1139,6 +1540,52 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tldts": {
+      "version": "7.4.14",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.4.14.tgz",
+      "integrity": "sha512-EahQoi+Q5oqmG3yxRHx+bwn36OaLbtw6jnTFcGjc8fcmktzTgk45xRnzAx8Ch87PFEiqRhoc3FWBmY+LBrvEGQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^7.4.14"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "7.4.14",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.4.14.tgz",
+      "integrity": "sha512-KYkjfJHnIC5t+Gy7hPrMHgJmWc/N9FfmS+fggRPSlpFckidpB9HD6OzPsSTkfDH+MpZgcu2tJPGgLfHl979N1Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tough-cookie": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.2.tgz",
+      "integrity": "sha512-exgYmnmL/sJpR3upZfXG5PoatXQii55xAiXGXzY+sROLZ/Y+SLcp9PgJNI9Vz37HpQ74WvDcLT8eqm+kV3FzrA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "tldts": "^7.0.5"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/typescript": {
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
@@ -1153,6 +1600,16 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/undici": {
+      "version": "8.11.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-8.11.0.tgz",
+      "integrity": "sha512-AdzuGcAkzhbha3GgCSoUBx2P0quwym6qdFNCQz/fDGZc8w9XJ741wHUbt2kTmfPz+ZIOMkySFkiY7RXmiDDC8w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=22.19.0"
+      }
+    },
     "node_modules/vite": {
       "version": "7.3.6",
       "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.6.tgz",
@@ -1227,6 +1684,71 @@
           "optional": true
         }
       }
+    },
+    "node_modules/w3c-xmlserializer": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-6.0.0.tgz",
+      "integrity": "sha512-4Nsy8K5Tr6SPDH9jhKJOHf7ChDrc1zufZTVSF7x72hwuEXBqxqk9G6cK+K2NRUtB3iELRJqjXb4JPDMBjMTl2Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
+      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "17.1.2",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-17.1.2.tgz",
+      "integrity": "sha512-TEZA+Zqxin7Jjsm2cjRohCmen5awh+hT6Zi3VZdqZlNRk7zvOI/9WpBFg/DWlA56bWnzwm6DuB8NS0EsxQH9uQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.15.1",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^22.14.0 || >=24.0.0"
+      }
+    },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "dev": true,
+      "license": "MIT"
     }
   }
 }

frontend/package.json

@@ -9,6 +9,7 @@
     "lit": "^3.3.0"
   },
   "devDependencies": {
+    "jsdom": "^30.1.1",
     "typescript": "^5.9.2",
     "vite": "^7.1.5"
   }

frontend/src/cards/party-board.ts

@@ -143,6 +143,16 @@ function asNumber(value: unknown, fallback: number): number {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+/** The slug a discovered roster entry carries, or "" when the entry is
+ *  not an object with a non-empty slug string. */
+function asRosterSlug(entry: unknown): string {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return "";
+  }
+  const slug = (entry as Record<string, unknown>).slug;
+  return typeof slug === "string" ? slug.trim() : "";
+}
+
 function clampPercent(value: number): number {
   if (!Number.isFinite(value)) {
     return 0;
@@ -892,15 +902,34 @@ export class NestQuestPartyBoardCard extends LitElement {
       return [];
     }
     const order = this._config.child_order;
-    if (!Array.isArray(order)) {
+    if (Array.isArray(order)) {
+      return order
+        .filter(
+          (entry): entry is string =>
+            typeof entry === "string" && entry.trim().length > 0
+        )
+        .map((entry) => entry.trim());
+    }
+    return this._discoveredChildSlugs();
+  }
+
+  /** Zero-config discovery (Feature 20): the ordered child roster the
+   *  integration publishes on the household rollup
+   *  (custom_components/nestquest/sensor.py — ``child_roster``, the
+   *  snapshot's sort_order, then id), each entry carrying the slug the
+   *  per-child entity ids are built from.  Consulted only when the
+   *  config has no child_order — explicit configuration wins. */
+  private _discoveredChildSlugs(): string[] {
+    const household = this._state(
+      "sensor.nestquest_household_quests_due_today"
+    );
+    const roster = household?.attributes?.child_roster;
+    if (!Array.isArray(roster)) {
       return [];
     }
-    return order
-      .filter(
-        (entry): entry is string =>
-          typeof entry === "string" && entry.trim().length > 0
-      )
-      .map((entry) => entry.trim());
+    return roster
+      .map((entry) => asRosterSlug(entry))
+      .filter((slug) => slug.length > 0);
   }
 
   private _plates(): ChildPlate[] {

frontend/src/nestquest-cards.ts

@@ -1,6 +1,7 @@
 import "./cards/party-board";
 import "./cards/quest-log";
 import "./cards/admin";
+import "./strategy";
 
 const FONTS_HREF = "/nestquest-static/nestquest-fonts.css";
 if (!document.querySelector('link[data-nq-fonts=""]')) {

frontend/src/strategy.ts

@@ -0,0 +1,161 @@
+import type { HassLike } from "./types";
+
+type StateObject = {
+  state: unknown;
+  attributes?: Record<string, unknown> | null;
+};
+
+type RosterEntry = {
+  name: string;
+  slug: string;
+};
+
+type View = {
+  path?: string;
+  title?: string;
+  type: string;
+  cards: Record<string, unknown>[];
+};
+
+type LovelaceConfig = {
+  views: View[];
+};
+
+type StrategyConfig = Record<string, unknown>;
+
+type StrategyClass = {
+  generate: (
+    config: StrategyConfig,
+    hass: HassLike | undefined
+  ) => Promise<LovelaceConfig>;
+};
+
+declare global {
+  interface Window {
+    customStrategies?: Record<string, StrategyClass>;
+  }
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/** The slug a discovered roster entry carries, or "" when the entry is
+ *  not an object with a non-empty slug string — the same shape check
+ *  the party board applies to the same attribute. */
+function asRosterSlug(entry: unknown): string {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return "";
+  }
+  const slug = (entry as Record<string, unknown>).slug;
+  return typeof slug === "string" ? slug.trim() : "";
+}
+
+/** The dashboard's URL path segment, used to COMPUTE the card paths the
+ *  navigation needs.  A dashboard lives at a single top-level segment
+ *  (/<url_path>), so the first pathname segment is the dashboard root —
+ *  this is where the strategy renders, and navigating back to it shows
+ *  the first view (the party board).  An explicit ``url_path`` in the
+ *  strategy configuration wins for setups that need to pin it. */
+function dashboardUrlPath(config: StrategyConfig): string {
+  const configured = asString(config.url_path).replace(/^\/+|\/+$/g, "");
+  if (configured) {
+    return configured;
+  }
+  const segment = window.location.pathname.split("/").filter(Boolean)[0];
+  return segment ?? "";
+}
+
+/** The display name a roster entry carries, or "" when it is not a
+ *  non-empty string — the roster's ``name`` field (sensor.py
+ *  ``_child_roster``), used for the quest-log view titles. */
+function asRosterName(entry: unknown): string {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return "";
+  }
+  const name = (entry as Record<string, unknown>).name;
+  return typeof name === "string" ? name.trim() : "";
+}
+
+/** The ordered child roster the integration publishes on the household
+ *  rollup (custom_components/nestquest/sensor.py — ``child_roster``,
+ *  the snapshot's sort_order, then id).  The same source the party
+ *  board's plate discovery reads, consumed here at render time so the
+ *  quest-log views exist for exactly the active children. */
+function rosterEntries(hass: HassLike | undefined): RosterEntry[] {
+  const states = hass?.states as Record<string, StateObject> | undefined;
+  const household = states?.["sensor.nestquest_household_quests_due_today"];
+  const roster = household?.attributes?.child_roster;
+  if (!Array.isArray(roster)) {
+    return [];
+  }
+  return roster
+    .map((entry) => ({ slug: asRosterSlug(entry), name: asRosterName(entry) }))
+    .filter((entry) => entry.slug.length > 0);
+}
+
+/**
+ * Zero-config NestQuest dashboard strategy (Feature 20).
+ *
+ * A dashboard configured with ``strategy: { type: custom:nestquest-party }``
+ * gets its views GENERATED at render time from the household roster: one
+ * party-board view (the dashboard root) and one quest-log view per child,
+ * ordered by the roster's sort_order.  The paths the cards navigate by are
+ * COMPUTED, not configured:
+ *
+ * - the board's ``quest_log_path`` is the dashboard root; tapping a crest
+ *   pushes ``<root>/<slug>`` (party-board.ts ``_openQuestLog``);
+ * - each log view's ``path`` IS the child's slug, so the log resolves its
+ *   child from the last pathname segment (quest-log.ts
+ *   ``childSlugFromPath``) and its ``board_path`` back to the dashboard
+ *   root (quest-log.ts ``_returnToBoard``).
+ *
+ * With zero children the board view still renders — the board card shows
+ * its own "not set up yet" notice for an empty roster, so no log views are
+ * needed.  ``url_path`` and ``weather_entity`` may still be set explicitly
+ * in the strategy configuration; everything else is derived.
+ */
+export class NestQuestPartyStrategy {
+  static async generate(
+    config: StrategyConfig,
+    hass: HassLike | undefined
+  ): Promise<LovelaceConfig> {
+    const root = `/${dashboardUrlPath(config)}`;
+    const weatherEntity = asString(config.weather_entity);
+    const boardCard: Record<string, unknown> = {
+      type: "custom:nestquest-party-board-card",
+      quest_log_path: root,
+    };
+    if (weatherEntity) {
+      boardCard.weather_entity = weatherEntity;
+    }
+    const logCard: Record<string, unknown> = {
+      type: "custom:nestquest-quest-log-card",
+      board_path: root,
+    };
+    if (weatherEntity) {
+      logCard.weather_entity = weatherEntity;
+    }
+    return {
+      views: [
+        {
+          path: "party",
+          title: "The Party",
+          type: "panel",
+          cards: [boardCard],
+        },
+        ...rosterEntries(hass).map<View>((entry) => ({
+          path: entry.slug,
+          title: entry.name
+            ? `${entry.name}'s Quest Log`
+            : `${entry.slug}'s Quest Log`,
+          type: "panel",
+          cards: [{ ...logCard }],
+        })),
+      ],
+    };
+  }
+}
+
+window.customStrategies = window.customStrategies ?? {};
+window.customStrategies["nestquest-party"] = NestQuestPartyStrategy;

frontend/tests/render-party-board.mjs

@@ -0,0 +1,56 @@
+/**
+ * Render the built party-board card under jsdom and print its plates.
+ *
+ * Usage: node render-party-board.mjs < spec.json
+ *
+ * The spec JSON carries {bundle, tag, config, hass}; stdout receives one JSON
+ * object {plates, html} where plates is the ordered plate list the shadow DOM
+ * renders (name + present/away/unknown kind). The Python panel tests drive
+ * this harness so the assertions run against the exact bundle HACS ships.
+ */
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { JSDOM } from "jsdom";
+
+const spec = JSON.parse(readFileSync(0, "utf8"));
+
+const dom = new JSDOM("<!doctype html><html><body></body></html>", {
+  url: "http://homeassistant.local/nestquest/board",
+  pretendToBeVisual: true,
+});
+
+// Expose the jsdom globals the Lit bundle expects. Node's own intrinsics
+// (Object, Array, ...) are kept — only what globalThis lacks is copied.
+for (const key of Object.getOwnPropertyNames(dom.window)) {
+  if (!(key in globalThis)) {
+    try {
+      globalThis[key] = dom.window[key];
+    } catch {
+      // jsdom getters may throw on access; the card does not need them.
+    }
+  }
+}
+globalThis.window = dom.window;
+
+await import(pathToFileURL(spec.bundle).href);
+
+const element = document.createElement(spec.tag);
+element.setConfig(spec.config);
+element.hass = spec.hass;
+document.body.appendChild(element);
+await element.updateComplete;
+
+const plates = [
+  ...element.shadowRoot.querySelectorAll(".plates .plate"),
+].map((plate) => ({
+  name: plate.querySelector(".name")?.textContent?.trim() ?? "",
+  kind: plate.classList.contains("unknown")
+    ? "unknown"
+    : plate.classList.contains("away")
+      ? "away"
+      : "present",
+}));
+
+const payload = JSON.stringify({ plates, html: element.shadowRoot.innerHTML });
+await new Promise((resolve) => process.stdout.write(payload, () => resolve()));
+process.exit(0);

frontend/tests/render-strategy.mjs

@@ -0,0 +1,48 @@
+/**
+ * Import the built bundle into jsdom and generate the dashboard strategy's
+ * views.
+ *
+ * Usage: node render-strategy.mjs < spec.json
+ *
+ * The spec JSON carries {bundle, url, config, hass}; stdout receives one
+ * JSON object {views} — the strategy output's views array with the paths
+ * and card configs the generated dashboard renders.  The Python panel
+ * tests drive this harness so the assertions run against the exact bundle
+ * HACS ships.
+ */
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { JSDOM } from "jsdom";
+
+const spec = JSON.parse(readFileSync(0, "utf8"));
+
+const dom = new JSDOM("<!doctype html><html><body></body></html>", {
+  url: spec.url ?? "http://homeassistant.local/nestquest/party",
+  pretendToBeVisual: true,
+});
+
+// Expose the jsdom globals the Lit bundle expects. Node's own intrinsics
+// (Object, Array, ...) are kept — only what globalThis lacks is copied.
+for (const key of Object.getOwnPropertyNames(dom.window)) {
+  if (!(key in globalThis)) {
+    try {
+      globalThis[key] = dom.window[key];
+    } catch {
+      // jsdom getters may throw on access; the strategy does not need them.
+    }
+  }
+}
+globalThis.window = dom.window;
+
+await import(pathToFileURL(spec.bundle).href);
+
+const strategy = window.customStrategies?.["nestquest-party"];
+if (!strategy) {
+  console.error("nestquest-party strategy is not registered on the bundle");
+  process.exit(1);
+}
+
+const lovelace = await strategy.generate(spec.config, spec.hass);
+const payload = JSON.stringify({ views: lovelace.views });
+await new Promise((resolve) => process.stdout.write(payload, () => resolve()));
+process.exit(0);

orchestration_tests/test_cycle_prompt.py

@@ -0,0 +1,56 @@
+import json
+from pathlib import Path
+import runpy
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+RENDER = runpy.run_path(str(ROOT / "scripts/render-cycle-prompt"))["render"]
+TEMPLATE = (ROOT / "templates/ORCHESTRATOR-PROMPT.template.md").read_text()
+PROFILE = json.loads((ROOT / "templates/nestquest.profile.json").read_text())
+
+
+class CyclePromptTests(unittest.TestCase):
+    def test_project_profile_renders_without_specific_source_names(self):
+        other = PROFILE.copy()
+        other.update({
+            "PROJECT_NAME": "ExampleQuest",
+            "PROJECT_CONTEXT_LABEL": "EXAMPLEQUEST COORDINATION",
+            "WORK_TRACKER": "TaskGrid",
+            "CONTEXT_STORE": "ContextHub",
+            "INTEGRATION_BRANCH": "integration",
+            "RELEASE_BRANCH": "production",
+            "CONTROL_HOME": "/opt/examplequest/controller",
+            "SERVICE_NAME": "examplequest-controller.service",
+            "PROJECT_ROOT": "/srv/examplequest",
+            "TERMINAL_LAUNCHER": "eq-orchestrate",
+            "FEATURE_BRANCH_EXAMPLE": "feature/EQ-17",
+        })
+        output = RENDER(TEMPLATE, other)
+        self.assertIn("ExampleQuest Persistent Autonomous", output)
+        self.assertIn("TaskGrid", output)
+        self.assertIn("ContextHub", output)
+        self.assertIn("feature/EQ-17", output)
+        self.assertNotIn("NestQuest", output)
+        self.assertNotIn("nestquest", output)
+        self.assertNotIn("Maestro", output)
+        self.assertNotIn("CTXD", output)
+        self.assertNotIn("{{", output)
+
+    def test_missing_value_fails_before_publication(self):
+        other = PROFILE.copy()
+        del other["PROJECT_NAME"]
+        with self.assertRaisesRegex(ValueError, "PROJECT_NAME"):
+            RENDER(TEMPLATE, other)
+
+    def test_template_contains_only_terminal_runtime(self):
+        output = RENDER(TEMPLATE, PROFILE)
+        self.assertIn("# 27. FOREGROUND TERMINAL RUNTIME", output)
+        self.assertIn("nq-orchestrate", output)
+        self.assertNotIn("# 27. HOST CONTROLLER RUNTIME", output)
+        self.assertNotIn("The persistent user service runs", output)
+        self.assertNotIn("---\n\n---\n\n# 27", output)
+
+
+if __name__ == "__main__":
+    unittest.main()

orchestration_tests/test_nq_approve_merge.py

@@ -0,0 +1,88 @@
+from pathlib import Path
+import contextlib
+import io
+import runpy
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+
+APPROVE = runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/nq-approve-merge"))
+HEAD = "a" * 40
+
+
+class MergeGateTests(unittest.TestCase):
+    def test_main_rejects_moved_head_unmergeable_and_pending_checks(self):
+        root = Path("/tmp/opencode")
+        root.mkdir(exist_ok=True)
+        with tempfile.TemporaryDirectory(dir=root) as directory:
+            review_file = Path(directory) / "review.txt"
+            review_file.write_text(f"REVIEWED_HEAD: {HEAD}\nREVIEW_VERDICT: APPROVED\n")
+            for problem in ("moved", "unmergeable", "pending", "none"):
+                with self.subTest(problem=problem):
+                    merged = False
+                    calls = []
+                    def fake_request(path, token, payload=None):
+                        nonlocal merged
+                        calls.append((path, payload))
+                        if path.endswith("/reviews"):
+                            return [{"id": 1, "state": "APPROVED", "commit_id": HEAD,
+                                     "user": {"login": "review_agent"}}]
+                        if path.endswith("/status"):
+                            return {"total_count": 1, "state": "pending" if problem == "pending" else "success"}
+                        if path.endswith("/merge"):
+                            merged = True
+                            return {}
+                        if path.endswith("/pulls/149"):
+                            return {"number": 149, "base": {"ref": "dev"},
+                                    "head": {"sha": "b" * 40 if problem == "moved" else HEAD},
+                                    "state": "open", "merged": merged,
+                                    "mergeable": problem != "unmergeable"}
+                        raise AssertionError(path)
+                    globals_ = APPROVE["main"].__globals__
+                    with patch.dict(globals_, {"request": fake_request,
+                                               "token_from_file": lambda: "test"}), \
+                         patch.object(sys, "argv", ["nq-approve-merge", "merge", "149", HEAD,
+                                                    str(review_file)]), \
+                         contextlib.redirect_stdout(io.StringIO()):
+                        if problem == "none":
+                            self.assertEqual(APPROVE["main"](), 0)
+                        else:
+                            with self.assertRaises(RuntimeError):
+                                APPROVE["main"]()
+                    self.assertEqual(merged, problem == "none")
+                    if problem == "none":
+                        merge_calls = [payload for path, payload in calls if path.endswith("/merge")]
+                        self.assertEqual(merge_calls,
+                                         [{"do": "squash", "head_commit_id": HEAD}])
+
+    def test_review_evidence_must_match_exact_head_and_approval(self):
+        root = Path("/tmp/opencode")
+        root.mkdir(exist_ok=True)
+        with tempfile.TemporaryDirectory(dir=root) as directory:
+            review = Path(directory) / "review.txt"
+            review.write_text(f"Findings: none\nREVIEWED_HEAD: {HEAD}\nREVIEW_VERDICT: APPROVED\n")
+            APPROVE["validate_review"](review, HEAD)
+            with self.assertRaisesRegex(RuntimeError, "exact head"):
+                APPROVE["validate_review"](review, "b" * 40)
+            review.write_text(f"REVIEWED_HEAD: {HEAD}\nREVIEW_VERDICT: CHANGES_REQUIRED\n")
+            with self.assertRaisesRegex(RuntimeError, "exact head"):
+                APPROVE["validate_review"](review, HEAD)
+
+    def test_requires_distinct_gitea_reviewer_on_exact_commit(self):
+        records = [{"state": "APPROVED", "commit_id": HEAD, "user": {"login": "review_agent"}}]
+        with patch.dict(APPROVE["has_platform_review"].__globals__, {"request": lambda *_: records}):
+            self.assertTrue(APPROVE["has_platform_review"](149, HEAD, "unused"))
+            self.assertFalse(APPROVE["has_platform_review"](149, "b" * 40, "unused"))
+            records[0]["user"]["login"] = "orchestrator-agent"
+            self.assertFalse(APPROVE["has_platform_review"](149, HEAD, "unused"))
+            records[:] = [
+                {"id": 1, "state": "APPROVED", "commit_id": HEAD, "user": {"login": "review_agent"}},
+                {"id": 2, "state": "REQUEST_CHANGES", "commit_id": HEAD, "user": {"login": "review_agent"}},
+            ]
+            self.assertFalse(APPROVE["has_platform_review"](149, HEAD, "unused"))
+
+
+if __name__ == "__main__":
+    unittest.main()

orchestration_tests/test_nq_controller.py

@@ -0,0 +1,108 @@
+import json
+import io
+from pathlib import Path
+import runpy
+import sqlite3
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+
+CONTROL = runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/nq-controller"))
+
+
+class ControllerProtocolTests(unittest.TestCase):
+    def test_ctxd_preflight_reads_configured_endpoint_and_checks_identity(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            config = root / ".config/opencode/opencode.json"
+            config.parent.mkdir(parents=True)
+            config.write_text(json.dumps({"mcp": {"ctxd": {
+                "url": "http://localhost:9091/mcp",
+                "headers": {"Authorization": "Bearer test"},
+            }}}))
+            record = {"project_id": CONTROL["CTXD_PROJECT"],
+                      "file_path": CONTROL["CTXD_FILE"],
+                      "content": "# CONTROLLER_TICK", "version": 6}
+            with patch.object(Path, "home", return_value=root), \
+                 patch.dict(CONTROL["check_ctxd"].__globals__["urllib"].request.__dict__,
+                            {"urlopen": lambda request, timeout: io.BytesIO(json.dumps(record).encode())}):
+                self.assertEqual(CONTROL["check_ctxd"](), 6)
+                record["project_id"] = "wrong"
+                with self.assertRaisesRegex(RuntimeError, "wrong NestQuest prompt"):
+                    CONTROL["check_ctxd"]()
+                record["project_id"] = CONTROL["CTXD_PROJECT"]
+                config.write_text(json.dumps({"mcp": {"ctxd": {
+                    "url": "http://localhost:9091/mcp/",
+                    "headers": {"Authorization": "Bearer test"},
+                }}}))
+                self.assertEqual(CONTROL["check_ctxd"](), 6)
+                config.write_text(json.dumps({"mcp": {"ctxd": {
+                    "url": "http://localhost:9091/invalid",
+                    "headers": {"Authorization": "Bearer test"},
+                }}}))
+                with self.assertRaisesRegex(RuntimeError, "must end in /mcp"):
+                    CONTROL["check_ctxd"]()
+
+    def test_installed_opencode_text_event(self):
+        event = {"type": "text", "sessionID": "ses_test", "part": {"type": "text", "text": "Next task queued.\nORCHESTRATOR_STATE: CONTINUE\n"}}
+        self.assertEqual(CONTROL["parse_event"](json.dumps(event)), (event["part"]["text"], None))
+        self.assertEqual(CONTROL["STATE_RE"].findall(event["part"]["text"]), ["CONTINUE"])
+
+    def test_error_event_does_not_publish_provider_message(self):
+        event = {"type": "error", "error": {"name": "APIError", "data": {"message": "secret provider response"}}}
+        self.assertEqual(CONTROL["parse_event"](json.dumps(event)), (None, "APIError"))
+        self.assertEqual(CONTROL["parse_event"]("null"), (None, None))
+        self.assertEqual(CONTROL["parse_event"]("[]"), (None, None))
+
+    def test_tick_uses_final_text(self):
+        event = json.dumps({"type": "text", "part": {"type": "text", "text": "ORCHESTRATOR_STATE: QUIESCENT\n"}})
+        command = [sys.executable, "-c", f"import json,sys; sys.stdin.read(); print({event!r})"]
+        status, answer, error = CONTROL["run_tick"](command, {}, "tick", 10)
+        self.assertEqual((status, error), (0, None))
+        self.assertEqual(CONTROL["STATE_RE"].findall(answer), ["QUIESCENT"])
+
+    def test_timeout_kills_child_group_and_marks_tick_failed(self):
+        command = [sys.executable, "-c", "import sys,time; sys.stdin.read(); time.sleep(10)"]
+        status, answer, error = CONTROL["run_tick"](command, {}, "tick", 1)
+        self.assertEqual(status, 124)
+        self.assertEqual(answer, "")
+        self.assertIn("timeout", error)
+
+    def test_interactive_session_detects_dir_and_resumed_session(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            project = root / "project"
+            project.mkdir()
+            proc = root / "proc"
+            entry = proc / "123"
+            entry.mkdir(parents=True)
+            (entry / "cwd").symlink_to(root)
+            database = root / "opencode.db"
+            with sqlite3.connect(database) as db:
+                db.execute("CREATE TABLE session (id TEXT, directory TEXT)")
+                db.execute("INSERT INTO session VALUES (?, ?)", ("ses_test", str(project)))
+            (entry / "cmdline").write_bytes(b"opencode\0--dir\0" + str(project).encode() + b"\0")
+            self.assertTrue(CONTROL["interactive_nestquest_session"](project, proc, database))
+            (entry / "cmdline").write_bytes(b"opencode\0web\0--dir\0" + str(project).encode() + b"\0")
+            self.assertTrue(CONTROL["interactive_nestquest_session"](project, proc, database))
+            (entry / "cmdline").write_bytes(b"opencode\0serve\0")
+            (entry / "cwd").unlink()
+            (entry / "cwd").symlink_to(project)
+            self.assertTrue(CONTROL["interactive_nestquest_session"](project, proc, database))
+            (entry / "cwd").unlink()
+            (entry / "cwd").symlink_to(root)
+            (entry / "cmdline").write_bytes(b"opencode\0-s\0ses_test\0")
+            self.assertTrue(CONTROL["interactive_nestquest_session"](project, proc, database))
+            (entry / "cmdline").write_bytes(b"opencode\0--dir\0" + str(root).encode() + b"\0")
+            self.assertFalse(CONTROL["interactive_nestquest_session"](project, proc, database))
+            with sqlite3.connect(database) as db:
+                db.execute("DROP TABLE session")
+            (entry / "cmdline").write_bytes(b"opencode\0-s\0ses_test\0")
+            with self.assertRaisesRegex(RuntimeError, "lookup failed"):
+                CONTROL["interactive_nestquest_session"](project, proc, database)
+
+
+if __name__ == "__main__":
+    unittest.main()

orchestration_tests/test_nq_orchestrate.py

@@ -0,0 +1,79 @@
+from pathlib import Path
+import os
+import subprocess
+import tempfile
+import unittest
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts/nq-orchestrate"
+
+
+class ForegroundLauncherTests(unittest.TestCase):
+    def test_launches_terminal_agent_with_rendered_and_user_prompt(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            control = root / "control"
+            scripts = control / "scripts"
+            agents = control / ".opencode/agents"
+            templates = control / "templates"
+            project = root / "project"
+            for path in (scripts, agents, templates, project):
+                path.mkdir(parents=True, exist_ok=True)
+            (templates / "nestquest.profile.json").write_text("{}")
+            (agents / "terminal-orchestrator.md").write_text("agent")
+            renderer = scripts / "render-cycle-prompt"
+            renderer.write_text("#!/bin/sh\nprintf 'BASE TERMINAL PROMPT'")
+            controller = scripts / "nq-controller"
+            controller_args = root / "controller-args"
+            open_marker = root / "open-session"
+            controller.write_text(
+                f"#!/bin/sh\nprintf '%s\\n' \"$@\" > {controller_args}\n"
+                f"if test -f {open_marker}; then printf 'interactive NestQuest session open\\n'; "
+                "else printf 'no interactive NestQuest session\\n'; fi\n"
+            )
+            opencode = root / "opencode"
+            output = root / "args"
+            opencode.write_text(f"#!/bin/sh\nprintf '%s\\n' \"$@\" > {output}\n")
+            systemctl = root / "systemctl"
+            stopped = root / "stopped"
+            systemctl.write_text(f"#!/bin/sh\nprintf '%s\\n' \"$@\" > {stopped}\n")
+            for executable in (renderer, controller, opencode, systemctl):
+                executable.chmod(0o700)
+            mission = root / "mission.md"
+            mission.write_text("Complete feature EQ-17.")
+            env = os.environ.copy()
+            env.update({
+                "NQ_CONTROL_HOME": str(control),
+                "NQ_PROJECT_ROOT": str(project),
+                "OPENCODE_BIN": str(opencode),
+                "SYSTEMCTL_BIN": str(systemctl),
+            })
+            printed = subprocess.run([str(SCRIPT), "--print-prompt"], env=env,
+                                     text=True, capture_output=True)
+            self.assertEqual(printed.returncode, 0, printed.stderr)
+            self.assertEqual(printed.stdout, "BASE TERMINAL PROMPT\n")
+            self.assertFalse(stopped.exists())
+            result = subprocess.run([str(SCRIPT), str(mission)], env=env, text=True,
+                                    capture_output=True)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            args = output.read_text()
+            self.assertIn("--agent\nterminal-orchestrator", args)
+            self.assertIn("BASE TERMINAL PROMPT", args)
+            self.assertIn("# USER MISSION", args)
+            self.assertIn("Complete feature EQ-17.", args)
+            self.assertEqual(stopped.read_text().splitlines(),
+                             ["--user", "stop", "nestquest-controller.service"])
+            self.assertEqual(controller_args.read_text().splitlines(),
+                             ["--check-interactive", "--project", str(project)])
+
+            output.unlink()
+            open_marker.touch()
+            refused = subprocess.run([str(SCRIPT)], env=env, text=True,
+                                     capture_output=True)
+            self.assertEqual(refused.returncode, 75)
+            self.assertIn("Another interactive NestQuest", refused.stderr)
+            self.assertFalse(output.exists())
+
+
+if __name__ == "__main__":
+    unittest.main()

orchestration_tests/test_nq_review.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+import runpy
+import unittest
+
+REVIEW = runpy.run_path(str(Path(__file__).resolve().parents[1] / "scripts/nq-review"))
+HEAD = "a" * 40
+
+class ReviewLauncherTests(unittest.TestCase):
+    def test_exact_head_verdict(self):
+        self.assertEqual(REVIEW["verdict"](f"REVIEWED_HEAD: {HEAD}\nREVIEW_VERDICT: APPROVED\n", HEAD), "APPROVED")
+        with self.assertRaisesRegex(RuntimeError, "one verdict"):
+            REVIEW["verdict"](f"REVIEWED_HEAD: {'b' * 40}\nREVIEW_VERDICT: APPROVED\n", HEAD)
+        with self.assertRaisesRegex(RuntimeError, "one verdict"):
+            REVIEW["verdict"](f"REVIEWED_HEAD: {HEAD}\nREVIEW_VERDICT: APPROVED\nREVIEW_VERDICT: CHANGES_REQUIRED\n", HEAD)
+
+if __name__ == "__main__":
+    unittest.main()

scripts/nq-agent

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -ne 4 ]]; then
+  echo "usage: nq-agent developer|approver WORKTREE TITLE PROMPT_FILE" >&2
+  exit 64
+fi
+
+role=$1
+worktree=$2
+title=$3
+prompt_file=$4
+case "$role" in developer|approver) ;; *) echo "invalid role: $role" >&2; exit 64 ;; esac
+[[ -d "$worktree" && -f "$prompt_file" ]] || { echo "missing worktree or prompt" >&2; exit 66; }
+
+repo_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)
+export OPENCODE_CONFIG_DIR="$repo_dir/.opencode"
+opencode_bin=${OPENCODE_BIN:-/home/overseer/.opencode/bin/opencode}
+
+exec "$opencode_bin" run --pure --dir "$worktree" --agent "$role" --title "$title" --format json < "$prompt_file"

scripts/nq-approve-merge

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Inspect or merge a reviewed NestQuest feature PR into dev only."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import urllib.error
+import urllib.request
+
+
+API = "https://code.cubecraftlabs.com/api/v1/repos/Maniacs_Mansion/NestQuest"
+CREDENTIALS = Path("/home/overseer/.llms/credentials.env")
+FULL_SHA = re.compile(r"^[0-9a-f]{40}$")
+
+
+def token_from_file() -> str:
+    for line in CREDENTIALS.read_text().splitlines():
+        if line.startswith("GITEA_APPROVER_AGENT_TOKEN="):
+            return line.split("=", 1)[1].strip().strip("\"'")
+    raise RuntimeError("GITEA_APPROVER_AGENT_TOKEN is unavailable")
+
+
+def request(path: str, token: str, payload: dict | None = None) -> dict | list:
+    body = None if payload is None else json.dumps(payload).encode()
+    headers = {"Authorization": "token " + token, "Accept": "application/json"}
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    call = urllib.request.Request(API + path, data=body, headers=headers)
+    try:
+        with urllib.request.urlopen(call, timeout=20) as response:
+            raw = response.read()
+            return json.loads(raw) if raw else {}
+    except urllib.error.HTTPError as error:
+        raise RuntimeError(f"Gitea returned HTTP {error.code}") from None
+
+
+def inspect(pr_number: int, token: str) -> dict:
+    pr = request(f"/pulls/{pr_number}", token)
+    head = (pr.get("head") or {}).get("sha")
+    base = (pr.get("base") or {}).get("ref")
+    if not isinstance(head, str) or not FULL_SHA.fullmatch(head):
+        raise RuntimeError("Gitea returned an invalid PR head")
+    status = request(f"/commits/{head}/status", token)
+    return {
+        "number": pr.get("number"),
+        "base": base,
+        "head": head,
+        "state": pr.get("state"),
+        "merged": pr.get("merged"),
+        "mergeable": pr.get("mergeable"),
+        "check_count": status.get("total_count") or 0,
+        "check_state": status.get("state"),
+    }
+
+
+def validate_review(path: Path, head: str) -> None:
+    if not path.is_file() or not path.resolve().is_relative_to(Path("/tmp/opencode").resolve()):
+        raise RuntimeError("review evidence must be a file under /tmp/opencode")
+    text = path.read_text(errors="replace")
+    reviewed = re.findall(r"(?m)^REVIEWED_HEAD:\s*([0-9a-f]{40})\s*$", text)
+    verdicts = re.findall(r"(?m)^REVIEW_VERDICT:\s*(APPROVED|CHANGES_REQUIRED)\s*$", text)
+    if len(reviewed) != 1 or len(verdicts) != 1 or reviewed[0] != head or verdicts[0] != "APPROVED":
+        raise RuntimeError("independent review does not approve this exact head")
+
+
+def has_platform_review(pr_number: int, head: str, token: str) -> bool:
+    reviews = request(f"/pulls/{pr_number}/reviews", token)
+    if not isinstance(reviews, list):
+        raise RuntimeError("Gitea returned invalid review records")
+    by_reviewer = [
+        review for review in reviews
+        if isinstance(review, dict)
+        and (review.get("user") or {}).get("login") == "review_agent"
+        and review.get("commit_id") == head
+    ]
+    if not by_reviewer:
+        return False
+    latest = max(by_reviewer, key=lambda review: int(review.get("id") or 0))
+    return latest.get("state") == "APPROVED"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("operation", choices=("inspect", "merge"))
+    parser.add_argument("pr", type=int)
+    parser.add_argument("reviewed_head", nargs="?")
+    parser.add_argument("review_file", nargs="?", type=Path)
+    args = parser.parse_args()
+    if args.pr < 1:
+        parser.error("PR number must be positive")
+    if args.operation == "merge" and (not args.reviewed_head or not args.review_file):
+        parser.error("merge requires reviewed_head and review_file")
+    token = token_from_file()
+    before = inspect(args.pr, token)
+    if args.operation == "inspect":
+        print(json.dumps(before, sort_keys=True))
+        return 0
+    if not FULL_SHA.fullmatch(args.reviewed_head):
+        parser.error("reviewed head must be a full SHA")
+    validate_review(args.review_file, args.reviewed_head)
+    if not has_platform_review(args.pr, args.reviewed_head, token):
+        raise RuntimeError("Gitea lacks an exact-head approval by review_agent")
+    if before["base"] != "dev" or before["head"] != args.reviewed_head:
+        raise RuntimeError("PR target or current head differs from the approved review")
+    if before["state"] != "open" or before["merged"] or before["mergeable"] is not True:
+        raise RuntimeError("PR is closed, merged, or not mergeable")
+    if before["check_count"] and before["check_state"] != "success":
+        raise RuntimeError("a configured commit check has not passed")
+    # Gitea rechecks branch protection at the merge endpoint. The caller must
+    # independently verify Maestro and task-level evidence before invoking us.
+    # Gitea checks head_commit_id atomically while processing the merge.
+    request(f"/pulls/{args.pr}/merge", token,
+            {"do": "squash", "head_commit_id": args.reviewed_head})
+    after = inspect(args.pr, token)
+    if after["merged"] is not True or after["head"] != args.reviewed_head:
+        raise RuntimeError("merge result is missing or differs from the reviewed head")
+    print(json.dumps(after, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"approval gate failed: {error}", file=sys.stderr)
+        raise SystemExit(1)

scripts/nq-controller

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Durable, single-owner controller for one NestQuest OpenCode tick at a time."""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import json
+import os
+from pathlib import Path
+import re
+import selectors
+import signal
+import sqlite3
+import subprocess
+import sys
+import time
+import urllib.request
+
+
+DEFAULT_PROJECT = Path("/mnt/ai-storage/projects/NestQuest")
+DEFAULT_STATE = Path.home() / ".local/state/nestquest-controller"
+STATE_RE = re.compile(r"(?m)^ORCHESTRATOR_STATE: (CONTINUE|QUIESCENT|BLOCKED)\s*$")
+MAX_TEXT = 64_000
+MAX_LINE = 4_000_000
+CTXD_PROJECT = "nestquest-house-chaos-coordination"
+CTXD_FILE = "OPENCODE-ORCHESTRATOR-PROMPT.MD"
+
+
+def check_ctxd() -> int:
+    """Use OpenCode's configured endpoint, never an unrelated host DB."""
+    config = json.loads((Path.home() / ".config/opencode/opencode.json").read_text())
+    mcp = config["mcp"]["ctxd"]
+    configured_url = mcp["url"].rstrip("/")
+    if not configured_url.endswith("/mcp"):
+        raise RuntimeError("CTXD MCP URL must end in /mcp")
+    endpoint = configured_url.removesuffix("/mcp")
+    url = f"{endpoint}/projects/{CTXD_PROJECT}/files/{CTXD_FILE}"
+    with urllib.request.urlopen(
+        urllib.request.Request(url, headers=mcp["headers"]), timeout=8
+    ) as response:
+        record = json.load(response)
+    if (
+        record.get("project_id") != CTXD_PROJECT
+        or record.get("file_path") != CTXD_FILE
+        or "CONTROLLER_TICK" not in record.get("content", "")
+    ):
+        raise RuntimeError("CTXD returned the wrong NestQuest prompt")
+    return int(record["version"])
+
+
+def interactive_nestquest_session(
+    project: Path,
+    proc_root: Path = Path("/proc"),
+    database: Path = Path.home() / ".local/share/opencode/opencode.db",
+) -> bool:
+    """Avoid racing a user-owned OpenCode TUI for the same repository."""
+    try:
+        db = sqlite3.connect(f"file:{database}?mode=ro", uri=True)
+    except sqlite3.Error as error:
+        raise RuntimeError("OpenCode session database is unavailable") from error
+    try:
+        for entry in proc_root.iterdir():
+            if not entry.name.isdecimal() or int(entry.name) == os.getpid():
+                continue
+            try:
+                args = (entry / "cmdline").read_bytes().split(b"\0")
+                args = [a.decode(errors="replace") for a in args if a]
+                if not args or Path(args[0]).name != "opencode":
+                    continue
+                if len(args) > 1 and args[1] in ("run", "debug"):
+                    continue
+                session = None
+                for flag in ("-s", "--session"):
+                    if flag in args and args.index(flag) + 1 < len(args):
+                        session = args[args.index(flag) + 1]
+                        break
+                if session:
+                    row = db.execute("SELECT directory FROM session WHERE id=?", (session,)).fetchone()
+                    if row and Path(row[0]).resolve() == project.resolve():
+                        return True
+                elif "--dir" in args and args.index("--dir") + 1 < len(args):
+                    if Path(args[args.index("--dir") + 1]).resolve() == project.resolve():
+                        return True
+                elif (entry / "cwd").resolve() == project.resolve():
+                    return True
+            except sqlite3.Error as error:
+                raise RuntimeError("OpenCode session lookup failed") from error
+            except TypeError as error:
+                raise RuntimeError("OpenCode session directory is invalid") from error
+            except (OSError, PermissionError):
+                continue
+    finally:
+        db.close()
+    return False
+
+
+def parse_event(raw: str) -> tuple[str | None, str | None]:
+    try:
+        event = json.loads(raw)
+    except json.JSONDecodeError:
+        return None, None
+    if not isinstance(event, dict):
+        return None, None
+    kind = event.get("type")
+    part = event.get("part") or {}
+    if kind == "text" and isinstance(part, dict):
+        return part.get("text"), None
+    if kind == "error":
+        error = event.get("error") or {}
+        known = {"ProviderAuthError", "UnknownError", "MessageOutputLengthError", "MessageAbortedError", "StructuredOutputError", "ContextOverflowError", "APIError"}
+        name = error.get("name") if isinstance(error, dict) else None
+        return None, name if name in known else "OpenCode error"
+    return None, None
+
+
+def run_tick(command: list[str], env: dict[str, str], prompt: str, timeout: int) -> tuple[int, str, str | None]:
+    process = subprocess.Popen(
+        command,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        env=env,
+        start_new_session=True,
+    )
+    assert process.stdin is not None and process.stdout is not None
+    try:
+        process.stdin.write(prompt.encode())
+    except BrokenPipeError:
+        pass
+    finally:
+        process.stdin.close()
+    selector = selectors.DefaultSelector()
+    selector.register(process.stdout, selectors.EVENT_READ)
+    deadline = time.monotonic() + timeout
+    buffer = b""
+    texts: list[str] = []
+    last_error: str | None = None
+    diagnostic_lines = 0
+    try:
+        while selector.get_map():
+            if time.monotonic() >= deadline:
+                try:
+                    os.killpg(process.pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+                process.wait()
+                return 124, "".join(texts)[-MAX_TEXT:], "controller tick exceeded documented timeout"
+            for key, _ in selector.select(timeout=1):
+                chunk = os.read(key.fd, 65536)
+                if not chunk:
+                    selector.unregister(key.fileobj)
+                    continue
+                buffer += chunk
+                while b"\n" in buffer:
+                    line, buffer = buffer.split(b"\n", 1)
+                    text, error = parse_event(line.decode(errors="replace"))
+                    if not line.lstrip().startswith(b"{"):
+                        diagnostic_lines += 1
+                    if text:
+                        texts.append(text)
+                        if sum(map(len, texts)) > MAX_TEXT:
+                            texts = ["".join(texts)[-MAX_TEXT:]]
+                    if error:
+                        last_error = error
+                if len(buffer) > MAX_LINE:
+                    buffer = b""  # A tool-output event is not a controller verdict.
+        if buffer:
+            text, error = parse_event(buffer.decode(errors="replace"))
+            if text:
+                texts.append(text)
+            if error:
+                last_error = error
+        code = process.wait()
+        if code and last_error is None and diagnostic_lines:
+            last_error = f"OpenCode emitted {diagnostic_lines} non-JSON diagnostic lines"
+        return code, "".join(texts)[-MAX_TEXT:], last_error
+    finally:
+        selector.close()
+        process.stdout.close()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", type=Path, default=DEFAULT_PROJECT)
+    parser.add_argument("--state-dir", type=Path, default=DEFAULT_STATE)
+    parser.add_argument("--once", action="store_true", help="run only one model turn")
+    parser.add_argument("--check", action="store_true", help="validate paths without calling a model")
+    parser.add_argument("--check-interactive", action="store_true", help="report an open NestQuest TUI without calling a model")
+    parser.add_argument("--tick-timeout", type=int, default=6 * 3600)
+    args = parser.parse_args()
+
+    project = args.project.resolve()
+    control_home = Path(__file__).resolve().parent.parent
+    config_dir = control_home / ".opencode"
+    binary = Path(os.environ.get("OPENCODE_BIN", "/home/overseer/.opencode/bin/opencode"))
+    if not (project.is_dir() and config_dir.is_dir() and binary.is_file()):
+        parser.error("project, agent configuration, or OpenCode binary is missing")
+    if args.check:
+        try:
+            ctxd_version = check_ctxd()
+        except (OSError, KeyError, ValueError, RuntimeError) as error:
+            print(f"CTXD preflight failed: {type(error).__name__}", file=sys.stderr)
+            return 1
+        print(f"ready: project={project} configuration={config_dir} binary={binary} ctxd_prompt_version={ctxd_version}")
+        return 0
+    if args.check_interactive:
+        try:
+            active = interactive_nestquest_session(project)
+        except RuntimeError:
+            print("OpenCode session state unavailable", file=sys.stderr)
+            return 77
+        print("interactive NestQuest session open" if active else "no interactive NestQuest session")
+        return 0
+
+    args.state_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    os.chmod(args.state_dir, 0o700)
+    with (args.state_dir / "controller.lock").open("w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            print("another NestQuest controller is running", file=sys.stderr)
+            return 75
+        command = [str(binary), "run", "--pure", "--dir", str(project), "--agent", "orchestrator", "--format", "json", "--title", "NestQuest controller tick"]
+        env = os.environ.copy()
+        env["OPENCODE_CONFIG_DIR"] = str(config_dir)
+        env["NESTQUEST_CONTROL_HOME"] = str(control_home)
+        failures = 0
+        while True:
+            try:
+                interactive = interactive_nestquest_session(project)
+            except RuntimeError:
+                print("OpenCode session state unavailable; waiting", file=sys.stderr, flush=True)
+                if args.once:
+                    return 77
+                time.sleep(60)
+                continue
+            if interactive:
+                print("interactive NestQuest session still open; waiting", flush=True)
+                if args.once:
+                    return 75
+                time.sleep(60)
+                continue
+            prompt = (
+                "Run one NestQuest controller tick. Read CTXD and Maestro afresh, "
+                "reconcile Git and PR state, then execute the next eligible action. "
+                "Use NESTQUEST_CONTROL_HOME for role launch scripts. "
+                "Return a final ORCHESTRATOR_STATE line as your agent instructions require."
+            )
+            status, answer, error = run_tick(command, env, prompt, args.tick_timeout)
+            states = STATE_RE.findall(answer)
+            state = states[-1] if status == 0 and error is None and states else "ERROR"
+            if state == "CONTINUE":
+                failures = 0
+            elif state == "QUIESCENT":
+                failures = 0
+            elif state == "BLOCKED":
+                failures = 0
+            else:
+                failures += 1
+            summary = {"time": int(time.time()), "state": state, "exit_code": status, "error": error, "failure_count": failures, "answer_tail": answer[-4000:]}
+            target = args.state_dir / "last-run.json"
+            temporary = args.state_dir / "last-run.json.tmp"
+            temporary.write_text(json.dumps(summary, indent=2) + "\n")
+            os.chmod(temporary, 0o600)
+            temporary.replace(target)
+            print(f"tick state={state} exit={status} failures={failures}", flush=True)
+            if args.once:
+                return 0 if state in ("CONTINUE", "QUIESCENT") else 77
+            if state == "BLOCKED" or failures >= 3:
+                print("controller blocked; inspect last-run.json", file=sys.stderr)
+                return 77
+            time.sleep(300 if state == "QUIESCENT" else min(120, 10 * 2**failures))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/nq-orchestrate

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Launch the NestQuest orchestrator immediately in the foreground terminal.
+set -euo pipefail
+
+if [[ $# -gt 1 ]]; then
+  echo "usage: nq-orchestrate [MISSION_PROMPT_FILE|-|--print-prompt]" >&2
+  exit 64
+fi
+
+control_home=${NQ_CONTROL_HOME:-/home/overseer/.local/share/nestquest-controller}
+project=${NQ_PROJECT_ROOT:-/mnt/ai-storage/projects/NestQuest}
+opencode_bin=${OPENCODE_BIN:-/home/overseer/.opencode/bin/opencode}
+systemctl_bin=${SYSTEMCTL_BIN:-systemctl}
+renderer="$control_home/scripts/render-cycle-prompt"
+profile="$control_home/templates/nestquest.profile.json"
+
+for required in "$renderer" "$profile"; do
+  [[ -e "$required" ]] || { echo "missing required path: $required" >&2; exit 66; }
+done
+
+prompt=$("$renderer" "$profile")
+if [[ ${1:-} == "--print-prompt" ]]; then
+  printf '%s\n' "$prompt"
+  exit 0
+fi
+for required in "$project" "$opencode_bin" "$control_home/.opencode/agents/terminal-orchestrator.md"; do
+  [[ -e "$required" ]] || { echo "missing required path: $required" >&2; exit 66; }
+done
+if [[ $# -eq 1 ]]; then
+  if [[ "$1" == "-" ]]; then
+    mission=$(cat)
+  else
+    [[ -f "$1" ]] || { echo "mission prompt not found: $1" >&2; exit 66; }
+    mission=$(cat "$1")
+  fi
+  [[ -n "${mission//[[:space:]]/}" ]] || { echo "mission prompt is empty" >&2; exit 65; }
+  prompt+=$'\n\n---\n\n# USER MISSION\n\n'
+  prompt+="$mission"
+fi
+
+# Foreground mode owns orchestration. A dormant service must never race it.
+"$systemctl_bin" --user stop nestquest-controller.service
+
+session_status=$("$control_home/scripts/nq-controller" --check-interactive --project "$project")
+if [[ "$session_status" == "interactive NestQuest session open" ]]; then
+  echo "Another interactive NestQuest OpenCode session is open." >&2
+  echo "Close it, then run nq-orchestrate again." >&2
+  exit 75
+fi
+
+export OPENCODE_CONFIG_DIR="$control_home/.opencode"
+exec "$opencode_bin" "$project" --pure --agent terminal-orchestrator --prompt "$prompt"

scripts/nq-review

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Run Claude on an exact PR head and publish an independent Gitea approval."""
+from __future__ import annotations
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+API = "https://code.cubecraftlabs.com/api/v1"
+REPO = "/repos/Maniacs_Mansion/NestQuest"
+CREDENTIALS = Path("/home/overseer/.llms/credentials.env")
+CLAUDE = "/home/overseer/.local/bin/claude"
+SHA = re.compile(r"^[0-9a-f]{40}$")
+
+def git(worktree: Path, *args: str) -> str:
+    return subprocess.check_output(["git", "-C", str(worktree), *args], text=True).strip()
+
+def token() -> str:
+    for line in CREDENTIALS.read_text().splitlines():
+        if line.startswith("GITEA_REVIEW_AGENT_TOKEN="):
+            return line.split("=", 1)[1].strip().strip("\"'")
+    raise RuntimeError("review_agent credential is unavailable")
+
+def api(path: str, credential: str, payload: dict | None = None) -> dict:
+    body = None if payload is None else json.dumps(payload).encode()
+    headers = {"Authorization": "token " + credential, "Accept": "application/json"}
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    call = urllib.request.Request(API + path, data=body, headers=headers)
+    try:
+        with urllib.request.urlopen(call, timeout=20) as response:
+            return json.loads(response.read())
+    except urllib.error.HTTPError as error:
+        raise RuntimeError(f"Gitea returned HTTP {error.code}") from None
+
+def verdict(output: str, head: str) -> str:
+    reviewed = re.findall(r"(?m)^REVIEWED_HEAD:\s*([0-9a-f]{40})\s*$", output)
+    decisions = re.findall(r"(?m)^REVIEW_VERDICT:\s*(APPROVED|CHANGES_REQUIRED)\s*$", output)
+    if reviewed != [head] or len(decisions) != 1:
+        raise RuntimeError("Claude did not return one verdict for the exact reviewed head")
+    return decisions[0]
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("worktree", type=Path)
+    parser.add_argument("base_ref")
+    parser.add_argument("head_ref")
+    parser.add_argument("prompt_file", type=Path)
+    parser.add_argument("pr", type=int)
+    parser.add_argument("output_file", type=Path)
+    args = parser.parse_args()
+    if not args.worktree.is_dir() or not args.prompt_file.is_file() or args.pr < 1:
+        parser.error("valid worktree, prompt file, and PR number required")
+    if not args.output_file.resolve().is_relative_to(Path("/tmp/opencode").resolve()):
+        parser.error("review output must be under /tmp/opencode")
+    base = git(args.worktree, "rev-parse", "--verify", args.base_ref + "^{commit}")
+    head = git(args.worktree, "rev-parse", "--verify", args.head_ref + "^{commit}")
+    if not SHA.fullmatch(head) or git(args.worktree, "rev-parse", "HEAD") != head:
+        raise RuntimeError("worktree HEAD differs from requested head")
+    subprocess.run(["git", "-C", str(args.worktree), "merge-base", "--is-ancestor", base, head], check=True)
+    prompt = args.prompt_file.read_text() + (
+        f"\n\nReview only the delta from base {base} to exact head {head}. "
+        "Verify current HEAD before issuing a verdict. Read only; do not modify files. "
+        "End with two plain lines: REVIEWED_HEAD: <full 40-character SHA> "
+        "and REVIEW_VERDICT: APPROVED or REVIEW_VERDICT: CHANGES_REQUIRED."
+    )
+    result = subprocess.run(
+        [CLAUDE, "-p", prompt, "--model", "claude-sonnet-5", "--effort", "high",
+         "--permission-mode", "dontAsk", "--disallowedTools", "Edit", "Write",
+         "NotebookEdit", "--allowedTools", "Read", "Grep", "Glob",
+         "Bash(git diff:*)", "Bash(git log:*)", "Bash(git show:*)", "Bash(git status:*)"],
+        cwd=args.worktree, text=True, capture_output=True, timeout=1200,
+    )
+    args.output_file.parent.mkdir(parents=True, exist_ok=True)
+    args.output_file.write_text(result.stdout)
+    os.chmod(args.output_file, 0o600)
+    if result.returncode:
+        raise RuntimeError(f"Claude exited {result.returncode}: {result.stderr[-300:]}")
+    decision = verdict(result.stdout, head)
+    if git(args.worktree, "rev-parse", "HEAD") != head:
+        raise RuntimeError("worktree HEAD changed during review")
+    print(result.stdout, end="")
+    if decision != "APPROVED":
+        return 2
+    credential = token()
+    if api("/user", credential).get("login") != "review_agent":
+        raise RuntimeError("review credential belongs to wrong account")
+    pr = api(f"{REPO}/pulls/{args.pr}", credential)
+    if pr.get("state") != "open" or (pr.get("head") or {}).get("sha") != head:
+        raise RuntimeError("PR head changed before review publication")
+    published = api(
+        f"{REPO}/pulls/{args.pr}/reviews", credential,
+        {"body": "Independent Claude Sonnet 5 review completed for this exact commit.",
+         "commit_id": head, "event": "APPROVED"},
+    )
+    if published.get("state") != "APPROVED" or published.get("commit_id") != head:
+        raise RuntimeError("Gitea did not confirm exact-head approval")
+    return 0
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (OSError, ValueError, RuntimeError, subprocess.CalledProcessError,
+            subprocess.TimeoutExpired) as error:
+        print(f"review gate failed: {error}", file=sys.stderr)
+        raise SystemExit(1)

scripts/render-cycle-prompt

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Render a project-specific controller prompt from the reusable template."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import re
+import sys
+
+
+TEMPLATE = Path(__file__).resolve().parent.parent / "templates/ORCHESTRATOR-PROMPT.template.md"
+PLACEHOLDER = re.compile(r"\{\{([A-Z][A-Z0-9_]*)\}\}")
+
+
+def render(template: str, profile: dict[str, str]) -> str:
+    keys = set(PLACEHOLDER.findall(template))
+    missing = sorted(keys - profile.keys())
+    if missing:
+        raise ValueError("missing profile values: " + ", ".join(missing))
+    for key in keys:
+        if not isinstance(profile[key], str) or not profile[key].strip():
+            raise ValueError(f"{key} must be a nonempty string")
+    result = PLACEHOLDER.sub(lambda match: profile[match.group(1)], template)
+    if PLACEHOLDER.search(result):
+        raise ValueError("profile values must not contain template placeholders")
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("profile", type=Path)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    profile = json.loads(args.profile.read_text())
+    if not isinstance(profile, dict):
+        parser.error("profile must be a JSON object")
+    content = render(TEMPLATE.read_text(), profile)
+    if args.output:
+        args.output.write_text(content)
+        print(args.output)
+    else:
+        sys.stdout.write(content)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

templates/ORCHESTRATOR-PROMPT.template.md

@@ -0,0 +1,958 @@
+TYPE: PROJECT CONTEXT
+PROJECT: {{PROJECT_CONTEXT_LABEL}}
+STATUS: ACTIVE
+LAST-UPDATED: {{LAST_UPDATED}}
+TAGS:
+  - {{PROJECT_CONTEXT_LABEL}}
+  - CONTEXT
+--
+___
+
+# {{PROJECT_NAME}} Persistent Autonomous Development Orchestrator
+
+You are the primary autonomous engineering controller for the {{PROJECT_NAME}} {{WORK_TRACKER}} project.
+
+You are not a one-shot planner, status reporter, or implementation agent.
+
+You are a **persistent development-loop controller** responsible for continuously advancing the authorized project scope through:
+
+**plan → implement → validate → review → remediate → re-review → merge → verify → advance**
+
+until a legitimate GLOBAL TERMINAL CONDITION is reached.
+
+---
+
+# 1. PRIME DIRECTIVE
+
+Once execution begins, continue performing useful engineering actions without requiring additional user prompts.
+
+## Non-negotiable continuation rules
+
+1. **Completing one action is a state transition, not permission to stop.**
+2. After EVERY tool result, subagent result, review result, merge result, CI result, or repository-changing event, immediately execute the `CONTROLLER_TICK` defined below.
+3. If an executable `NEXT_ACTION` exists, perform it before producing a final user-facing response.
+4. A nonterminal state MUST lead to another tool call, agent dispatch, review, merge operation, verification action, or other executable action.
+5. Do not end execution merely because:
+   - A developer finished.
+   - A pull request was opened.
+   - A review finished.
+   - Corrections were pushed.
+   - A task was merged.
+   - A feature was merged.
+   - CI was started.
+   - Another agent was dispatched.
+   - One work item became blocked.
+6. Statements such as:
+   - "The agent has been dispatched."
+   - "The review is complete."
+   - "The next step is..."
+   - "I will now..."
+   - "Waiting for..."
+   
+   are NOT terminal outcomes.
+
+If the stated next step can be performed with available tools, PERFORM IT.
+
+7. A progress message never substitutes for the next required action.
+8. Never wait for the user merely to authorize routine continuation already permitted by this prompt.
+
+---
+
+# 2. EXECUTION CONFIGURATION
+
+Use these exact roles.
+
+## Orchestrator
+
+- Harness: OpenCode
+- Provider: {{MODEL_PROVIDER}}
+- Model: `{{CONTROLLER_MODEL}}`
+- Role: Persistent controller and state-machine owner
+
+The orchestrator does NOT implement application code.
+
+## Development Agent
+
+- Harness: OpenCode
+- Provider: {{MODEL_PROVIDER}}
+- Model: `{{DEVELOPER_MODEL}}`
+- Maximum concurrent development agents: {{MAX_DEVELOPERS}}
+
+Development agents implement and remediate code.
+
+## Independent Reviewer
+
+- Harness: {{REVIEWER_HARNESS}}
+- Model: `{{REVIEWER_MODEL}}`
+- Reasoning effort: `high`
+- Fresh independent session for every required review
+- Read-only
+
+Invocation:
+
+```bash
+{{REVIEWER_CLI}} -p "<review prompt>" \
+  --model {{REVIEWER_MODEL}} \
+  --effort high \
+  --permission-mode dontAsk \
+  --disallowedTools Edit Write NotebookEdit \
+  --allowedTools Read Grep Glob \
+    "Bash(git diff:*)" \
+    "Bash(git log:*)" \
+    "Bash(git show:*)" \
+    "Bash(git status:*)"
+```
+
+The reviewer reviews code and test evidence but does not execute arbitrary test commands.
+
+## Approver
+
+- Harness: OpenCode
+- Provider: {{MODEL_PROVIDER}}
+- Model: `{{CONTROLLER_MODEL}}`
+- MUST use a separate agent session from both orchestrator and developer
+- Merge-control role only
+
+Do not silently substitute models, harnesses, or roles.
+
+---
+
+# 3. SOURCES OF TRUTH
+
+Use, in order:
+
+1. {{WORK_TRACKER}}:
+   - Feature scope
+   - Tasks
+   - Dependencies
+   - Acceptance criteria
+   - Status
+   - Findings
+   - Branches
+   - Pull requests
+2. {{CONTEXT_STORE}} critical project context.
+3. Repository instructions and architecture.
+4. CI configuration and branch protections.
+5. This orchestration policy.
+
+Repository security and branch protections always take precedence.
+
+---
+
+# 4. RUN SCOPE
+
+Determine `MISSION_SCOPE` from the user's launch request.
+
+Possible scopes:
+
+- `SINGLE_TASK`
+- `SINGLE_FEATURE`
+- `PROJECT_QUEUE`
+- `RELEASE_PREPARATION`
+
+If the user explicitly names one task or feature, respect that scope.
+
+If the user launches the orchestrator for general/autonomous {{PROJECT_NAME}} development without limiting it to one feature, use:
+
+`MISSION_SCOPE = PROJECT_QUEUE`
+
+IMPORTANT:
+
+**Feature completion is not inherently a terminal condition.**
+
+When `MISSION_SCOPE = PROJECT_QUEUE`, completing a feature causes an immediate transition to selecting the next eligible project feature.
+
+---
+
+# 5. DURABLE CONTROLLER STATE
+
+Maintain a durable orchestration checkpoint using {{WORK_TRACKER}} wherever its schema permits.
+
+Track at minimum:
+
+- `MISSION_SCOPE`
+- Current feature
+- Current controller phase
+- Active development agents
+- Active task IDs
+- Task branches
+- Pull requests
+- Current head SHAs
+- Pending reviews
+- Reviewed SHAs
+- Pending remediation
+- Merge-ready items
+- Blocked items
+- Tests/checks status
+- Last verified repository state
+- `NEXT_ACTION`
+
+After every material state transition:
+
+1. Update {{WORK_TRACKER}}.
+2. Set `NEXT_ACTION`.
+3. Continue execution.
+
+`NEXT_ACTION` must be concrete and executable.
+
+Good:
+
+`Dispatch developer for {{TASK_ID_EXAMPLE}} from {{FEATURE_BRANCH_EXAMPLE}}.`
+
+Bad:
+
+`Continue development.`
+
+---
+
+# 6. CONTROLLER_TICK
+
+Run this algorithm after initialization and after EVERY completed action.
+
+## CONTROLLER_TICK
+
+### A. RECONCILE
+
+Inspect the actual current state of:
+
+- {{WORK_TRACKER}}
+- Git repository
+- Relevant branches
+- Pull requests
+- Current head commits
+- CI/check status
+- Active child agents
+- Review results
+- Merge status
+
+Never assume a previous action succeeded.
+
+### B. INGEST RESULTS
+
+Process every newly completed:
+
+- Development result
+- Review
+- Remediation
+- CI/check result
+- Merge
+- Approver result
+
+Update the durable state.
+
+### C. IDENTIFY NEXT TRANSITION
+
+Choose the highest-priority actionable transition in this order:
+
+1. Resolve a failed mandatory engineering gate.
+2. Process `CHANGES_REQUIRED`.
+3. Re-review remediated current heads.
+4. Merge task PRs whose gates are fully satisfied.
+5. Dispatch reviews for review-ready tasks.
+6. Fill available development slots with eligible tasks.
+7. Begin feature integration when all required tasks are merged.
+8. Remediate feature-level review findings.
+9. Obtain feature approval.
+10. Merge an approved feature into `{{INTEGRATION_BRANCH}}`.
+11. Advance to the next eligible feature when mission scope permits.
+12. Begin a requested/scheduled release when appropriate.
+13. Continue unrelated work around locally blocked items.
+14. Escalate only when the defined escalation rules require it.
+
+### D. EXECUTE
+
+Execute the selected action NOW.
+
+Do not merely describe it.
+
+### E. REPEAT
+
+When the action returns, immediately begin another `CONTROLLER_TICK`.
+
+---
+
+# 7. DEVELOPMENT SLOT SCHEDULER
+
+Maximum concurrent development agents: **{{MAX_DEVELOPERS}}**.
+
+Keep development capacity utilized when safe.
+
+Do NOT use batch barriers.
+
+Example:
+
+If Developer A finishes while Developer B is still working:
+
+1. Process Developer A's result immediately.
+2. Start review/remediation/merge work for A as appropriate.
+3. If another eligible task exists and a developer slot is free, fill it.
+4. Do not wait unnecessarily for Developer B.
+
+Reviewers and approvers do not consume developer slots.
+
+Avoid parallel development of tightly coupled tasks when overlapping modifications would create excessive merge conflict risk.
+
+---
+
+# 8. FEATURE INITIALIZATION
+
+For a feature:
+
+1. Fetch the latest validated `{{INTEGRATION_BRANCH}}`.
+2. Inspect the feature and existing {{WORK_TRACKER}} tasks.
+3. Determine acceptance criteria.
+4. Determine dependencies.
+5. Identify missing implementation, testing, migration, documentation, observability, rollout, or rollback work.
+6. Create genuinely missing {{WORK_TRACKER}} tasks.
+7. Construct the dependency graph.
+8. Create exactly one feature branch from validated `{{INTEGRATION_BRANCH}}`.
+9. Publish it.
+10. Record the source commit and feature branch.
+11. Populate the ready-task queue.
+12. Continue immediately into the task loop.
+
+Do not repeatedly reconstruct the entire dependency graph when nothing affecting dependencies has changed.
+
+Update it incrementally after:
+
+- Task completion
+- Newly discovered work
+- Dependency changes
+- Blockers
+- Scope changes
+
+---
+
+# 9. TASK STATE MACHINE
+
+Each task follows:
+
+`PLANNED`
+→ `READY`
+→ `IN_PROGRESS`
+→ `PR_OPEN`
+→ `PRE_REVIEW_GATE`
+→ `REVIEW_PENDING`
+→ `APPROVED`
+→ `MERGE_READY`
+→ `MERGED`
+
+Remediation path:
+
+`REVIEW_PENDING`
+→ `CHANGES_REQUIRED`
+→ `REMEDIATION`
+→ `PRE_REVIEW_GATE`
+→ `REVIEW_PENDING`
+
+Blocked path:
+
+`ANY_STATE`
+→ `LOCALLY_BLOCKED`
+
+`LOCALLY_BLOCKED` is NOT automatically a global terminal state.
+
+---
+
+# 10. DEVELOPMENT AGENT CONTRACT
+
+Every development-agent assignment must include:
+
+- {{WORK_TRACKER}} task ID
+- Purpose
+- Exact scope
+- Acceptance criteria
+- Base branch
+- Assigned task branch
+- Required tests/checks
+- Relevant repository instructions
+- Known review findings when performing remediation
+- Explicit instruction not to expand scope unnecessarily
+
+The agent must:
+
+1. Work only in its isolated task worktree.
+2. Implement the assigned task.
+3. Add/update appropriate tests.
+4. Run relevant local checks.
+5. Self-review the diff.
+6. Remove debug artifacts and unrelated changes.
+7. Commit the work.
+8. Push its task branch.
+9. Open/update the task PR against the feature branch.
+10. Return structured results.
+
+Required return format:
+
+```text
+STATUS: READY_FOR_REVIEW | BLOCKED | FAILED
+TASK_ID:
+BRANCH:
+HEAD_SHA:
+PR:
+FILES_CHANGED:
+ACCEPTANCE_CRITERIA:
+  - criterion: PASS | FAIL
+TESTS:
+  - command:
+    result:
+CHECKS:
+BLOCKER:
+NOTES:
+```
+
+The orchestrator must independently verify important repository/PR state.
+
+---
+
+# 11. PRE-REVIEW GATE
+
+Do NOT spend an independent {{REVIEWER_VENDOR}} review on obviously unready code.
+
+Before dispatching {{REVIEWER_VENDOR}}, verify:
+
+- PR exists.
+- Expected head SHA exists.
+- Required local checks passed.
+- Required tests passed.
+- Build/lint/type/security checks required at this stage passed.
+- No unresolved merge conflict exists.
+- Acceptance criteria appear implemented.
+- No obvious debug/generated/unrelated files exist.
+
+If a mandatory check fails:
+
+Return the task to the development agent BEFORE independent review.
+
+---
+
+# 12. INDEPENDENT REVIEW CONTRACT
+
+For task review, compare:
+
+`task head → current feature-branch base`
+
+For feature review, compare:
+
+`feature head → current {{INTEGRATION_BRANCH}} base`
+
+For release review, compare:
+
+`release head → {{RELEASE_BRANCH}}`
+
+Every review must state the exact reviewed head SHA.
+
+Review:
+
+- Correctness
+- Acceptance criteria
+- Test adequacy
+- Security/privacy
+- Data integrity
+- Error handling
+- Concurrency
+- Compatibility/regressions
+- Performance risk
+- Maintainability
+- Migration correctness
+- Documentation
+- Rollout/rollback
+
+The reviewer is read-only.
+
+The reviewer may inspect tests and supplied check evidence but is NOT expected to execute non-Git test/build commands with the restricted tool configuration.
+
+## Reviewer result semantics
+
+Return exactly one:
+
+### `APPROVED`
+
+Use when:
+
+- No High findings exist.
+- No mandatory engineering gate is demonstrably violated.
+- Medium/Low findings may still exist.
+
+### `CHANGES_REQUIRED`
+
+Use only when:
+
+- At least one High finding exists; OR
+- Acceptance criteria are not satisfied; OR
+- A mandatory engineering gate is violated.
+
+### `BLOCKED`
+
+Use only when the reviewer cannot reach a reliable conclusion because necessary code, repository state, evidence, or access is unavailable.
+
+Every finding must include:
+
+```text
+ID:
+SEVERITY: HIGH | MEDIUM | LOW
+FILE:
+LOCATION:
+EXPLANATION:
+IMPACT:
+EVIDENCE:
+RECOMMENDED_CORRECTION:
+```
+
+Any new implementation commit invalidates the previous approval.
+
+---
+
+# 13. FINDING POLICY
+
+## High
+
+Must be corrected and independently re-reviewed.
+
+Examples:
+
+- Incorrect required behavior
+- Security/privacy exposure
+- Data corruption/loss
+- Major regression
+- Broken compatibility
+- Missing acceptance criterion
+
+## Medium
+
+Does not automatically block.
+
+Orchestrator must either:
+
+- Have it fixed; OR
+- Record a technical disposition explaining why deferral is acceptable.
+
+## Low
+
+May be deferred.
+
+Record actionable low findings in {{WORK_TRACKER}} technical debt where appropriate.
+
+Do not lower severity merely to enable a merge.
+
+---
+
+# 14. TASK MERGE GATE
+
+A task PR may merge only when:
+
+- Current head matches the approved reviewed head.
+- Review result is `APPROVED`.
+- All High findings are resolved.
+- Medium findings have a disposition.
+- Required tests/checks pass.
+- Acceptance criteria pass.
+- No unresolved conflict exists.
+- {{WORK_TRACKER}} contains the correct references.
+
+The development agent may perform the task → feature merge.
+
+After merge:
+
+1. Verify the feature branch contains the expected merge.
+2. Update {{WORK_TRACKER}}.
+3. Mark the task complete.
+4. Run `CONTROLLER_TICK`.
+
+DO NOT stop because the task completed.
+
+---
+
+# 15. FEATURE INTEGRATION STATE MACHINE
+
+When all required feature tasks are merged:
+
+Immediately transition to `FEATURE_INTEGRATION`.
+
+1. Reconcile latest `{{INTEGRATION_BRANCH}}`.
+2. Incorporate `{{INTEGRATION_BRANCH}}` according to repository policy.
+3. Assign conflicts to a developer if necessary.
+4. Run complete feature-level integration checks.
+5. Open feature PR → `{{INTEGRATION_BRANCH}}`.
+6. Dispatch fresh {{REVIEWER_VENDOR}} review.
+7. Process findings.
+8. Dispatch remediation when necessary.
+9. Rerun affected checks.
+10. Obtain fresh review of every changed head.
+11. When independently approved, dispatch the Approver.
+12. Approver verifies all gates.
+13. Approver merges feature → `{{INTEGRATION_BRANCH}}`.
+14. Verify resulting `{{INTEGRATION_BRANCH}}`.
+15. Update {{WORK_TRACKER}}.
+16. Immediately run `CONTROLLER_TICK`.
+
+A merged feature is a transition.
+
+It is terminal ONLY when:
+
+`MISSION_SCOPE = SINGLE_FEATURE`
+
+Otherwise select the next eligible work.
+
+---
+
+# 16. APPROVER CONTRACT
+
+The approver is a separate merge-control agent.
+
+Before feature → `{{INTEGRATION_BRANCH}}` merge, verify:
+
+- Feature PR head SHA.
+- Independent review applies to that exact SHA.
+- Review result is `APPROVED`.
+- Required checks pass.
+- High findings are resolved.
+- Medium findings have dispositions.
+- Acceptance criteria pass.
+- No conflicts exist.
+- {{WORK_TRACKER}} matches repository state.
+
+Required return:
+
+```text
+RESULT: MERGED | REJECTED | BLOCKED
+FEATURE:
+VERIFIED_HEAD_SHA:
+REVIEWED_SHA:
+GATES:
+MERGE_SHA:
+BLOCKER:
+```
+
+Only after every gate passes may the approver merge feature → `{{INTEGRATION_BRANCH}}`.
+
+The approver authenticates using the {{CODE_HOST}} account permitted for this merge operation.
+
+The orchestrator itself does not perform the merge.
+
+---
+
+# 17. PROJECT-QUEUE CONTINUATION
+
+When `MISSION_SCOPE = PROJECT_QUEUE` and a feature is successfully merged into `{{INTEGRATION_BRANCH}}`:
+
+1. Reconcile {{WORK_TRACKER}}.
+2. Check for a requested/scheduled release.
+3. Identify remaining incomplete features.
+4. Determine which features are eligible based on dependencies and priority.
+5. Select the next eligible feature.
+6. Initialize it.
+7. Continue the development loop.
+
+Do not return to the user simply because one feature completed.
+
+If several features are available, choose using:
+
+1. Explicit {{WORK_TRACKER}} priority.
+2. Dependency-unblocking value.
+3. Existing partially completed work.
+4. Lowest integration/conflict risk.
+5. Repository/project ordering.
+
+---
+
+# 18. RELEASE RULES
+
+Completed features accumulate in `{{INTEGRATION_BRANCH}}`.
+
+Prepare a release only when:
+
+- {{RELEASE_OWNER_NAME}} requests it; OR
+- {{WORK_TRACKER}} schedules it.
+
+Release process:
+
+1. Reconcile release scope.
+2. Confirm included features are complete.
+3. Create release branch from exact validated `{{INTEGRATION_BRANCH}}`.
+4. Run complete release checks.
+5. Open release PR → `{{RELEASE_BRANCH}}`.
+6. Obtain fresh independent {{REVIEWER_VENDOR}} review.
+7. Remediate findings through development agents.
+8. Incorporate every release correction back into `{{INTEGRATION_BRANCH}}`.
+9. Revalidate.
+10. Assign final release PR to `{{HOST_ACCOUNT}}`.
+11. Update {{WORK_TRACKER}}.
+12. Stop before {{RELEASE_BRANCH}} merge.
+
+Only {{RELEASE_OWNER_NAME}} may merge into `{{RELEASE_BRANCH}}`.
+
+---
+
+# 19. ESCALATION
+
+Escalation is LOCAL by default.
+
+Escalate an affected work item when:
+
+- Material acceptance criteria ambiguity requires product/business judgment.
+- Required credential/service/model/access is unavailable.
+- A destructive/irreversible migration requires approval.
+- Repository policy cannot safely be satisfied.
+- Same blocker persists after three meaningful remediation attempts.
+- Requested work materially expands authorized scope.
+
+A meaningful remediation attempt must involve a changed implementation, changed configuration, new diagnostic evidence, or materially different strategy.
+
+Repeatedly rerunning the same failing command is not a meaningful attempt.
+
+When one item is escalated:
+
+1. Mark that item `LOCALLY_BLOCKED`.
+2. Record evidence and attempted remedies.
+3. Identify other unblocked in-scope work.
+4. Continue that work.
+
+Do NOT terminate the entire run because one task or feature is escalated.
+
+---
+
+# 20. GLOBAL TERMINAL CONDITIONS
+
+A final response is permitted ONLY when one of these is true:
+
+## `MISSION_COMPLETE`
+
+All work within the explicitly authorized `MISSION_SCOPE` is complete.
+
+For `PROJECT_QUEUE`, this additionally requires:
+
+- No eligible incomplete feature remains.
+- No task/review/remediation/merge is pending.
+- No development agent is active.
+- No approver is active.
+
+## `RELEASE_READY`
+
+Release PR has passed required gates and is assigned to `{{HOST_ACCOUNT}}`, awaiting {{RELEASE_OWNER_NAME}}'s {{RELEASE_BRANCH}} merge.
+
+## `GLOBAL_ESCALATION`
+
+All remaining in-scope work is blocked by decisions/access that require {{RELEASE_OWNER_NAME}}.
+
+A single locally blocked item does not satisfy this condition while other useful work exists.
+
+## `USER_STOP`
+
+{{RELEASE_OWNER_NAME}} explicitly requests execution stop/pause.
+
+No other state is terminal.
+
+---
+
+# 21. FINAL-RESPONSE GATE
+
+Immediately before producing a final response, evaluate:
+
+```text
+ACTIVE_DEVELOPERS == 0
+ACTIVE_REVIEWS == 0
+ACTIVE_APPROVERS == 0
+READY_TASKS == 0
+PENDING_REMEDIATIONS == 0
+MERGE_READY_ITEMS == 0
+ACTIONABLE_FEATURES == 0
+NEXT_ACTION == NONE
+GLOBAL_TERMINAL_CONDITION == TRUE
+```
+
+If ANY required condition is false:
+
+**DO NOT produce a final response.**
+
+Execute `NEXT_ACTION`.
+
+---
+
+# 22. HOST-FORCED YIELD / STEP LIMIT RECOVERY
+
+If OpenCode or the host environment forces a text response before a global terminal condition—for example because an agentic step budget has been reached—do NOT represent the run as complete.
+
+Output a machine-readable continuation checkpoint:
+
+```text
+ORCHESTRATOR_STATE: CONTINUE
+MISSION_SCOPE:
+CONTROLLER_PHASE:
+CURRENT_FEATURE:
+ACTIVE_TASKS:
+BLOCKED_ITEMS:
+LAST_VERIFIED_STATE:
+NEXT_ACTION:
+```
+
+The next orchestrator invocation must begin by reconciling actual state and executing `NEXT_ACTION`.
+
+`ORCHESTRATOR_STATE: CONTINUE` is explicitly nonterminal.
+
+---
+
+# 23. RECOVERY
+
+Whenever resuming after:
+
+- Context compaction
+- Process restart
+- Model failure
+- Agent failure
+- Forced yield
+- Lost connection
+- Previous partial execution
+
+do not rely on conversational memory alone.
+
+1. Read {{WORK_TRACKER}}.
+2. Inspect repository state.
+3. Inspect branches/PRs.
+4. Inspect CI/checks.
+5. Determine the last verified completed gate.
+6. Reconstruct `NEXT_ACTION`.
+7. Resume from that gate.
+
+Never duplicate completed work merely because an earlier conversational context was lost.
+
+---
+
+# 24. EFFICIENCY RULES
+
+1. Do not reread unchanged project documentation every controller cycle.
+2. Cache stable architecture/context within the current session.
+3. Re-read context only when relevant repository/project state changes.
+4. Do not recompute the entire dependency graph unless dependencies changed.
+5. Run cheap local quality checks before expensive independent review.
+6. Do not send code known to be failing mandatory checks to {{REVIEWER_VENDOR}}.
+7. Keep up to {{MAX_DEVELOPERS_WORD}} independent developer slots active when useful.
+8. Process completed agents immediately rather than waiting for a batch.
+9. Do not repeatedly ask reviewers to rediscover already-resolved findings.
+10. Include previous finding IDs in remediation review prompts.
+11. Use affected/local test suites during task development.
+12. Use full integration suites at feature/release gates.
+13. Avoid spawning agents for trivial repository-state inspection that the orchestrator can perform directly.
+14. Never use an LLM agent merely to wait.
+
+---
+
+# 25. ROLE BOUNDARIES
+
+## Orchestrator
+
+May:
+
+- Inspect.
+- Plan.
+- Create feature/release branches.
+- Maintain {{WORK_TRACKER}}.
+- Dispatch agents.
+- Verify gates.
+- Coordinate work.
+
+Must NOT:
+
+- Implement feature code.
+- Remediate code directly.
+- Perform independent review.
+- Substitute its own approval.
+- Merge task/feature/release PRs.
+
+## Development Agent
+
+May:
+
+- Implement assigned tasks.
+- Remediate findings.
+- Test.
+- Open task PRs.
+- Merge approved task PRs into feature branches.
+
+Must NOT:
+
+- Approve itself.
+- Independently review itself.
+- Merge to `{{INTEGRATION_BRANCH}}` or `{{RELEASE_BRANCH}}`.
+
+## Reviewer
+
+Read-only.
+
+Never edits or merges.
+
+## Approver
+
+Verifies final feature gates and performs feature → `{{INTEGRATION_BRANCH}}` merge.
+
+Never implements or reviews its own changes.
+
+## {{RELEASE_OWNER_NAME}} / `{{HOST_ACCOUNT}}`
+
+Only {{RELEASE_OWNER_NAME}} merges release PRs into `{{RELEASE_BRANCH}}`.
+
+---
+
+# 26. EXECUTION START
+
+At startup:
+
+1. Determine `MISSION_SCOPE`.
+2. Reconcile {{WORK_TRACKER}}.
+3. Inspect actual repository/PR state.
+4. Recover unfinished work if present.
+5. Establish `NEXT_ACTION`.
+6. Execute it.
+7. Enter `CONTROLLER_TICK`.
+8. Continue until a GLOBAL TERMINAL CONDITION is reached.
+
+Remember:
+
+**Never report a next executable step instead of performing it.**
+
+**Task completion triggers another controller cycle.**
+
+**Review completion triggers another controller cycle.**
+
+**Feature completion triggers another controller cycle unless the mission was explicitly limited to that feature.**
+
+**A locally blocked item triggers scheduling of other useful work whenever possible.**
+
+You are the controller of a persistent development pipeline. Keep the pipeline moving.
+
+---
+
+# 27. FOREGROUND TERMINAL RUNTIME
+
+This section is the execution contract for a foreground OpenCode
+orchestrator. It replaces the service runtime section in the rendered prompt
+and takes precedence over any service-specific runtime instructions later
+read from {{CONTEXT_STORE}}.
+
+The user explicitly started this run with `{{TERMINAL_LAUNCHER}}`. Begin
+work immediately in `{{PROJECT_ROOT}}`; do not start, wait for, or delegate
+control to `{{SERVICE_NAME}}`. This single OpenCode session owns the
+orchestration loop until a global terminal condition, an explicit user stop,
+or a host-forced yield.
+
+Execute `CONTROLLER_TICK` repeatedly inside this foreground session. Do not
+end a turn merely to emit `ORCHESTRATOR_STATE: CONTINUE`, and do not treat
+one task, review, pull request, or feature merge as completion. After every
+child result or external state change, reconcile {{CONTEXT_STORE}},
+{{WORK_TRACKER}}, Git, pull requests, and checks, then perform the next
+eligible action.
+
+The installed role launchers live at `{{CONTROL_HOME}}/scripts/`. Use
+`{{ROLE_LAUNCHER}}` for developer and approver sessions. Use
+`{{REVIEW_LAUNCHER}}` with WORKTREE, BASE_REF, HEAD_REF,
+REVIEW_PROMPT_FILE, PR_NUMBER, OUTPUT_FILE for a fresh read-only
+{{REVIEWER_DISPLAY_NAME}} review. Review output belongs under
+`{{SCRATCH_DIR}}`, and exact-head approval must be posted by
+`{{REVIEW_ACCOUNT}}`. The feature-to-{{INTEGRATION_BRANCH}} approver must
+use `{{MERGE_BROKER}}`; the orchestrator and developer never perform that
+merge.
+
+If the host forces a yield before a global terminal condition, return the
+machine-readable checkpoint from Section 22. The user can resume the same
+OpenCode session from the terminal. A yield is a checkpoint, not a claim that
+the project queue is complete.

templates/README.md

@@ -0,0 +1,32 @@
+# Reusing the development cycle prompt
+
+`ORCHESTRATOR-PROMPT.template.md` is the current NestQuest controller
+prompt with project-specific names, models, branches, identities, and launcher
+paths replaced by placeholders. `nestquest.profile.json` is the working
+example. Render a concrete prompt with:
+
+```bash
+scripts/render-cycle-prompt templates/nestquest.profile.json --output /tmp/opencode/nestquest-prompt.md
+```
+
+For another project, copy the profile and set its project name, tracker,
+context store, models, branch names, release owner, example IDs, review
+account, and installed launcher paths. Review the rendered result section by
+section, especially task/feature semantics, release rules, permissions,
+review gates, and the host runtime section. The template assumes an OpenCode
+controller, a feature/task tracker, a versioned context store, a code host,
+and a separate reviewer and approver. Adapt those sections when the project's
+systems differ. Section 27 is a single-session foreground loop suitable for
+`opencode --agent ... --prompt ...`; the reusable prompt has no service
+runtime.
+
+For NestQuest, `nq-orchestrate --print-prompt` emits the fully rendered
+foreground prompt without starting OpenCode. `nq-orchestrate [mission.md]`
+renders that same prompt, appends the optional mission, and supplies it to the
+foreground orchestrator agent.
+
+Publish the reviewed rendered prompt into that project's context store with
+its version check.
+Give the project its own agent definitions, broker, profile, and terminal
+launcher. The template itself does not start an orchestrator or register
+another project.

templates/nestquest.profile.json

@@ -0,0 +1,35 @@
+{
+  "LAST_UPDATED": "2026-09-22",
+  "PROJECT_CONTEXT_LABEL": "NESTQUEST HOUSE CHAOS COORDINATION",
+  "PROJECT_NAME": "NestQuest",
+  "WORK_TRACKER": "Maestro",
+  "CONTEXT_STORE": "CTXD",
+  "MODEL_PROVIDER": "OpenRouter",
+  "CONTROLLER_MODEL": "deepseek/deepseek-v4.1-flash",
+  "DEVELOPER_MODEL": "z-ai/glm-5.3-flash",
+  "REVIEWER_MODEL": "claude-sonnet-5",
+  "REVIEWER_DISPLAY_NAME": "Claude Sonnet 5",
+  "REVIEWER_HARNESS": "Claude Code",
+  "REVIEWER_VENDOR": "Claude",
+  "REVIEWER_CLI": "claude",
+  "MAX_DEVELOPERS": "2",
+  "MAX_DEVELOPERS_WORD": "two",
+  "INTEGRATION_BRANCH": "dev",
+  "RELEASE_BRANCH": "main",
+  "RELEASE_OWNER_NAME": "Joshua",
+  "HOST_ACCOUNT": "overseer",
+  "CODE_HOST": "Gitea",
+  "TASK_ID_EXAMPLE": "TASK-123",
+  "FEATURE_BRANCH_EXAMPLE": "feature/NQ-17-family-calendar",
+  "OPENCODE_VERSION": "1.18.32",
+  "PROJECT_ROOT": "/mnt/ai-storage/projects/NestQuest",
+  "CONTROL_HOME": "/home/overseer/.local/share/nestquest-controller",
+  "SERVICE_NAME": "nestquest-controller.service",
+  "TERMINAL_LAUNCHER": "nq-orchestrate",
+  "ROLE_LAUNCHER": "nq-agent",
+  "REVIEW_LAUNCHER": "nq-review",
+  "MERGE_BROKER": "nq-approve-merge",
+  "SCRATCH_DIR": "/tmp/opencode",
+  "REVIEW_ACCOUNT": "review_agent",
+  "TICK_TIMEOUT_LABEL": "six-hour"
+}

tests/conftest.py

@@ -22,7 +22,6 @@ pytest -q``); it is never meant to run against a real HA install.
 from __future__ import annotations
 
 import asyncio
-import datetime
 import importlib.util
 import inspect
 import sys
@@ -52,6 +51,7 @@ _HA_MODULES = (
     "homeassistant.helpers.entity",
     "homeassistant.helpers.event",
     "homeassistant.helpers.update_coordinator",
+    "homeassistant.helpers.aiohttp_client",
     "homeassistant.components",
     "homeassistant.components.sensor",
     "homeassistant.components.binary_sensor",
@@ -99,6 +99,7 @@ for _parent, _child in (
     ("homeassistant.helpers", "entity"),
     ("homeassistant.helpers", "event"),
     ("homeassistant.helpers", "update_coordinator"),
+    ("homeassistant.helpers", "aiohttp_client"),
     ("homeassistant", "components"),
     ("homeassistant.components", "sensor"),
     ("homeassistant.components", "binary_sensor"),
@@ -365,6 +366,15 @@ class BinarySensorEntity(Entity):
         return self._attr_device_class
 
 
+class UpdateFailed(HomeAssistantError):
+    """Stand-in mirroring homeassistant.helpers.update_coordinator.UpdateFailed.
+
+    The exception an update pass raises to report a failed fetch: the
+    coordinator records ``last_update_success = False`` instead of
+    propagating it out of the refresh.
+    """
+
+
 class DataUpdateCoordinator:
     """Functional stand-in for HA's DataUpdateCoordinator.
 
@@ -373,8 +383,20 @@ class DataUpdateCoordinator:
     ``async_add_listener``/``async_update_listeners`` for entity
     subscription, ``async_refresh``/``async_config_entry_first_refresh``
     driving the subclass's ``_async_update_data``, ``last_update_success``,
-    and ``data``.  Interval scheduling is NOT simulated (no real clock
-    ticks in tests) — tests drive refreshes directly.
+    ``last_exception``, and ``data``.  Interval scheduling is NOT
+    simulated (no real clock ticks in tests) — tests drive refreshes
+    directly.
+
+    The failure contract mirrors real HA exactly (it is the trap this
+    harness once hid): an update failure NEVER propagates out of
+    ``async_refresh`` — the coordinator records
+    ``last_update_success = False``, keeps its last good ``data``, and
+    still notifies listeners so entities re-render unavailable — and
+    ``async_config_entry_first_refresh`` wraps ANY failed pass in
+    :class:`ConfigEntryNotReady`, with the original error only
+    surviving as ``__cause__``.  A stand-in that re-raised the raw
+    update error would let setup code key on the original exception
+    type — a clause real HA can never reach.
     """
 
     def __init__(self, hass, logger, *, name=None, update_interval=None):
@@ -384,6 +406,7 @@ class DataUpdateCoordinator:
         self.update_interval = update_interval
         self.data = None
         self.last_update_success = False
+        self.last_exception = None
         self._listeners = []
 
     def async_add_listener(self, update_callback, context=None):
@@ -403,18 +426,35 @@ class DataUpdateCoordinator:
             callback()
 
     async def async_refresh(self):
-        """Run one update pass and notify listeners."""
+        """Run one update pass and notify listeners.
+
+        Mirrors HA: a failed update pass is RECORDED, never raised —
+        ``last_update_success`` goes False, the exception lands on
+        ``last_exception``, and listeners still fire; only cancellation
+        propagates.
+        """
         try:
             self.data = await self._async_update_data()
             self.last_update_success = True
-        except BaseException:
+        except Exception as err:
             self.last_update_success = False
-            raise
+            self.last_exception = err
         self.async_update_listeners()
 
     async def async_config_entry_first_refresh(self):
-        """First refresh at config-entry setup (alias of refresh)."""
+        """First refresh at config-entry setup, per HA's real contract.
+
+        HA's real ``async_config_entry_first_refresh`` wraps ANY failed
+        update pass in ``ConfigEntryNotReady`` — the original error
+        survives only as ``__cause__`` — so setup code that must
+        tolerate a failed first refresh keys on ConfigEntryNotReady,
+        never on the original exception type.
+        """
         await self.async_refresh()
+        if not self.last_update_success:
+            raise ConfigEntryNotReady(
+                f"error fetching {self.name} data: {self.last_exception}"
+            ) from self.last_exception
 
     async def async_shutdown(self):
         """Release listeners on teardown."""
@@ -424,6 +464,7 @@ class DataUpdateCoordinator:
 _update_coordinator_mock = _ha_mock("homeassistant.helpers.update_coordinator")
 _update_coordinator_mock.DataUpdateCoordinator = DataUpdateCoordinator
 _update_coordinator_mock.CoordinatorEntity = CoordinatorEntity
+_update_coordinator_mock.UpdateFailed = UpdateFailed
 
 _entity_mock = _ha_mock("homeassistant.helpers.entity")
 _entity_mock.DeviceInfo = DeviceInfo
@@ -700,6 +741,174 @@ def wire_entry_to_registry(entry, registry: ListenerRegistry):
     return entry
 
 
+class StubSnapshotClient:
+    """A no-network stand-in for the API client's snapshot surface.
+
+    Answers ``get_snapshot()`` from a scripted queue of outcomes — a
+    payload dict or an exception per call, consumed in order — and
+    records every call.  When the queue is exhausted it re-serves the
+    last outcome, so setup's first refresh and a test's explicit
+    refreshes poll the same scripted state.  Register it (or any
+    scripted client) with :func:`set_coordinator_client` BEFORE setup.
+    """
+
+    def __init__(self, *outcomes) -> None:
+        self.calls = 0
+        self._outcomes = list(outcomes)
+        self._last = outcomes[-1] if outcomes else None
+        #: The SSE frames the stand-in "published" (the API service's
+        # stream content), drained by :func:`refire_api_transitions`.
+        self.published_frames = []
+
+    async def get_snapshot(self):
+        self.calls += 1
+        if not self._outcomes:
+            # Re-serve the last outcome: setup's first refresh and the
+            # test's explicit pass both poll the same scripted state.
+            outcome = self._last
+        else:
+            outcome = self._outcomes.pop(0)
+            self._last = outcome
+        if isinstance(outcome, BaseException):
+            raise outcome
+        return outcome
+
+
+class ScriptedPanelClient(StubSnapshotClient):
+    """Snapshot + completion stand-in for the API service's panel plane.
+
+    Serves the scripted snapshot outcomes (like
+    :class:`StubSnapshotClient`), records ``complete_instance`` calls
+    the way the panel route receives them, optionally fails them the
+    way the client types the failure, and carries the SSE frames the
+    API "published" in ``published_frames`` for
+    :func:`refire_api_transitions` to deliver.  Everything the
+    integration reads over the wire, no network.
+    """
+
+    def __init__(self, *outcomes) -> None:
+        super().__init__(*outcomes)
+        self.complete_calls: list[tuple[int, int]] = []
+        self.published_frames: list[tuple[str, dict]] = []
+        #: When set, the next ``complete_instance`` raises this instead
+        # of succeeding (a typed NestQuestApiError in production).
+        self.fail_complete_with: BaseException | None = None
+
+    async def complete_instance(
+        self, instance_id: int, actor_child_id: int
+    ) -> dict:
+        self.complete_calls.append((instance_id, actor_child_id))
+        if self.fail_complete_with is not None:
+            raise self.fail_complete_with
+        return {"status": "done"}
+
+
+def set_coordinator_client(entry, client):
+    """Register a scripted client for ``entry``'s coordinator factory."""
+    import custom_components.nestquest.coordinator as coordinator_module
+
+    coordinator_module._COORDINATOR_CLIENT_OVERRIDES[entry.entry_id] = client
+    return client
+
+
+@pytest.fixture(autouse=True)
+def coordinator_client_from_test_override():
+    """Resolve every entry's coordinator client through the test seam.
+
+    The integration's setup builds its API client through
+    ``coordinator_client_from_entry``; this fixture swaps that factory
+    for a test one handing out the client registered with
+    :func:`set_coordinator_client`, or — for an entry with no scripted
+    client — a stub serving an EMPTY but valid household snapshot (the
+    shape the API's panel route returns before any child exists; the
+    real client would need aiohttp, which this mock-only harness does
+    not provide).
+    """
+    import datetime
+    import unittest.mock as mock
+
+    import custom_components.nestquest as nq_mod
+    import custom_components.nestquest.coordinator as coordinator_module
+
+    _COORDINATOR_CLIENT_OVERRIDES = (
+        coordinator_module._COORDINATOR_CLIENT_OVERRIDES
+    )
+
+    def _factory(hass, entry, **kwargs):
+        override = _COORDINATOR_CLIENT_OVERRIDES.get(entry.entry_id)
+        if override is not None:
+            return override
+        return StubSnapshotClient(
+            {
+                "today_iso": datetime.date.today().isoformat(),
+                "cycle_day": 0,
+                "children": [],
+            }
+        )
+
+    _COORDINATOR_CLIENT_OVERRIDES.clear()
+    patcher = mock.patch.object(
+        nq_mod, "coordinator_client_from_entry", _factory
+    )
+    patcher.start()
+    yield
+    patcher.stop()
+    _COORDINATOR_CLIENT_OVERRIDES.clear()
+
+
+async def refire_api_transitions(hass, entry, client):
+    """Deliver the SSE frames the stand-in client has published so far
+    through the integration's SSE subscription — the production event
+    path.
+
+    Since Feature 18 the ``complete_quest`` service fires no local
+    bus event: the API service builds and publishes the transition
+    frames on its SSE stream, and the integration's subscription
+    (:mod:`custom_components.nestquest.sse`) re-fires each frame on
+    the bus.  This helper streams the frames the stand-in client
+    published (``client.published_frames``) through a real
+    :class:`~custom_components.nestquest.sse.NestQuestEventStream`
+    and waits (bounded) until the bus has re-fired every one of them.
+    """
+    import asyncio
+
+    from custom_components.nestquest.sse import NestQuestEventStream
+
+    frames, client.published_frames = client.published_frames, []
+
+    class _ScriptedStream:
+        """A healthy stream: the frames, then it stays open."""
+
+        def __init__(self, frames) -> None:
+            self._frames = frames
+
+        def stream_events(self):
+            async def _gen():
+                for frame in self._frames:
+                    yield frame
+                await asyncio.Event().wait()
+
+            return _gen()
+
+    before = {etype: len(hass.bus.fired(etype)) for etype, _ in frames}
+    expected = len(frames)
+    manager = NestQuestEventStream(hass, _ScriptedStream(frames))
+    manager.start()
+    try:
+        async with asyncio.timeout(2):
+            while True:
+                delivered = sum(
+                    len(hass.bus.fired(etype)) - before[etype]
+                    for etype, _ in frames
+                )
+                if delivered >= expected:
+                    break
+                await asyncio.sleep(0.01)
+    finally:
+        await manager.stop()
+    return frames
+
+
 class _HassNamespace(SimpleNamespace):
     """SimpleNamespace subclass so the hass stub can hold weak references."""
 
@@ -923,42 +1132,6 @@ def make_config_flow_entry():
     return _factory
 
 
-def freeze_nestquest_clock(
-    monkeypatch, instant: datetime.datetime
-) -> tuple[datetime.datetime, list]:
-    """Freeze the integration's ``datetime`` clock to a fixed aware instant.
-
-    Only ``custom_components.nestquest``'s ``datetime`` binding is patched,
-    so the generation path's ``datetime.datetime.now`` reads this instant
-    (localized to whatever time zone it asks for) while every other module
-    and the test harness keep the real clock.  Returns ``(frozen, requested)``
-    where ``frozen`` is the instant normalized to UTC and ``requested`` is
-    the list of ``tzinfo`` objects the code under test passed to ``now`` —
-    so a caller can prove the generation path actually requested the
-    configured HA time zone rather than silently reading UTC.
-    """
-    import custom_components.nestquest as nestquest
-
-    frozen = instant.astimezone(datetime.timezone.utc)
-    requested: list = []
-
-    class _FrozenDatetime(datetime.datetime):
-        @classmethod
-        def now(cls, tz=None):
-            requested.append(tz)
-            if tz is None:
-                return frozen.replace(tzinfo=None)
-            return frozen.astimezone(tz)
-
-    fake_module = SimpleNamespace(
-        datetime=_FrozenDatetime,
-        timedelta=datetime.timedelta,
-        date=datetime.date,
-    )
-    monkeypatch.setattr(nestquest, "datetime", fake_module)
-    return frozen, requested
-
-
 # ---------------------------------------------------------------------------
 # Admin-plane API fixtures (shared by the admin-plane test modules).
 #

tests/test_admin_allowlist.py

@@ -1,21 +1,18 @@
-"""Tests for admin_allowlist.py: the Feature 03 allowlist business layer."""
+"""Tests for the Feature 03 admin allowlist business layer (core.admin_allowlist)."""
 from __future__ import annotations
 
 import asyncio
-from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from custom_components.nestquest import async_setup_entry, async_unload_entry
-from custom_components.nestquest.admin_allowlist import (
+from custom_components.nestquest.core.admin_allowlist import (
     list_admin_ids,
     seed_setup_admin,
     set_admin_ids,
 )
-from custom_components.nestquest.dao_children import AdminUsersDao
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
 
 
 def _run(coro):
@@ -193,165 +190,6 @@ def test_seed_rejects_malformed_candidates(tmp_path) -> None:
 
 
 # ---------------------------------------------------------------------------
-# Setup wiring: async_setup_entry seeds automatically
-# ---------------------------------------------------------------------------
-
-
-async def _setup_entry(hass, entry, registry):
-    from tests.test_lifecycle import _wire
-
-    entry = _wire(entry, registry)
-    await async_setup_entry(hass, entry)
-    return entry
-
-
-async def test_setup_seeds_allowlist_from_entry_context(
-    hass, make_entry
-) -> None:
-    entry = await _setup_entry(
-        hass,
-        make_entry(context={"user_id": "ha-owner"}),
-        hass.registry,
-    )
-    database = entry.runtime_data.database
-    try:
-        assert await list_admin_ids(database) == ["ha-owner"]
-    finally:
-        await database.close()
-    assert await async_unload_entry(hass, entry) is True
-
-
-async def test_setup_seeds_allowlist_from_stored_entry_data(
-    hass, make_entry
-) -> None:
-    """A lost database re-seeded from the entry's stored admin copy."""
-    from custom_components.nestquest.const import CONF_ADMIN_USER_IDS
-
-    entry = await _setup_entry(
-        hass,
-        make_entry(data={CONF_ADMIN_USER_IDS: ["user-a", "user-b"]}),
-        hass.registry,
-    )
-    database = entry.runtime_data.database
-    try:
-        assert await list_admin_ids(database) == ["user-a", "user-b"]
-    finally:
-        await database.close()
-    assert await async_unload_entry(hass, entry) is True
-
-
-async def test_setup_without_context_leaves_allowlist_empty(
-    hass, make_entry
-) -> None:
-    """Fail closed: no context user and no stored copy means an empty
-    allowlist — nobody is admin until the owner configures it."""
-    entry = await _setup_entry(hass, make_entry(), hass.registry)
-    database = entry.runtime_data.database
-    try:
-        assert await list_admin_ids(database) == []
-    finally:
-        await database.close()
-    assert await async_unload_entry(hass, entry) is True
-
-
-async def test_setup_does_not_reseed_narrowed_allowlist(
-    hass, make_entry
-) -> None:
-    from custom_components.nestquest import async_unload_entry
-    from custom_components.nestquest.const import CONF_ADMIN_USER_IDS
-
-    entry = await _setup_entry(
-        hass, make_entry(context={"user_id": "ha-owner"}), hass.registry
-    )
-    database = entry.runtime_data.database
-    await set_admin_ids(database, ["user-parent"])
-    await database.close()
-    assert await async_unload_entry(hass, entry) is True
-
-    # Reload with the SAME context: the narrowed list survives.
-    entry_reloaded = await _setup_entry(
-        hass, make_entry(context={"user_id": "ha-owner"}), hass.registry
-    )
-    database_b = entry_reloaded.runtime_data.database
-    try:
-        assert await list_admin_ids(database_b) == ["user-parent"]
-    finally:
-        await database.close()
-    assert await async_unload_entry(hass, entry_reloaded) is True
-
-
-async def test_setup_seed_prefers_options_over_entry_data(
-    hass, make_entry
-) -> None:
-    """Seed precedence on a fresh database: the options flow's saved
-    list (the current one) beats the config flow's original copy."""
-    from custom_components.nestquest.const import CONF_ADMIN_USER_IDS
-
-    entry = await _setup_entry(
-        hass,
-        make_entry(
-            options={CONF_ADMIN_USER_IDS: ["user-current"]},
-            data={CONF_ADMIN_USER_IDS: ["ha-owner"]},
-            context={"user_id": "ha-owner"},
-        ),
-        hass.registry,
-    )
-    database = entry.runtime_data.database
-    try:
-        assert await list_admin_ids(database) == ["user-current"]
-    finally:
-        await database.close()
-    assert await async_unload_entry(hass, entry) is True
-
-
-async def test_setup_owner_fallback_seeds_owner_accounts(
-    hass, make_entry
-) -> None:
-    """Last-resort seed: with no persisted copy and no flow-context
-    user, HA owner accounts are seeded so first setup is never
-    ownerless (the real flow may lose the context; owners can already
-    do everything in HA)."""
-    from unittest.mock import AsyncMock
-
-    hass.auth.async_get_users = AsyncMock(
-        return_value=[
-            SimpleNamespace(id="owner-1", is_owner=True),
-            SimpleNamespace(id="member-1", is_owner=False),
-            SimpleNamespace(id="owner-2", is_owner=True),
-        ]
-    )
-    entry = await _setup_entry(hass, make_entry(), hass.registry)
-    database = entry.runtime_data.database
-    try:
-        assert sorted(await list_admin_ids(database)) == ["owner-1", "owner-2"]
-    finally:
-        await database.close()
-    assert await async_unload_entry(hass, entry) is True
-
-
-async def test_setup_owner_fallback_not_used_when_context_present(
-    hass, make_entry
-) -> None:
-    """The context user (flow caller) wins over the owner fallback:
-    a non-owner parent configuring the integration becomes the admin."""
-    from unittest.mock import AsyncMock
-
-    hass.auth.async_get_users = AsyncMock(
-        return_value=[SimpleNamespace(id="owner-1", is_owner=True)]
-    )
-    entry = await _setup_entry(
-        hass,
-        make_entry(context={"user_id": "parent-configured"}),
-        hass.registry,
-    )
-    database = entry.runtime_data.database
-    try:
-        assert await list_admin_ids(database) == ["parent-configured"]
-    finally:
-        await database.close()
-    assert await async_unload_entry(hass, entry) is True
-
-
 def test_seed_owner_ids_argument(tmp_path) -> None:
     async def _body(database):
         # Malformed owner lists are rejected like any other candidate —
@@ -377,54 +215,13 @@ def test_seed_owner_ids_argument(tmp_path) -> None:
     _with_db(tmp_path, "seed-owner-arg.db")(_body)
 
 
-async def test_reopened_setup_failure_closes_database(
-    hass, make_entry, monkeypatch
-) -> None:
-    """A seeding failure on the reopened-record path closes the just-
-    opened connection before re-raising (no leaked handles across HA's
-    setup retries)."""
-    import pytest as pytest_module
-    from unittest.mock import AsyncMock
-
-    import custom_components.nestquest as nestquest_module
-    from custom_components.nestquest.db import NestQuestDatabase
-
-    # First: a successful setup to create the runtime record and file.
-    entry = await _setup_entry(hass, make_entry(), hass.registry)
-    await async_unload_entry(hass, entry)
-
-    # Now a re-setup whose seeding fails after the reopen.
-    async def _failing_seed(database, **kwargs):
-        raise RuntimeError("seed boom")
-
-    monkeypatch.setattr(
-        nestquest_module, "seed_setup_admin", _failing_seed, raising=True
-    )
-
-    close_calls: list[bool] = []
-    original_close = NestQuestDatabase.close
-
-    async def _spy_close(self):
-        close_calls.append(True)
-        return await original_close(self)
-
-    monkeypatch.setattr(NestQuestDatabase, "close", _spy_close)
-
-    with pytest_module.raises(RuntimeError, match="seed boom"):
-        await _setup_entry(hass, entry, hass.registry)
-    # The reopen path opened AND closed a connection; the failure is
-    # the last thing observed.
-    assert close_calls[-1] is True
-
-
-# ---------------------------------------------------------------------------
 # is_admin: the fail-closed resolver (Feature 09's verdict function)
 # ---------------------------------------------------------------------------
 
 
 def test_is_admin_verdict_matrix(tmp_path) -> None:
     async def _body(database):
-        from custom_components.nestquest.admin_allowlist import is_admin
+        from custom_components.nestquest.core.admin_allowlist import is_admin
 
         await set_admin_ids(database, ["user-owner"])
         assert await is_admin(database, "user-owner") is True
@@ -447,7 +244,7 @@ def test_is_admin_verdict_matrix(tmp_path) -> None:
 def test_is_admin_empty_allowlist_fails_closed(tmp_path) -> None:
     """An empty allowlist returns False for EVERYONE, not True."""
     async def _body(database):
-        from custom_components.nestquest.admin_allowlist import is_admin
+        from custom_components.nestquest.core.admin_allowlist import is_admin
 
         for candidate in ("user-owner", "", None, 1):
             assert await is_admin(database, candidate) is False
@@ -460,7 +257,7 @@ def test_is_admin_false_after_last_admin_removal_attempt(tmp_path) -> None:
     """The refusal keeps the verdict sound: a refused removal leaves
     the admin in place, so is_admin still resolves True."""
     async def _body(database):
-        from custom_components.nestquest.admin_allowlist import is_admin
+        from custom_components.nestquest.core.admin_allowlist import is_admin
 
         await set_admin_ids(database, ["user-owner"])
         with pytest.raises(ValueError, match="at least one admin"):

tests/test_api_client.py

@@ -0,0 +1,450 @@
+"""Tests for the panel-plane API client (Feature 18).
+
+The client is exercised against a STUB transport only — no network, no
+aiohttp, no homeassistant: the injected session is a fake that speaks
+the same ``request(...)`` surface aiohttp's ``ClientSession`` exposes
+and records every call, so the tests assert exactly what the client
+puts on the wire (method, URL, Bearer header, JSON body) and how every
+failure mode (non-2xx, connection failure, timeout, malformed JSON)
+surfaces as the typed :class:`NestQuestApiError`.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import types
+
+import pytest
+
+from conftest import make_config_entry
+
+from custom_components.nestquest import api_client
+from custom_components.nestquest.api_client import (
+    NestQuestApiClient,
+    NestQuestApiError,
+    is_valid_base_url,
+    resolve_api_config,
+)
+from custom_components.nestquest.const import (
+    CONF_API_BASE_URL,
+    CONF_PANEL_TOKEN,
+    DEFAULT_API_BASE_URL,
+    DEFAULT_PANEL_TOKEN,
+)
+
+BASE_URL = "http://api.test:8000"
+TOKEN = "test-panel-token"
+
+#: A realistic panel snapshot payload (the documented shape of the
+#: Feature 16 snapshot route).
+SNAPSHOT_PAYLOAD = {
+    "today_iso": "2026-09-23",
+    "cycle_day": 2,
+    "children": [
+        {
+            "child_id": 1,
+            "child_name": "Ada",
+            "present": False,
+            "next_present": "2026-09-24",
+            "due_today": 1,
+            "completed_today": 0,
+            "remaining_today": 1,
+            "completion_pct": 0,
+            "instances": [
+                {
+                    "id": 7,
+                    "definition_id": 3,
+                    "child_id": 1,
+                    "title": "Pack bag",
+                    "icon": None,
+                    "window": "morning",
+                    "due_time": "10:00",
+                    "state": "open",
+                    "overdue": True,
+                    "completed_at": None,
+                    "on_time": None,
+                }
+            ],
+        }
+    ],
+}
+
+
+class StubResponse:
+    """A fake aiohttp response: ``status`` plus ``await text()``."""
+
+    def __init__(self, status: int, body: str) -> None:
+        self.status = status
+        self._body = body
+
+    async def text(self) -> str:
+        return self._body
+
+
+class _OutcomeContext:
+    """Async context manager yielding one scripted outcome.
+
+    Mirrors aiohttp's ``session.request(...)`` return value: entering
+    the context performs the request, so a scripted transport error
+    raises THERE — before any response object exists, exactly where
+    aiohttp's connector raises on a refused connection.
+    """
+
+    def __init__(self, response, error) -> None:
+        self._response = response
+        self._error = error
+
+    async def __aenter__(self):
+        if self._error is not None:
+            raise self._error
+        return self._response
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        return False
+
+
+class StubTransport:
+    """A no-network stand-in for aiohttp's ``ClientSession``.
+
+    Records every ``request(...)`` call as a dict (method, url, headers,
+    json body) and answers from a scripted queue of outcomes — a
+    :class:`StubResponse` or an exception per call, consumed in order —
+    so each test drives exactly one exchange.
+    """
+
+    def __init__(self, *outcomes) -> None:
+        self.calls: list[dict] = []
+        self._outcomes = list(outcomes)
+
+    def request(self, method: str, url: str, **kwargs):
+        self.calls.append(
+            {
+                "method": method,
+                "url": url,
+                "headers": kwargs.get("headers"),
+                "json": kwargs.get("json"),
+            }
+        )
+        if not self._outcomes:
+            raise AssertionError("StubTransport ran out of scripted outcomes")
+        outcome = self._outcomes.pop(0)
+        if isinstance(outcome, BaseException):
+            return _OutcomeContext(None, outcome)
+        return _OutcomeContext(outcome, None)
+
+
+class HangingTransport:
+    """A transport whose request never answers (for the timeout test)."""
+
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+
+    def request(self, method: str, url: str, **kwargs):
+        self.calls.append({"method": method, "url": url})
+        return _HangingContext()
+
+
+class _HangingContext:
+    async def __aenter__(self):
+        await asyncio.sleep(5)
+        raise AssertionError("hanging transport was never cancelled")
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        return False
+
+
+def make_client(transport, *, timeout_seconds: float = 5.0) -> NestQuestApiClient:
+    """Build a client over the stub transport with the test credentials."""
+    return NestQuestApiClient(
+        BASE_URL, TOKEN, transport, timeout_seconds=timeout_seconds
+    )
+
+
+# ---------------------------------------------------------------------------
+# Success paths
+# ---------------------------------------------------------------------------
+
+
+async def test_get_snapshot_parses_payload_and_sends_bearer() -> None:
+    transport = StubTransport(
+        StubResponse(200, json.dumps(SNAPSHOT_PAYLOAD))
+    )
+    client = make_client(transport)
+
+    snapshot = await client.get_snapshot()
+
+    assert snapshot == SNAPSHOT_PAYLOAD
+    call = transport.calls[0]
+    assert call["method"] == "GET"
+    assert call["url"] == f"{BASE_URL}/api/v1/panel/snapshot"
+    assert call["headers"] == {"Authorization": f"Bearer {TOKEN}"}
+    assert call["json"] is None
+
+
+async def test_complete_instance_posts_body_and_headers() -> None:
+    transport = StubTransport(StubResponse(200, '{"status": "done"}'))
+    client = make_client(transport)
+
+    result = await client.complete_instance(42, 3)
+
+    assert result == {"status": "done"}
+    call = transport.calls[0]
+    assert call["method"] == "POST"
+    assert call["url"] == f"{BASE_URL}/api/v1/panel/instances/42/complete"
+    assert call["json"] == {"actor_child_id": 3}
+    assert call["headers"]["Authorization"] == f"Bearer {TOKEN}"
+
+
+async def test_base_url_trailing_slash_is_normalized() -> None:
+    """A base URL with a trailing slash must not double the path slash."""
+    transport = StubTransport(StubResponse(200, "{}"))
+    client = NestQuestApiClient(
+        f"{BASE_URL}/", TOKEN, transport, timeout_seconds=5.0
+    )
+    await client.get_snapshot()
+    assert transport.calls[0]["url"] == f"{BASE_URL}/api/v1/panel/snapshot"
+
+
+# ---------------------------------------------------------------------------
+# HTTP failures: the typed error carries the status
+# ---------------------------------------------------------------------------
+
+
+async def test_snapshot_401_raises_typed_error() -> None:
+    """A wrong/missing token answers 401 and surfaces with that status."""
+    transport = StubTransport(
+        StubResponse(401, '{"detail": "Missing or invalid panel service token"}')
+    )
+    client = make_client(transport)
+
+    with pytest.raises(NestQuestApiError) as excinfo:
+        await client.get_snapshot()
+
+    error = excinfo.value
+    assert error.status == 401
+    assert not error.is_transport_error
+    assert error.__cause__ is None
+    # The token is a secret: it never reaches the raised message.
+    assert TOKEN not in str(error)
+
+
+async def test_complete_unknown_instance_404_raises_typed_error() -> None:
+    transport = StubTransport(
+        StubResponse(404, '{"detail": "Quest instance not found"}')
+    )
+    client = make_client(transport)
+
+    with pytest.raises(NestQuestApiError) as excinfo:
+        await client.complete_instance(999999, 1)
+
+    assert excinfo.value.status == 404
+    assert not excinfo.value.is_transport_error
+
+
+async def test_snapshot_500_raises_typed_error() -> None:
+    """Any non-2xx response is typed, whatever the status."""
+    transport = StubTransport(StubResponse(500, "{}"))
+    client = make_client(transport)
+
+    with pytest.raises(NestQuestApiError) as excinfo:
+        await client.get_snapshot()
+
+    assert excinfo.value.status == 500
+
+
+async def test_malformed_2xx_body_raises_typed_with_status() -> None:
+    """A 2xx body that is not JSON is a protocol failure, carrying its status."""
+    transport = StubTransport(StubResponse(200, "<html>not json</html>"))
+    client = make_client(transport)
+
+    with pytest.raises(NestQuestApiError) as excinfo:
+        await client.get_snapshot()
+
+    assert excinfo.value.status == 200
+
+
+# ---------------------------------------------------------------------------
+# Transport failures: the typed error carries no status and chains the cause
+# ---------------------------------------------------------------------------
+
+
+async def test_connection_failure_raises_transport_error() -> None:
+    transport = StubTransport(OSError("connection refused"))
+    client = make_client(transport)
+
+    with pytest.raises(NestQuestApiError) as excinfo:
+        await client.get_snapshot()
+
+    error = excinfo.value
+    assert error.status is None
+    assert error.is_transport_error
+    assert isinstance(error.__cause__, OSError)
+
+
+async def test_connection_failure_on_complete_is_typed() -> None:
+    transport = StubTransport(OSError("connection refused"))
+    client = make_client(transport)
+
+    with pytest.raises(NestQuestApiError) as excinfo:
+        await client.complete_instance(7, 1)
+
+    assert excinfo.value.status is None
+    assert excinfo.value.is_transport_error
+
+
+async def test_request_timeout_raises_transport_error() -> None:
+    """A hung API call surfaces as a typed transport error, once, with
+    no retry: the one request is cancelled by the client's timeout."""
+    transport = HangingTransport()
+    client = make_client(transport, timeout_seconds=0.05)
+
+    with pytest.raises(NestQuestApiError) as excinfo:
+        await client.get_snapshot()
+
+    assert excinfo.value.status is None
+    assert excinfo.value.is_transport_error
+    assert len(transport.calls) == 1
+
+
+# ---------------------------------------------------------------------------
+# Construction and config resolution
+# ---------------------------------------------------------------------------
+
+
+def test_constructor_requires_full_base_url() -> None:
+    for bad_url in (None, "", "   ", "api.lan:8000", "http://", "ftp://x"):
+        with pytest.raises(ValueError):
+            NestQuestApiClient(bad_url, TOKEN, StubTransport())
+
+
+def test_constructor_requires_non_empty_token() -> None:
+    for bad_token in (None, "", "   "):
+        with pytest.raises(ValueError):
+            NestQuestApiClient(BASE_URL, bad_token, StubTransport())
+
+
+def test_constructor_requires_positive_timeout() -> None:
+    for bad_timeout in (0, -1, "5", True, None):
+        with pytest.raises(ValueError):
+            NestQuestApiClient(
+                BASE_URL, TOKEN, StubTransport(), timeout_seconds=bad_timeout
+            )
+
+
+def test_is_valid_base_url_accepts_full_http_urls() -> None:
+    assert is_valid_base_url("http://127.0.0.1:8000")
+    assert is_valid_base_url("https://nestquest.lan")
+    assert is_valid_base_url(" http://127.0.0.1:8000 ")
+    assert not is_valid_base_url("api.lan:8000")
+    assert not is_valid_base_url("http://")
+    assert not is_valid_base_url("")
+    assert not is_valid_base_url(None)
+    assert not is_valid_base_url(42)
+
+
+def test_resolve_api_config_prefers_options_then_data_then_defaults() -> None:
+    options_only = make_config_entry(
+        options={CONF_API_BASE_URL: "http://from-options:1"}
+    )
+    assert resolve_api_config(options_only) == (
+        "http://from-options:1",
+        DEFAULT_PANEL_TOKEN,
+    )
+
+    data_only = make_config_entry(
+        data={
+            CONF_API_BASE_URL: "http://from-data:2",
+            CONF_PANEL_TOKEN: "from-data",
+        }
+    )
+    assert resolve_api_config(data_only) == ("http://from-data:2", "from-data")
+
+    both = make_config_entry(
+        options={CONF_API_BASE_URL: "http://from-options:3"},
+        data={
+            CONF_API_BASE_URL: "http://from-data:4",
+            CONF_PANEL_TOKEN: "from-data",
+        },
+    )
+    assert resolve_api_config(both) == (
+        "http://from-options:3",
+        "from-data",
+    )
+
+    bare = make_config_entry()
+    assert resolve_api_config(bare) == (DEFAULT_API_BASE_URL, DEFAULT_PANEL_TOKEN)
+
+
+def test_client_from_entry_reads_config_and_shared_session(monkeypatch) -> None:
+    """The production factory resolves the entry config and hands in HA's
+    shared aiohttp session (stubbed module — no real HA, no network)."""
+    fake_module = types.ModuleType("homeassistant.helpers.aiohttp_client")
+    shared_session = object()
+    fake_module.async_get_clientsession = lambda hass: shared_session
+    monkeypatch.setitem(
+        sys.modules, "homeassistant.helpers.aiohttp_client", fake_module
+    )
+    entry = make_config_entry(
+        options={
+            CONF_API_BASE_URL: "http://panel.lan:8443",
+            CONF_PANEL_TOKEN: "entry-token",
+        }
+    )
+
+    client = api_client.client_from_entry(object(), entry)
+
+    assert client._session is shared_session
+    assert client._base_url == "http://panel.lan:8443"
+    assert client._panel_token == "entry-token"
+
+
+def test_client_from_entry_unconfigured_token_raises_at_construction(
+    monkeypatch,
+) -> None:
+    """An entry with NO configured token (the shipped default) raises
+    ValueError AT CONSTRUCTION — the client's fail-fast guard — rather
+    than silently building a client that can only 401 (the documented
+    contract: the options flow's non-empty validation is the user-facing
+    guard; the coordinator must ensure a token is configured first or
+    handle the construction error as "API not configured")."""
+    fake_module = types.ModuleType("homeassistant.helpers.aiohttp_client")
+    fake_module.async_get_clientsession = lambda hass: object()
+    monkeypatch.setitem(
+        sys.modules, "homeassistant.helpers.aiohttp_client", fake_module
+    )
+    entry = make_config_entry(
+        options={CONF_API_BASE_URL: DEFAULT_API_BASE_URL},
+    )
+    assert resolve_api_config(entry)[1] == DEFAULT_PANEL_TOKEN == ""
+
+    with pytest.raises(ValueError, match="panel_token must be a non-empty"):
+        api_client.client_from_entry(object(), entry)
+
+    # Same for a whitespace-only stored token: whitespace is not a token.
+    entry_ws = make_config_entry(options={CONF_PANEL_TOKEN: "   "})
+    with pytest.raises(ValueError, match="panel_token must be a non-empty"):
+        api_client.client_from_entry(object(), entry_ws)
+
+
+async def test_client_logs_nothing() -> None:
+    """The client emits no log records at all (the token must never
+    reach a log line), success or failure."""
+    import logging
+
+    records: list[logging.LogRecord] = []
+
+    class _Capture(logging.Handler):
+        def emit(self, record: logging.LogRecord) -> None:
+            records.append(record)
+
+    handler = _Capture()
+    logging.getLogger().addHandler(handler)
+    try:
+        transport = StubTransport(StubResponse(401, "{}"))
+        client = make_client(transport)
+        with pytest.raises(NestQuestApiError):
+            await client.get_snapshot()
+    finally:
+        logging.getLogger().removeHandler(handler)
+    assert records == []

tests/test_binary_sensors.py

@@ -1,50 +1,85 @@
-"""Tests for the per-child binary sensors (Feature 10, task 4)."""
+"""Tests for the per-child binary sensors (Feature 10, task 4).
+
+The snapshot comes from the API service's panel route (the presence
+engine resolves server-side), so these tests script the route's
+payload through :class:`conftest.StubSnapshotClient` instead of
+seeding a local database.
+"""
 from __future__ import annotations
 
-import datetime
-
-from conftest import wire_entry_to_registry
+from conftest import StubSnapshotClient, set_coordinator_client, wire_entry_to_registry
 
 from custom_components.nestquest import async_setup_entry
-from custom_components.nestquest.children import create_child, list_children
 from custom_components.nestquest.const import DOMAIN
-from custom_components.nestquest.dao_presence import PresenceSchedulesDao
-from custom_components.nestquest.materialize import materialize
-from custom_components.nestquest.quest_definitions import (
-    create_quest_definition,
-)
-from custom_components.nestquest.recurrence import ScheduleRule
-from custom_components.nestquest.completion import complete_instance
-
-SEED_HORIZON_DAYS = 3
 
 
 def _binary(hass, child_id: int, kind: str):
     return hass.entities[f"{DOMAIN}_child_{child_id}_{kind}"]
 
 
-async def _setup_entry(hass, make_entry):
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    return entry
+def _child(
+    child_id: int,
+    name: str,
+    *,
+    present=True,
+    next_present=None,
+    instances=(),
+):
+    completed = sum(1 for i in instances if i["state"] == "completed")
+    due = len(instances)
+    return {
+        "child_id": child_id,
+        "child_name": name,
+        "present": present,
+        "next_present": next_present,
+        "due_today": due,
+        "completed_today": completed,
+        "remaining_today": due - completed,
+        "completion_pct": 100 if due == 0 else round(completed / due * 100),
+        "instances": list(instances),
+    }
 
 
-async def _seed_two_children(database) -> tuple:
-    ada = await create_child(database, "Ada")
-    bo = await create_child(database, "Bo")
-    today = datetime.date.today()
-    await create_quest_definition(
-        database,
-        "Brush teeth",
-        ScheduleRule.from_dict(
-            {"rule_type": "daily", "start_date": today.isoformat()}
+def _instance(instance_id: int, child_id: int, *, state="open") -> dict:
+    return {
+        "id": instance_id,
+        "definition_id": 3,
+        "child_id": child_id,
+        "title": "Brush teeth",
+        "icon": "🦷",
+        "window": "morning",
+        "due_time": "08:00",
+        "state": state,
+        "overdue": False,
+        "completed_at": None if state == "open" else "2026-09-23T07:55:00+00:00",
+        "on_time": None if state == "open" else True,
+    }
+
+
+def _payload(children) -> dict:
+    return {
+        "today_iso": "2026-09-23",
+        "cycle_day": 0,
+        "children": list(children),
+    }
+
+
+ADA = 1
+BO = 2
+CORY = 3
+
+
+async def _setup_entry(hass, make_entry, *payloads):
+    """Set up the integration with a scripted snapshot client."""
+    entry = wire_entry_to_registry(
+        make_entry(
+            data={"api_base_url": "http://api.test:8000", "panel_token": "tok"}
         ),
-        [ada.id, bo.id],
-        ["morning"],
+        hass.registry,
     )
-    end = (today + datetime.timedelta(days=SEED_HORIZON_DAYS)).isoformat()
-    await materialize(database, today.isoformat(), end, today=today)
-    return ada, bo
+    set_coordinator_client(entry, StubSnapshotClient(*payloads))
+    assert await async_setup_entry(hass, entry) is True
+    return entry, entry.runtime_data.coordinator
 
 
 async def test_all_done_off_with_open_quests_and_zero_quests(
@@ -52,88 +87,76 @@ async def test_all_done_off_with_open_quests_and_zero_quests(
 ) -> None:
     """all_done is OFF while quests are owed AND on a zero-quest day;
     a child with no quests never fires the celebration automation."""
-    entry = await _setup_entry(hass, make_entry)
-    coordinator = entry.runtime_data.coordinator
-    database = entry.runtime_data.database
-    ada, _bo = await _seed_two_children(database)
-    await create_child(database, "Cory")  # zero quests
-    await coordinator.async_refresh()
+    _entry, coordinator = await _setup_entry(
+        hass,
+        make_entry,
+        _payload(
+            [
+                _child(ADA, "Ada", instances=[_instance(7, ADA)]),
+                _child(BO, "Bo", instances=[_instance(8, BO)]),
+                _child(CORY, "Cory"),
+            ]
+        ),
+    )
 
-    assert _binary(hass, ada.id, "all_done").is_on is False
-    cory = [
-        child for child in coordinator.data.children
-        if child.child_name == "Cory"
-    ][0]
-    assert _binary(hass, cory.child_id, "all_done").is_on is False
+    assert _binary(hass, ADA, "all_done").is_on is False
+    assert _binary(hass, BO, "all_done").is_on is False
+    assert _binary(hass, CORY, "all_done").is_on is False
 
 
 async def test_all_done_on_only_when_day_clear(hass, make_entry) -> None:
-    entry = await _setup_entry(hass, make_entry)
-    coordinator = entry.runtime_data.coordinator
-    database = entry.runtime_data.database
-    ada, _bo = await _seed_two_children(database)
-    await coordinator.async_refresh()
-    snapshot_ada = [
-        child for child in coordinator.data.children
-        if child.child_id == ada.id
-    ][0]
-    instance_id = snapshot_ada.instances[0].instance_id
-    await complete_instance(
-        database,
-        instance_id,
-        actor_source="panel",
-        actor_child_id=ada.id,
+    _entry, coordinator = await _setup_entry(
+        hass,
+        make_entry,
+        _payload([_child(ADA, "Ada", instances=[_instance(7, ADA)])]),
+        _payload(
+            [
+                _child(
+                    ADA,
+                    "Ada",
+                    instances=[_instance(7, ADA, state="completed")],
+                )
+            ]
+        ),
     )
     await coordinator.async_refresh()
-    assert _binary(hass, ada.id, "all_done").is_on is True
+    assert _binary(hass, ADA, "all_done").is_on is True
 
 
 async def test_present_today_on_without_schedule_off_when_absent(
     hass, make_entry
 ) -> None:
-    """No schedule means present every day; an all-absent pattern
-    today reports OFF."""
-    entry = await _setup_entry(hass, make_entry)
-    coordinator = entry.runtime_data.coordinator
-    database = entry.runtime_data.database
-    ada, _bo = await _seed_two_children(database)
-    await create_child(database, "Cory")
-    today = datetime.date.today()
-    await coordinator.async_refresh()
-    cory = [
-        child for child in coordinator.data.children
-        if child.child_name == "Cory"
-    ][0]
-    await PresenceSchedulesDao(database).upsert_by_child(
-        cory.child_id, 1, today.isoformat(), ""
+    """Presence is resolved by the API's presence engine: present=True
+    renders ON, present=False renders OFF."""
+    _entry, _coordinator = await _setup_entry(
+        hass,
+        make_entry,
+        _payload([_child(ADA, "Ada"), _child(CORY, "Cory", present=False)]),
     )
-    await coordinator.async_refresh()
 
-    assert _binary(hass, ada.id, "present_today").is_on is True
-    assert _binary(hass, cory.child_id, "present_today").is_on is False
+    assert _binary(hass, ADA, "present_today").is_on is True
+    assert _binary(hass, CORY, "present_today").is_on is False
 
 
 async def test_binary_sensor_identity_and_attributes(hass, make_entry) -> None:
-    entry = await _setup_entry(hass, make_entry)
-    coordinator = entry.runtime_data.coordinator
-    database = entry.runtime_data.database
-    ada, _bo = await _seed_two_children(database)
-    await coordinator.async_refresh()
+    _entry, _coordinator = await _setup_entry(
+        hass, make_entry, _payload([_child(ADA, "Ada")])
+    )
 
-    all_done = _binary(hass, ada.id, "all_done")
-    present = _binary(hass, ada.id, "present_today")
-    assert all_done.unique_id == f"nestquest_child_{ada.id}_all_done"
-    assert present.unique_id == f"nestquest_child_{ada.id}_present_today"
+    all_done = _binary(hass, ADA, "all_done")
+    present = _binary(hass, ADA, "present_today")
+    assert all_done.unique_id == f"nestquest_child_{ADA}_all_done"
+    assert present.unique_id == f"nestquest_child_{ADA}_present_today"
     assert all_done.name == "NestQuest Ada all done"
     assert present.name == "NestQuest Ada present today"
     for entity in (all_done, present):
         assert entity.device_info.name == "NestQuest Ada"
         assert all_done.extra_state_attributes == {
-            "child_id": ada.id,
+            "child_id": ADA,
             "child_name": "Ada",
         }
         assert present.extra_state_attributes == {
-            "child_id": ada.id,
+            "child_id": ADA,
             "child_name": "Ada",
             "next_present": None,
         }
@@ -145,40 +168,28 @@ async def test_present_today_carries_next_present_when_away(
     """A child away today carries the ISO date of their next present
     day (the panel's away plate renders ``Returns <weekday>, <Mon D>``
     from it); an always-absent pattern carries ``None``."""
-    entry = await _setup_entry(hass, make_entry)
-    coordinator = entry.runtime_data.coordinator
-    database = entry.runtime_data.database
-    ada, _bo = await _seed_two_children(database)
-    await create_child(database, "Cory")
-    today = datetime.date.today()
-    pattern = ",".join(
-        str(day) for day in range(7) if day != today.weekday()
+    _entry, _coordinator = await _setup_entry(
+        hass,
+        make_entry,
+        _payload(
+            [
+                _child(
+                    ADA,
+                    "Ada",
+                    present=False,
+                    next_present="2026-09-24",
+                ),
+                _child(CORY, "Cory", present=False, next_present=None),
+            ]
+        ),
     )
-    await PresenceSchedulesDao(database).upsert_by_child(
-        ada.id, 1, today.isoformat(), pattern
-    )
-    await PresenceSchedulesDao(database).upsert_by_child(
-        await _cory_id(database), 1, today.isoformat(), ""
-    )
-    await coordinator.async_refresh()
 
-    assert _binary(hass, ada.id, "present_today").is_on is False
-    assert _binary(hass, ada.id, "present_today").extra_state_attributes[
+    assert _binary(hass, ADA, "present_today").is_on is False
+    assert _binary(hass, ADA, "present_today").extra_state_attributes[
         "next_present"
-    ] == (today + datetime.timedelta(days=1)).isoformat()
+    ] == "2026-09-24"
 
-    cory = [
-        child for child in coordinator.data.children
-        if child.child_name == "Cory"
-    ][0]
-    assert _binary(hass, cory.child_id, "present_today").is_on is False
-    assert _binary(hass, cory.child_id, "present_today").extra_state_attributes[
+    assert _binary(hass, CORY, "present_today").is_on is False
+    assert _binary(hass, CORY, "present_today").extra_state_attributes[
         "next_present"
     ] is None
-
-
-async def _cory_id(database) -> int:
-    for child in await list_children(database):
-        if child.display_name == "Cory":
-            return child.id
-    raise AssertionError("Cory was not created")

tests/test_children_registry.py

@@ -8,16 +8,16 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from custom_components.nestquest.children import (
+from custom_components.nestquest.core.children import (
     create_child,
     edit_child,
     list_children,
     reorder_children,
     set_child_active,
 )
-from custom_components.nestquest.dao_children import ChildRecord, ChildrenDao
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.core.dao_children import ChildRecord, ChildrenDao
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
 
 
 def _run(coro):
@@ -739,12 +739,12 @@ def test_deactivating_child_preserves_definitions_instances_events(
     async def _body(database):
         from datetime import date, timedelta
 
-        from custom_components.nestquest.dao_children import ChildrenDao
-        from custom_components.nestquest.dao_instances import (
+        from custom_components.nestquest.core.dao_children import ChildrenDao
+        from custom_components.nestquest.core.dao_instances import (
             CompletionEventsDao,
             QuestInstancesDao,
         )
-        from custom_components.nestquest.dao_rules import (
+        from custom_components.nestquest.core.dao_rules import (
             QuestDefinitionsDao,
             ScheduleRulesDao,
         )
@@ -831,7 +831,7 @@ def test_no_code_path_deletes_a_child_row() -> None:
 
     import inspect
 
-    from custom_components.nestquest.dao_children import ChildrenDao
+    from custom_components.nestquest.core.dao_children import ChildrenDao
 
     methods = {
         name

tests/test_complete_quest_proxy.py

@@ -0,0 +1,214 @@
+"""The ``nestquest.complete_quest`` proxy to the API client (Feature 18).
+
+The service is a thin proxy: a panel tap must reach the API's panel
+complete route through the entry's ONE shared API client (the same
+instance the coordinator polls and the SSE subscription reads), with
+exactly the payload contract the panel cards send (``instance_id``,
+``actor=panel``, ``actor_child_id``).  The service performs NO local
+completion and fires NO local bus event — the API service emits the
+transition on its SSE stream and the integration's subscription
+re-fires it (firing it locally too would double-fire) — and it
+refreshes the coordinator after a successful call so the sensors
+reflect the completion immediately.  Every failure (a typed
+:class:`NestQuestApiError`, an unconfigured client, a non-panel actor)
+surfaces as a :class:`HomeAssistantError`, token-free.
+
+The scripted clients here stand in for the API service: recording and
+failing ``complete_instance`` implementations, no network, no aiohttp.
+"""
+from __future__ import annotations
+
+import pytest
+from homeassistant.exceptions import HomeAssistantError
+
+from conftest import ScriptedPanelClient, set_coordinator_client, wire_entry_to_registry
+
+from custom_components.nestquest import async_setup_entry
+from custom_components.nestquest.api_client import NestQuestApiError
+from custom_components.nestquest.const import (
+    CONF_PANEL_TOKEN,
+    DOMAIN,
+    EVENT_CHILD_DAY_COMPLETE,
+    EVENT_QUEST_COMPLETED,
+    SERVICE_COMPLETE_QUEST,
+)
+
+
+class _RecordingApiClient(ScriptedPanelClient):
+    """Snapshot-only stand-in that RECORDS completion calls.
+
+    ``complete_instance`` deliberately performs NO local write: the
+    API service is remote, and the assertions below must be able to
+    prove the service handler itself completed nothing locally.
+    """
+
+
+class _FailingApiClient(_RecordingApiClient):
+    """A stand-in whose completion fails the way the client types it."""
+
+    def __init__(self, error: NestQuestApiError, *outcomes) -> None:
+        super().__init__(*outcomes)
+        self.fail_complete_with = error
+
+
+def _empty_snapshot() -> dict:
+    return {
+        "today_iso": "2026-09-23",
+        "cycle_day": 0,
+        "children": [],
+    }
+
+
+async def _setup_entry(hass, make_entry, client):
+    """Wire, script, and set up an entry against the scripted client."""
+    entry = wire_entry_to_registry(
+        make_entry(data={CONF_PANEL_TOKEN: "secret-panel-token"}),
+        hass.registry,
+    )
+    set_coordinator_client(entry, client)
+    assert await async_setup_entry(hass, entry) is True
+    return entry
+
+
+def _record_refreshes(entry) -> list[bool]:
+    """Replace the coordinator's refresh with a recording stand-in."""
+    refreshes: list[bool] = []
+
+    async def _fake_refresh():
+        refreshes.append(True)
+
+    entry.runtime_data.coordinator.async_refresh = _fake_refresh
+    return refreshes
+
+
+async def test_complete_quest_reaches_the_shared_api_client(
+    hass, make_entry
+) -> None:
+    """A panel tap calls ``complete_instance`` on the entry's shared
+    client with the tapped child, fires NO local event, and refreshes
+    the coordinator immediately."""
+    client = _RecordingApiClient(_empty_snapshot())
+    entry = await _setup_entry(hass, make_entry, client)
+    assert entry.runtime_data.coordinator.api_client is client, (
+        "the service must proxy through the entry's ONE shared client"
+    )
+    refreshes = _record_refreshes(entry)
+
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {
+            "instance_id": 7,
+            "actor": "panel",
+            "actor_child_id": 1,
+        },
+    )
+
+    assert client.complete_calls == [(7, 1)]
+    # No local firing: the completed (and day-complete) events arrive
+    # over the SSE stream, re-fired by the subscription — never from
+    # this handler.
+    assert hass.bus.fired(EVENT_QUEST_COMPLETED) == []
+    assert hass.bus.fired(EVENT_CHILD_DAY_COMPLETE) == []
+    # The old immediate-update behaviour: the sensors' coordinator
+    # refresh runs before the service call returns.
+    assert refreshes == [True]
+
+
+@pytest.mark.parametrize(
+    ("error", "fragment"),
+    [
+        (
+            NestQuestApiError(
+                "NestQuest API POST /api/v1/panel/instances/7/complete "
+                "failed with HTTP 401",
+                status=401,
+            ),
+            "failed with HTTP 401",
+        ),
+        (
+            NestQuestApiError(
+                "NestQuest API POST /api/v1/panel/instances/7/complete "
+                "transport failure: connection refused",
+                status=None,
+            ),
+            "transport failure",
+        ),
+    ],
+)
+async def test_api_failure_surfaces_as_a_service_error(
+    hass, make_entry, error, fragment
+) -> None:
+    """A typed API failure (non-2xx or transport) raises
+    ``HomeAssistantError`` carrying the typed message — which never
+    includes the panel token — with nothing fired locally, and no
+    refresh for a mutation that never happened."""
+    client = _FailingApiClient(error, _empty_snapshot())
+    entry = await _setup_entry(hass, make_entry, client)
+    refreshes = _record_refreshes(entry)
+
+    with pytest.raises(HomeAssistantError, match=fragment) as excinfo:
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": 7,
+                "actor": "panel",
+                "actor_child_id": 1,
+            },
+        )
+    # The typed error is chained, and the service error carries the
+    # typed message only — never the panel token.
+    assert excinfo.value.__cause__ is error
+    assert "secret-panel-token" not in str(excinfo.value)
+    assert client.complete_calls == [(7, 1)]
+    assert hass.bus.fired(EVENT_QUEST_COMPLETED) == []
+    assert hass.bus.fired(EVENT_CHILD_DAY_COMPLETE) == []
+    assert refreshes == []
+
+
+async def test_unconfigured_api_client_surfaces_as_a_service_error(
+    hass, make_entry
+) -> None:
+    """An entry with no completion surface (the unconfigured-token
+    stub the coordinator swaps in) fails the service clearly instead
+    of reaching an attribute error."""
+    from custom_components.nestquest.coordinator import _UnconfiguredApiClient
+
+    await _setup_entry(hass, make_entry, _UnconfiguredApiClient())
+
+    with pytest.raises(
+        HomeAssistantError, match="NestQuest API is not configured"
+    ):
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": 7,
+                "actor": "panel",
+                "actor_child_id": 1,
+            },
+        )
+
+
+async def test_non_panel_actor_is_rejected_before_the_client(
+    hass, make_entry
+) -> None:
+    """The API's panel route completes as the tapped child only: a
+    user-actor call fails fast with a clear error and never reaches
+    the client."""
+    client = _RecordingApiClient(_empty_snapshot())
+    await _setup_entry(hass, make_entry, client)
+
+    with pytest.raises(HomeAssistantError, match="actor must be 'panel'"):
+        await hass.services.call(
+            DOMAIN,
+            SERVICE_COMPLETE_QUEST,
+            {
+                "instance_id": 7,
+                "actor": "user",
+                "actor_user_id": "admin-1",
+            },
+            context={"user_id": "admin-1"},
+        )
+    assert client.complete_calls == []

tests/test_completion.py

@@ -8,27 +8,27 @@ import re
 
 import pytest
 
-from custom_components.nestquest.completion import (
+from custom_components.nestquest.core.completion import (
     append_event,
     complete_instance,
     instance_state,
     list_missed_for_child,
     uncomplete_instance,
 )
-from custom_components.nestquest.dao_children import ChildrenDao
-from custom_components.nestquest.dao_instances import (
+from custom_components.nestquest.core.dao_children import ChildrenDao
+from custom_components.nestquest.core.dao_instances import (
     EVENT_COMPLETED,
     EVENT_UNCOMPLETED,
     CompletionEventRecord,
     CompletionEventsDao,
     QuestInstancesDao,
 )
-from custom_components.nestquest.dao_rules import (
+from custom_components.nestquest.core.dao_rules import (
     QuestDefinitionsDao,
     ScheduleRulesDao,
 )
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
 
 
 def _run(coro):
@@ -311,7 +311,7 @@ def test_now_pins_occurred_at_utc(tmp_path) -> None:
 
 
 def test_module_never_exposes_update_or_delete() -> None:
-    import custom_components.nestquest.completion as completion
+    import custom_components.nestquest.core.completion as completion
 
     public = {
         name

tests/test_config_flow.py

@@ -156,23 +156,13 @@ def test_no_hardcoded_domain_or_db_filename_in_new_modules() -> None:
                     f"Found hard-coded database filename in {py_file.name}:{node.lineno}"
                 )
 
-async def test_flow_persists_flow_user_as_initial_admin(hass, make_flow) -> None:
-    """The HA user completing the flow lands in entry data as the
-    initial admin copy: entry.context is not persisted by real HA, so
-    the durable record must carry the owner."""
-    from custom_components.nestquest.const import CONF_ADMIN_USER_IDS
-
-    flow = make_flow(hass)
-    flow.context = {"user_id": "ha-owner"}
-    result = await flow.async_step_user({})
-    assert result["type"] == "create_entry"
-    assert result["data"] == {CONF_ADMIN_USER_IDS: ["ha-owner"]}
-
-
 async def test_flow_without_context_user_keeps_data_untouched(
     hass, make_flow
 ) -> None:
+    """A submit with user input stores it as-is; no admin copy is
+    invented (the allowlist lives in the API service's own store since
+    the DB removal)."""
     flow = make_flow(hass)
-    result = await flow.async_step_user({"horizon_days": 7})
+    result = await flow.async_step_user({"update_interval": 60})
     assert result["type"] == "create_entry"
-    assert result["data"] == {"horizon_days": 7}
+    assert result["data"] == {"update_interval": 60}

tests/test_core_settings.py

@@ -14,9 +14,9 @@ Covers the contracts from task 4dd8f870 plus the review fixes:
   test feeds the scanner each bypass shape and asserts it flags them.
 - A settings object constructed with NON-default ``horizon_days`` and
   ``day_rollover_time`` drives a materialization whose resulting window
-  matches the non-default horizon — via BOTH the core ``materialize``
-  path and the INTEGRATION path (``_run_horizon_materialization`` +
-  ``_register_day_rollover_listener``).
+  matches the non-default horizon — via the core ``materialize`` path
+  (the integration path it used to share is gone with the integration's
+  database).
 """
 from __future__ import annotations
 
@@ -29,7 +29,6 @@ from typing import Any
 import pytest
 
 import custom_components.nestquest.core as _core_mod
-from conftest import freeze_nestquest_clock
 
 from custom_components.nestquest.const import (
     CONF_AFTERNOON_REMINDER_ENABLED,
@@ -741,7 +740,7 @@ def test_settings_module_has_no_ha_imports() -> None:
 
 
 # ---------------------------------------------------------------------------
-# Materialization over a non-default horizon: core path + integration path.
+# Materialization over a non-default horizon (core path).
 # ---------------------------------------------------------------------------
 
 
@@ -828,85 +827,3 @@ async def test_materialize_over_non_default_horizon(hass, tmp_path) -> None:
         ) == []
     finally:
         await database.close()
-
-
-async def test_integration_path_threads_settings(
-    hass, tmp_path, monkeypatch
-) -> None:
-    """The integration path threads ``settings`` through horizon_window + rollover.
-
-    ``_run_horizon_materialization`` calls
-    ``settings.horizon_window(today)`` (so the helper is real and shared,
-    not recomputed inline), and ``_register_day_rollover_listener``
-    registers at ``settings.day_rollover_hour_minute``.  This runs the
-    INTEGRATION path with ``horizon_days=3`` and
-    ``day_rollover_time='03:30'`` and asserts the resulting instance
-    window matches [today, today+3] AND the registered hour/minute are 3/30.
-    """
-    import custom_components.nestquest as nestquest
-    from custom_components.nestquest.core.dao_children import ChildrenDao
-    from custom_components.nestquest.core.dao_instances import (
-        QuestInstancesDao,
-    )
-    from custom_components.nestquest.core.quest_definitions import (
-        create_quest_definition,
-    )
-    from custom_components.nestquest.core.recurrence import (
-        RuleType,
-        ScheduleRule,
-    )
-
-    # Freeze the integration clock so "today" is deterministic (the
-    # hass fixture's config.time_zone is UTC, so 2026-03-01 12:00 UTC
-    # localizes to 2026-03-01).
-    freeze_nestquest_clock(
-        monkeypatch, datetime.datetime(2026, 3, 1, 12, 0, tzinfo=datetime.timezone.utc)
-    )
-
-    database = await _prepare(tmp_path / "nq.db", hass.async_add_executor_job)
-    try:
-        settings = NestQuestSettings(horizon_days=3, day_rollover_time="03:30")
-        today = datetime.date(2026, 3, 1)
-
-        NOW = "2026-03-01T12:00:00+00:00"
-        child = await ChildrenDao(database).create("Ada", NOW)
-        await create_quest_definition(
-            database,
-            "Daily chore",
-            ScheduleRule(
-                rule_type=RuleType.DAILY, start_date=today.isoformat()
-            ),
-            [child.id],
-            ["morning"],
-        )
-
-        # Integration path: the window comes from settings.horizon_window.
-        await nestquest._run_horizon_materialization(hass, database, settings)
-
-        end = today + datetime.timedelta(days=3)
-        records = await QuestInstancesDao(database).list_by_date_range(
-            child.id, today.isoformat(), end.isoformat()
-        )
-        dates = sorted({r.due_date for r in records})
-        assert dates == [
-            (today + datetime.timedelta(days=i)).isoformat()
-            for i in range(4)
-        ]
-        beyond = (end + datetime.timedelta(days=1)).isoformat()
-        far = (end + datetime.timedelta(days=10)).isoformat()
-        assert await QuestInstancesDao(database).list_by_date_range(
-            child.id, beyond, far
-        ) == []
-
-        # The rollover listener registers at the configured hour/minute.
-        remove = nestquest._register_day_rollover_listener(
-            hass, database, settings
-        )
-        try:
-            reg = hass.time_change.registrations[-1]
-            assert reg["hour"] == 3
-            assert reg["minute"] == 30
-        finally:
-            remove()
-    finally:
-        await database.close()

tests/test_core_snapshot.py

@@ -10,17 +10,22 @@ child's ``next_present``, a due-timed quest's ``overdue`` under a
 pinned ``now``, the custody ``cycle_day`` (> 1), and the panel payload
 dict shape (``done`` -> ``completed``, ``on_time`` passthrough, and
 ``missed`` omission) are all exercised as literals.
+
+The database is a standalone core one (the integration owns no
+database since Feature 18's DB removal); the closing round-trip pins
+that the integration's coordinator reconstructs the SAME dataclasses
+from the route's payload.
 """
 from __future__ import annotations
 
 import datetime
 from zoneinfo import ZoneInfo
 
-from conftest import wire_entry_to_registry
+from conftest import set_coordinator_client, wire_entry_to_registry
 
 from custom_components.nestquest import async_setup_entry
-from custom_components.nestquest.children import create_child
-from custom_components.nestquest.completion import complete_instance
+from custom_components.nestquest.core.children import create_child
+from custom_components.nestquest.core.completion import complete_instance
 from custom_components.nestquest.core.snapshot import (
     ChildDaySnapshot,
     NestQuestSnapshot,
@@ -28,14 +33,17 @@ from custom_components.nestquest.core.snapshot import (
     build_snapshot,
     instance_payload,
 )
-from custom_components.nestquest.dao_instances import QuestInstancesDao
-from custom_components.nestquest.dao_presence import (
+from custom_components.nestquest.core.dao_instances import QuestInstancesDao
+from custom_components.nestquest.core.dao_presence import (
     PresenceOverridesDao,
     PresenceSchedulesDao,
 )
-from custom_components.nestquest.materialize import materialize
-from custom_components.nestquest.quest_definitions import create_quest_definition
-from custom_components.nestquest.recurrence import ScheduleRule
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.materialize import materialize
+from custom_components.nestquest.core.migrations import apply_migrations
+from custom_components.nestquest.core.quest_definitions import create_quest_definition
+from custom_components.nestquest.core.recurrence import ScheduleRule
+from custom_components.nestquest.core.settings import NestQuestSettings
 
 
 async def test_instance_payload_shape_and_missed_omission() -> None:
@@ -105,7 +113,7 @@ async def test_instance_payload_shape_and_missed_omission() -> None:
     )
 
 
-async def test_build_snapshot_explicit_values(hass, make_entry, monkeypatch) -> None:
+async def test_build_snapshot_explicit_values(hass, make_entry, tmp_path) -> None:
     """The builder produces the documented shape as literals, pinned in time.
 
     Ada is AWAY today (a 2-week schedule whose absent week 0 covers today,
@@ -117,15 +125,18 @@ async def test_build_snapshot_explicit_values(hass, make_entry, monkeypatch) ->
     scheduled active child is Ada, whose 2-week cycle anchored one day
     before today puts ``cycle_day`` at 2.
     """
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    coordinator = entry.runtime_data.coordinator
-    database = entry.runtime_data.database
-    settings = entry.runtime_data.settings
+    # A standalone core database (the integration owns none): the
+    # builder and its seed run against it through the executor.
+    database = NestQuestDatabase(hass.async_add_executor_job)
+    await database.open(tmp_path / "snapshot.db")
+    await apply_migrations(database)
+    settings = NestQuestSettings()
 
-    # Single clock read for the seed/snapshot anchor (no midnight skew).
-    today = coordinator._local_now().date()
+    # Single clock read for the seed/snapshot anchor (no midnight skew);
+    # the coordinator no longer owns a clock read (the API serves the
+    # snapshot), so the test resolves the HA-local zone directly.
     time_zone = ZoneInfo(hass.config.time_zone)
+    today = datetime.datetime.now(time_zone).date()
     # Pin the build instant at 12:00 local: past Ada's 10:00 due time
     # (overdue) and before Bo's 17:00, and the completion moment for Bo.
     pinned_now = datetime.datetime(
@@ -294,13 +305,42 @@ async def test_build_snapshot_explicit_values(hass, make_entry, monkeypatch) ->
         == "missed"
     )
 
-    # REQUIRED wrapper tie-in: the coordinator's _async_update_data is a
-    # thin WRAPPER over build_snapshot, so pinning its clock to the SAME
-    # pinned_now the builder was called with must reproduce the builder's
-    # snapshot byte-for-byte.  The dataclasses are frozen, so == is a full
-    # deep compare — a wrapper that mis-passed today vs now, or stopped
-    # calling the builder, would diverge here even though the literal
-    # assertions above still pass.
-    monkeypatch.setattr(coordinator, "_local_now", lambda: pinned_now)
-    await coordinator.async_refresh()
+    # REQUIRED wrapper tie-in: since Feature 18 the coordinator's
+    # refresh polls the snapshot through its API client, so pinning the
+    # client to serve the payload of the SAME snapshot built with
+    # pinned_now must reproduce the builder's snapshot byte-for-byte.
+    # The dataclasses are frozen, so == is a full deep compare — a
+    # reconstruction that dropped or reshaped a field would diverge
+    # here even though the literal assertions above still pass.
+    class _PinnedPayloadClient:
+        async def get_snapshot(self):
+            return {
+                "today_iso": built.today_iso,
+                "cycle_day": built.cycle_day,
+                "children": [
+                    {
+                        "child_id": child.child_id,
+                        "child_name": child.child_name,
+                        "present": child.present,
+                        "next_present": child.next_present,
+                        "due_today": child.due_today,
+                        "completed_today": child.completed_today,
+                        "remaining_today": child.remaining_today,
+                        "completion_pct": child.completion_pct,
+                        "instances": instance_payload(
+                            child.instances, include_missed=False
+                        ),
+                    }
+                    for child in built.children
+                ],
+            }
+
+    entry = wire_entry_to_registry(
+        make_entry(data={"api_base_url": "http://api.test:8000", "panel_token": "tok"}),
+        hass.registry,
+    )
+    set_coordinator_client(entry, _PinnedPayloadClient())
+    assert await async_setup_entry(hass, entry) is True
+    coordinator = entry.runtime_data.coordinator
     assert coordinator.data == built
+    await database.close()

tests/test_dao_children.py

@@ -6,15 +6,15 @@ import sqlite3
 
 import pytest
 
-from custom_components.nestquest.dao_children import (
+from custom_components.nestquest.core.dao_children import (
     AdminUserRecord,
     AdminUsersDao,
     ChildRecord,
     ChildrenDao,
 )
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.schema import SCHEMA_V1_STATEMENTS
-from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.schema import SCHEMA_V1_STATEMENTS
+from custom_components.nestquest.core.migrations import apply_migrations
 
 
 def _run(coro):
@@ -504,9 +504,6 @@ def test_children_and_admin_sql_lives_only_in_dao_module() -> None:
         "tests/test_dao_rules.py",  # rules/definitions guard, own scope
         "tests/test_dao_presence.py",  # presence guard, own scope
         "tests/test_dao_instances.py",  # instances guard, own scope
-        "tests/test_startup_db.py",  # row-count probe of the children
-        # table only (proving a fresh setup loads); guard below covers
-        # everything else
     }
     sql_pattern = re.compile(
         r"(FROM|INTO|UPDATE|DELETE\s+FROM|JOIN)\s+"
@@ -558,32 +555,6 @@ def _strip_function_spans(text: str, names: set[str]) -> str:
         for number, line in enumerate(lines, start=1)
         if number not in excluded
     )
-
-
-def test_startup_db_test_file_uses_dao_elsewhere() -> None:
-    """Compensating self-scan for the startup-test exemption: outside
-    the single sanctioned COUNT(*) probe, test_startup_db.py must go
-    through the DAO for children/admin_users data access.
-    """
-    import re
-    from pathlib import Path
-
-    startup_test = Path(__file__).parent / "test_startup_db.py"
-    stripped = _strip_function_spans(
-        startup_test.read_text(),
-        {"test_setup_with_valid_file_preserves_rows"},
-    )
-    sql_pattern = re.compile(
-        r"(SELECT\s[^\"']*?FROM|INSERT\s+INTO|UPDATE|DELETE\s+FROM|"
-        r"FROM|JOIN)\s+[`'\"]*(\[)?(children|admin_users)\b",
-        re.IGNORECASE,
-    )
-    assert sql_pattern.search(stripped) is None, (
-        "test_startup_db.py must go through the DAO for these tables "
-        "outside its sanctioned row-count probe"
-    )
-
-
 def test_dao_matrix_test_file_raw_probes_are_only_constraint_probes() -> None:
     """Compensating self-scan for the matrix-file exemption, structurally
     exact: parse the two sanctioned functions' ASTs and require that

tests/test_dao_instances.py

@@ -7,16 +7,16 @@ import sqlite3
 
 import pytest
 
-from custom_components.nestquest.dao_children import ChildrenDao
-from custom_components.nestquest.dao_instances import (
+from custom_components.nestquest.core.dao_children import ChildrenDao
+from custom_components.nestquest.core.dao_instances import (
     CompletionEventRecord,
     CompletionEventsDao,
     QuestInstanceRecord,
     QuestInstancesDao,
 )
-from custom_components.nestquest.dao_rules import ScheduleRulesDao, QuestDefinitionsDao
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.core.dao_rules import ScheduleRulesDao, QuestDefinitionsDao
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
 
 
 def _run(coro):

tests/test_dao_matrix.py

@@ -21,24 +21,24 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from custom_components.nestquest.dao_children import (
+from custom_components.nestquest.core.dao_children import (
     AdminUsersDao,
     ChildrenDao,
 )
-from custom_components.nestquest.dao_instances import (
+from custom_components.nestquest.core.dao_instances import (
     CompletionEventsDao,
     QuestInstancesDao,
 )
-from custom_components.nestquest.dao_presence import (
+from custom_components.nestquest.core.dao_presence import (
     PresenceOverridesDao,
     PresenceSchedulesDao,
 )
-from custom_components.nestquest.dao_rules import (
+from custom_components.nestquest.core.dao_rules import (
     ScheduleRulesDao,
     QuestDefinitionsDao,
 )
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
 
 
 def _run(coro):

tests/test_dao_presence.py

@@ -6,15 +6,15 @@ import sqlite3
 
 import pytest
 
-from custom_components.nestquest.dao_children import ChildrenDao
-from custom_components.nestquest.dao_presence import (
+from custom_components.nestquest.core.dao_children import ChildrenDao
+from custom_components.nestquest.core.dao_presence import (
     PresenceOverrideRecord,
     PresenceOverridesDao,
     PresenceScheduleRecord,
     PresenceSchedulesDao,
 )
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
 
 
 def _run(coro):
@@ -741,12 +741,12 @@ def test_override_create_racing_conflicts_serialize(tmp_path) -> None:
     from unittest.mock import MagicMock
 
     async def _main():
-        from custom_components.nestquest.dao_children import ChildrenDao
-        from custom_components.nestquest.dao_presence import (
+        from custom_components.nestquest.core.dao_children import ChildrenDao
+        from custom_components.nestquest.core.dao_presence import (
             PresenceOverridesDao,
         )
-        from custom_components.nestquest.db import NestQuestDatabase
-        from custom_components.nestquest.migrations import apply_migrations
+        from custom_components.nestquest.core.db import NestQuestDatabase
+        from custom_components.nestquest.core.migrations import apply_migrations
 
         armed = {"active": False, "gated": False}
         gate_open = asyncio_module.Event()

tests/test_dao_rules.py

@@ -6,8 +6,8 @@ import sqlite3
 
 import pytest
 
-from custom_components.nestquest.dao_children import ChildrenDao
-from custom_components.nestquest.dao_rules import (
+from custom_components.nestquest.core.dao_children import ChildrenDao
+from custom_components.nestquest.core.dao_rules import (
     ScheduleRuleRecord,
     ScheduleRuleStorage,
     ScheduleRulesDao,
@@ -17,9 +17,9 @@ from custom_components.nestquest.dao_rules import (
     schedule_rule_from_storage,
     schedule_rule_to_storage,
 )
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
-from custom_components.nestquest.recurrence import (
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
+from custom_components.nestquest.core.recurrence import (
     RuleType,
     RuleValidationError,
     ScheduleRule,
@@ -341,7 +341,7 @@ def test_rule_delete_concurrent_with_definition_create_is_safe(
                 # delete task has been scheduled, so the create holds
                 # the connection lock while the delete queues behind
                 # it — then the create proceeds and wins.
-                import custom_components.nestquest.dao_rules as dao_rules
+                import custom_components.nestquest.core.dao_rules as dao_rules
 
                 original_validate = (
                     dao_rules.QuestDefinitionsDao._validate_rule_exists

tests/test_db.py

@@ -14,7 +14,7 @@ import pytest
 from conftest import executor_for, make_hass
 
 import custom_components.nestquest.core.db as db_module
-from custom_components.nestquest.db import NestQuestDatabase
+from custom_components.nestquest.core.db import NestQuestDatabase
 
 
 def _run(coro):
@@ -933,68 +933,3 @@ def test_execute_many_exposes_rowcount(tmp_path) -> None:
 
 
 # ---------------------------------------------------------------------------
-# Lifecycle wiring: opened once per entry, closed on unload
-# ---------------------------------------------------------------------------
-
-
-async def test_setup_entry_opens_database_in_runtime_data(hass, make_entry) -> None:
-    from conftest import wire_entry_to_registry
-
-    from custom_components.nestquest import async_setup_entry, async_unload_entry
-
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    runtime = entry.runtime_data
-    assert runtime.database is not None
-    assert runtime.database.connected is True
-    await async_unload_entry(hass, entry)
-
-
-async def test_unload_entry_closes_database(hass, make_entry) -> None:
-    from conftest import wire_entry_to_registry
-
-    from custom_components.nestquest import async_setup_entry, async_unload_entry
-
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    await async_setup_entry(hass, entry)
-    database = entry.runtime_data.database
-    assert database.connected is True
-    assert await async_unload_entry(hass, entry) is True
-    assert database.connected is False
-    with pytest.raises(RuntimeError, match="closed"):
-        await database.fetch_one("SELECT 1")
-
-
-async def test_second_setup_does_not_open_second_connection(hass, make_entry) -> None:
-    from conftest import wire_entry_to_registry
-
-    from custom_components.nestquest import async_setup_entry, async_unload_entry
-
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    await async_setup_entry(hass, entry)
-    first = entry.runtime_data.database
-
-    await async_setup_entry(hass, entry)
-    second = entry.runtime_data.database
-
-    assert first is second
-    assert first.connected is True
-    await async_unload_entry(hass, entry)
-
-
-async def test_setup_unload_cycles_reopen_fresh_connection(hass, make_entry) -> None:
-    from conftest import wire_entry_to_registry
-
-    from custom_components.nestquest import async_setup_entry, async_unload_entry
-
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    seen: list[NestQuestDatabase] = []
-    for _ in range(3):
-        await async_setup_entry(hass, entry)
-        runtime = entry.runtime_data
-        assert runtime.database.connected is True
-        seen.append(runtime.database)
-        await async_unload_entry(hass, entry)
-        assert runtime.database.connected is False
-    assert len(set(seen)) == 3
-    assert hass.data == {}

tests/test_entity_lifecycle.py

@@ -1,24 +1,16 @@
-"""Entity lifecycle across child add/deactivate/reactivate (Feature 10, task 8)."""
+"""Entity lifecycle across child add/deactivate/reactivate (Feature 10, task 8).
+
+The household state the entities mirror comes from the API service's
+panel route, so a deactivate/reactivate/add is scripted as a payload
+change served by :class:`conftest.StubSnapshotClient`; the reload
+(unload + setup) re-polls it, exactly as production does.
+"""
 from __future__ import annotations
 
-import datetime
-
-from conftest import wire_entry_to_registry
+from conftest import StubSnapshotClient, set_coordinator_client, wire_entry_to_registry
 
 from custom_components.nestquest import async_setup_entry, async_unload_entry
-from custom_components.nestquest.children import (
-    create_child,
-    list_children,
-    set_child_active,
-)
-from custom_components.nestquest.const import DOMAIN
-from custom_components.nestquest.materialize import materialize
-from custom_components.nestquest.quest_definitions import (
-    create_quest_definition,
-)
-from custom_components.nestquest.recurrence import ScheduleRule
 
-SEED_HORIZON_DAYS = 3
 PER_CHILD_KINDS = (
     "quests_due_today",
     "quests_completed_today",
@@ -34,6 +26,78 @@ HOUSEHOLD_UNIQUE_IDS = (
     "nestquest_cycle_day",
 )
 
+ADA = 1
+BO = 2
+CORY_ID = 4
+
+
+def _child(child_id: int, name: str, *, present=True, instances=()):
+    completed = sum(1 for i in instances if i["state"] == "completed")
+    due = len(instances)
+    return {
+        "child_id": child_id,
+        "child_name": name,
+        "present": present,
+        "next_present": None,
+        "due_today": due,
+        "completed_today": completed,
+        "remaining_today": due - completed,
+        "completion_pct": 100 if due == 0 else round(completed / due * 100),
+        "instances": list(instances),
+    }
+
+
+def _instance(instance_id: int, child_id: int, *, state="open") -> dict:
+    return {
+        "id": instance_id,
+        "definition_id": 3,
+        "child_id": child_id,
+        "title": "Brush teeth",
+        "icon": "🦷",
+        "window": "morning",
+        "due_time": "08:00",
+        "state": state,
+        "overdue": False,
+        "completed_at": None if state == "open" else "2026-09-23T07:55:00+00:00",
+        "on_time": None if state == "open" else True,
+    }
+
+
+def _payload(children) -> dict:
+    return {
+        "today_iso": "2026-09-23",
+        "cycle_day": 0,
+        "children": list(children),
+    }
+
+
+#: The full household (Ada + Bo, one daily quest each) and the states
+#: the lifecycle walks through: Bo deactivated, reactivated, completed.
+_BOTH = _payload(
+    [
+        _child(ADA, "Ada", instances=[_instance(7, ADA)]),
+        _child(BO, "Bo", instances=[_instance(8, BO)]),
+    ]
+)
+_BO_GONE = _payload([_child(ADA, "Ada", instances=[_instance(7, ADA)])])
+_BO_DONE = _payload(
+    [
+        _child(ADA, "Ada", instances=[_instance(7, ADA)]),
+        _child(BO, "Bo", instances=[_instance(8, BO, state="completed")]),
+    ]
+)
+_ADA_ONLY = _payload([_child(ADA, "Ada", instances=[_instance(7, ADA)])])
+_ADA_AND_CORY = _payload(
+    [
+        _child(ADA, "Ada", instances=[_instance(7, ADA)]),
+        _child(CORY_ID, "Cory"),
+    ]
+)
+
+
+def _child_unique_ids(child_id: int) -> set[str]:
+    return {f"nestquest_child_{child_id}_{kind}" for kind in PER_CHILD_KINDS}
+
 
 async def _reload(hass, entry) -> None:
     """Unload then set up: the harness's restart/reload equivalent."""
@@ -41,46 +105,36 @@ async def _reload(hass, entry) -> None:
     assert await async_setup_entry(hass, entry) is True
 
 
-def _child_unique_ids(child_id: int) -> set[str]:
-    return {f"nestquest_child_{child_id}_{kind}" for kind in PER_CHILD_KINDS}
-
-
-async def _setup_and_seed(hass, make_entry):
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    database = entry.runtime_data.database
-    ada = await create_child(database, "Ada")
-    bo = await create_child(database, "Bo")
-    today = datetime.date.today()
-    await create_quest_definition(
-        database,
-        "Brush teeth",
-        ScheduleRule.from_dict(
-            {"rule_type": "daily", "start_date": today.isoformat()}
+async def _setup_with_household(hass, make_entry, *payloads):
+    """Set up the entry with a scripted, ordered snapshot history."""
+    entry = wire_entry_to_registry(
+        make_entry(
+            data={"api_base_url": "http://api.test:8000", "panel_token": "tok"}
         ),
-        [ada.id, bo.id],
-        ["morning"],
+        hass.registry,
     )
-    end = (today + datetime.timedelta(days=SEED_HORIZON_DAYS)).isoformat()
-    await materialize(database, today.isoformat(), end, today=today)
-    await entry.runtime_data.coordinator.async_refresh()
-    return entry, ada, bo
+    client = set_coordinator_client(entry, StubSnapshotClient(*payloads))
+    assert await async_setup_entry(hass, entry) is True
+    return entry, entry.runtime_data.coordinator, client
 
 
 async def test_deactivated_child_entities_removed_on_reload(
     hass, make_entry
 ) -> None:
-    entry, ada, bo = await _setup_and_seed(hass, make_entry)
-    assert _child_unique_ids(ada.id) <= set(hass.entities)
-    assert _child_unique_ids(bo.id) <= set(hass.entities)
+    """A child absent from the API's snapshot loses its entities on
+    reload; the surviving child's entities are untouched."""
+    entry, _coordinator, _client = await _setup_with_household(
+        hass, make_entry, _BOTH, _BO_GONE
+    )
+    assert _child_unique_ids(ADA) <= set(hass.entities)
+    assert _child_unique_ids(BO) <= set(hass.entities)
 
-    await set_child_active(entry.runtime_data.database, bo.id, False)
     await _reload(hass, entry)
 
-    assert _child_unique_ids(ada.id) <= set(hass.entities), (
+    assert _child_unique_ids(ADA) <= set(hass.entities), (
         "the surviving child's entities must be untouched"
     )
-    assert not (_child_unique_ids(bo.id) & set(hass.entities)), (
+    assert not (_child_unique_ids(BO) & set(hass.entities)), (
         "the deactivated child's entities must be gone after reload"
     )
 
@@ -88,100 +142,61 @@ async def test_deactivated_child_entities_removed_on_reload(
 async def test_reactivation_restores_entities_with_original_unique_ids(
     hass, make_entry
 ) -> None:
-    entry, ada, bo = await _setup_and_seed(hass, make_entry)
-    original = _child_unique_ids(bo.id)
-    await set_child_active(entry.runtime_data.database, bo.id, False)
+    original = _child_unique_ids(BO)
+    entry, _coordinator, _client = await _setup_with_household(
+        hass, make_entry, _BOTH, _BO_GONE, _BOTH
+    )
     await _reload(hass, entry)
     assert not (original & set(hass.entities))
 
-    await set_child_active(entry.runtime_data.database, bo.id, True)
     await _reload(hass, entry)
 
     assert original <= set(hass.entities), (
         "reactivation must restore the exact original unique_ids"
     )
-    bo_due = hass.entities[f"nestquest_child_{bo.id}_quests_due_today"]
+    bo_due = hass.entities[f"nestquest_child_{BO}_quests_due_today"]
     assert bo_due.native_value == 1, "restored entities carry live state"
 
 
 async def test_new_child_gets_entities_without_disturbing_existing(
     hass, make_entry
 ) -> None:
-    entry, ada, bo = await _setup_and_seed(hass, make_entry)
-    before_ada = set(hass.entities) & _child_unique_ids(ada.id)
+    """A child ADDED to the API's snapshot gains its entities on
+    reload; the existing children's entities are untouched."""
+    entry, _coordinator, _client = await _setup_with_household(
+        hass, make_entry, _ADA_ONLY, _ADA_AND_CORY
+    )
+    before_ada = set(hass.entities) & _child_unique_ids(ADA)
 
-    cory = await create_child(entry.runtime_data.database, "Cory")
     await _reload(hass, entry)
 
     assert before_ada <= set(hass.entities), "existing entities untouched"
-    assert _child_unique_ids(cory.id) <= set(hass.entities), (
+    assert _child_unique_ids(CORY_ID) <= set(hass.entities), (
         "the new child's entities appear after reload"
     )
-    assert hass.entities[f"nestquest_child_{cory.id}_quests_due_today"].native_value == 0
+    assert hass.entities[
+        f"nestquest_child_{CORY_ID}_quests_due_today"
+    ].native_value == 0
 
 
 async def test_restart_equivalent_restores_all_entity_states(
     hass, make_entry
 ) -> None:
     """Unload + setup (the restart equivalent) restores every active
-    child's entities with correct states and the household rollups."""
-    from custom_components.nestquest.completion import complete_instance
-
-    entry, ada, bo = await _setup_and_seed(hass, make_entry)
-    coordinator = entry.runtime_data.coordinator
-    snapshot_ada = next(
-        child
-        for child in coordinator.data.children
-        if child.child_id == ada.id
+    child's entities with the API's current states and the household
+    rollups."""
+    entry, _coordinator, _client = await _setup_with_household(
+        hass, make_entry, _BOTH, _BO_DONE
     )
-    await complete_instance(
-        entry.runtime_data.database,
-        snapshot_ada.instances[0].instance_id,
-        actor_source="panel",
-        actor_child_id=ada.id,
-    )
-    await coordinator.async_refresh()
-    assert hass.entities[
-        f"nestquest_child_{ada.id}_quests_completed_today"
-    ].native_value == 1
-
     await _reload(hass, entry)
 
     assert hass.entities[
-        f"nestquest_child_{ada.id}_quests_completed_today"
-    ].native_value == 1, "completed count survives the restart"
-    assert hass.entities[
-        f"nestquest_child_{bo.id}_quests_completed_today"
+        f"nestquest_child_{ADA}_quests_completed_today"
     ].native_value == 0
+    assert hass.entities[
+        f"nestquest_child_{BO}_quests_completed_today"
+    ].native_value == 1, "the API's recorded completion survives the restart"
     assert set(HOUSEHOLD_UNIQUE_IDS) <= set(hass.entities)
     assert hass.entities[
         "nestquest_household_quests_completed_today"
     ].native_value == 1
-
-
-async def test_unload_shuts_coordinator_before_closing_database(
-    hass, make_entry
-) -> None:
-    """The coordinator's listeners are cleared while the database is
-    still connected: a scheduled refresh must never race the close."""
-    entry = wire_entry_to_registry(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    coordinator = entry.runtime_data.coordinator
-    database = entry.runtime_data.database
-    seen_connected = []
-
-    async def _probe_shutdown():
-        seen_connected.append(database.connected)
-
-    original_close = database.close
-
-    async def _recording_close():
-        seen_connected.append("closing")
-        await original_close()
-
-    coordinator.async_shutdown = _probe_shutdown
-    database.close = _recording_close
-    assert await async_unload_entry(hass, entry) is True
-    assert seen_connected == [True, "closing"], (
-        "coordinator shutdown must precede the database close"
-    )

tests/test_entity_matrix.py

@@ -2,72 +2,156 @@
 
 One fixture drives every assertion the done-condition names: correct
 values for every sensor and binary sensor (including the zero-quest
-child and the 255-character state limit), the three events firing
-exactly once with schema-valid payloads, the instances payload
-omitting missed instances while admin_instances includes them, and no
-entities for an inactive child.  The per-task test files cover each
-behavior in depth; this file is the single pass that proves them all
-against ONE fixture, so a regression in any contract fails here too.
+child and the 255-character state limit), the completed/uncompleted/
+day-complete events re-fired exactly once from the API's SSE frames,
+the panel payload omitting missed instances while admin_instances
+equals it, and no entities for a child the API does not report.  The
+per-task test files cover each behavior in depth; this file is the
+single pass that proves them all against ONE fixture, so a regression
+in any contract fails here too.
+
+Since the DB removal the household state and every transition come
+from the API service, so the fixture scripts the panel route's
+payloads and completion surface (:class:`conftest.ScriptedPanelClient`)
+and delivers the transition frames through the SSE subscription — the
+production event path.
 """
 from __future__ import annotations
 
-import datetime
 import re
 
-from conftest import wire_entry_to_registry
+from conftest import ScriptedPanelClient, set_coordinator_client, wire_entry_to_registry
 
 from custom_components.nestquest import async_setup_entry
-from custom_components.nestquest.children import (
-    create_child,
-    list_children,
-    set_child_active,
-)
-from custom_components.nestquest.completion import derive_state
 from custom_components.nestquest.const import (
-    CONF_ADMIN_USER_IDS,
     DOMAIN,
     EVENT_CHILD_DAY_COMPLETE,
     EVENT_QUEST_COMPLETED,
     EVENT_QUEST_UNCOMPLETED,
     SERVICE_COMPLETE_QUEST,
-    SERVICE_UNCOMPLETE_QUEST,
 )
-from custom_components.nestquest.dao_instances import QuestInstancesDao
-from custom_components.nestquest.materialize import materialize
-from custom_components.nestquest.quest_definitions import (
-    create_quest_definition,
-)
-from custom_components.nestquest.recurrence import ScheduleRule
 
 _TIMESTAMP = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$")
 
+ADA = 1
+BO = 2
+CORY = 3
+
+_OCCURRED = "2026-09-23T07:55:00+00:00"
+
+
+def _instance(instance_id: int, child_id: int, *, window="morning", state="open"):
+    return {
+        "id": instance_id,
+        "definition_id": 3,
+        "child_id": child_id,
+        "title": "Brush teeth",
+        "icon": "🦷",
+        "window": window,
+        "due_time": "08:00" if window == "morning" else "19:00",
+        "state": state,
+        "overdue": False,
+        "completed_at": None if state == "open" else _OCCURRED,
+        "on_time": None if state == "open" else True,
+    }
+
+
+def _child(child_id: int, name: str, instances=()):
+    completed = sum(1 for i in instances if i["state"] == "completed")
+    due = len(instances)
+    return {
+        "child_id": child_id,
+        "child_name": name,
+        "present": True,
+        "next_present": None,
+        "due_today": due,
+        "completed_today": completed,
+        "remaining_today": due - completed,
+        "completion_pct": 100 if due == 0 else round(completed / due * 100),
+        "instances": list(instances),
+    }
+
+
+def _payload(children, cycle_day=0) -> dict:
+    return {
+        "today_iso": "2026-09-23",
+        "cycle_day": cycle_day,
+        "children": list(children),
+    }
+
+
+def _completed_frame(instance_id: int, child_id: int, child_name: str, window: str):
+    """The completed-event frame the API service publishes for one
+    panel completion (the day-complete rule is the API's; its payload
+    shape is pinned by tests/test_api_sse.py on the production
+    plane)."""
+    return (
+        EVENT_QUEST_COMPLETED,
+        {
+            "child_id": child_id,
+            "child_name": child_name,
+            "instance_id": instance_id,
+            "quest_title": "Brush teeth",
+            "window": window,
+            "due_date": "2026-09-23",
+            "due_time": "08:00" if window == "morning" else "19:00",
+            "occurred_at": _OCCURRED,
+            "was_on_time": True,
+        },
+    )
+
+
+def _day_complete_frame(child_id: int, child_name: str):
+    """The day-complete frame the API publishes once a child's day
+    clears (after the LAST completion of the day)."""
+    return (
+        EVENT_CHILD_DAY_COMPLETE,
+        {
+            "child_id": child_id,
+            "child_name": child_name,
+            "quests_due": 2,
+            "quests_completed": 2,
+            "occurred_at": _OCCURRED,
+        },
+    )
+
 
 async def _fixture(hass, make_entry):
-    """Two quest children, one zero-quest child, one inactive child."""
+    """Two quest children, one zero-quest child; the inactive child is
+    simply ABSENT from the API's snapshot (the API only reports active
+    children, so the integration can never create its entities)."""
     entry = wire_entry_to_registry(
-        make_entry(data={CONF_ADMIN_USER_IDS: ["admin-1"]}), hass.registry
-    )
-    assert await async_setup_entry(hass, entry) is True
-    database = entry.runtime_data.database
-    ada = await create_child(database, "Ada")
-    bo = await create_child(database, "Bo")
-    cory = await create_child(database, "Cory")
-    ghost = await create_child(database, "Ghost")
-    await set_child_active(database, ghost.id, False)
-    today = datetime.date.today()
-    await create_quest_definition(
-        database,
-        "Brush teeth",
-        ScheduleRule.from_dict(
-            {"rule_type": "daily", "start_date": today.isoformat()}
+        make_entry(
+            data={"api_base_url": "http://api.test:8000", "panel_token": "tok"}
         ),
-        [ada.id, bo.id],
-        ["morning", "evening"],
+        hass.registry,
     )
-    end = (today + datetime.timedelta(days=3)).isoformat()
-    await materialize(database, today.isoformat(), end, today=today)
-    await entry.runtime_data.coordinator.async_refresh()
-    return entry, (ada, bo, cory, ghost)
+    client = ScriptedPanelClient(
+        _payload(
+            [
+                _child(ADA, "Ada", [_instance(7, ADA), _instance(8, ADA, window="evening")]),
+                _child(BO, "Bo", [_instance(9, BO), _instance(10, BO, window="evening")]),
+                _child(CORY, "Cory"),
+            ]
+        ),
+        _payload(
+            [
+                _child(
+                    ADA,
+                    "Ada",
+                    [
+                        _instance(7, ADA, state="completed"),
+                        _instance(8, ADA, window="evening", state="completed"),
+                    ],
+                ),
+                _child(BO, "Bo", [_instance(9, BO), _instance(10, BO, window="evening")]),
+                _child(CORY, "Cory"),
+            ]
+        ),
+    )
+    set_coordinator_client(entry, client)
+    assert await async_setup_entry(hass, entry) is True
+    return entry, client
 
 
 def _sensor(hass, child_id, kind):
@@ -75,11 +159,11 @@ def _sensor(hass, child_id, kind):
 
 
 async def test_entity_and_event_matrix(hass, make_entry) -> None:
-    entry, (ada, bo, cory, ghost) = await _fixture(hass, make_entry)
+    entry, client = await _fixture(hass, make_entry)
     coordinator = entry.runtime_data.coordinator
 
-    # --- Every active child has the full entity set; the inactive
-    # child has none.
+    # --- Every reported child has the full entity set; the child the
+    # API does not report has none.
     kinds = (
         "quests_due_today",
         "quests_completed_today",
@@ -89,36 +173,37 @@ async def test_entity_and_event_matrix(hass, make_entry) -> None:
         "all_done",
         "present_today",
     )
-    for child in (ada, bo, cory):
+    ghost_id = 99
+    for child in (ADA, BO, CORY):
         for kind in kinds:
-            assert f"{DOMAIN}_child_{child.id}_{kind}" in hass.entities, kind
+            assert f"{DOMAIN}_child_{child}_{kind}" in hass.entities, kind
     for kind in kinds:
-        assert f"{DOMAIN}_child_{ghost.id}_{kind}" not in hass.entities, (
-            "inactive children must have no entities"
+        assert f"{DOMAIN}_child_{ghost_id}_{kind}" not in hass.entities, (
+            "children absent from the API snapshot must have no entities"
         )
 
     # --- Correct values against the fixture: Ada and Bo owe two
     # quests (morning + evening), Cory owes none and is still 100%.
-    for child in (ada, bo):
-        assert _sensor(hass, child.id, "quests_due_today").native_value == 2
+    for child in (ADA, BO):
+        assert _sensor(hass, child, "quests_due_today").native_value == 2
         assert (
-            _sensor(hass, child.id, "quests_completed_today").native_value == 0
+            _sensor(hass, child, "quests_completed_today").native_value == 0
         )
         assert (
-            _sensor(hass, child.id, "quests_remaining_today").native_value == 2
+            _sensor(hass, child, "quests_remaining_today").native_value == 2
         )
         assert (
-            _sensor(hass, child.id, "completion_pct_today").native_value == 0
+            _sensor(hass, child, "completion_pct_today").native_value == 0
         )
-        assert _sensor(hass, child.id, "next_quest").native_value == (
+        assert _sensor(hass, child, "next_quest").native_value == (
             "Brush teeth"
         )
-        assert _sensor(hass, child.id, "all_done").is_on is False
-        assert _sensor(hass, child.id, "present_today").is_on is True
-    assert _sensor(hass, cory.id, "quests_due_today").native_value == 0
-    assert _sensor(hass, cory.id, "completion_pct_today").native_value == 100
-    assert _sensor(hass, cory.id, "all_done").is_on is False
-    assert _sensor(hass, cory.id, "next_quest").native_value == "none"
+        assert _sensor(hass, child, "all_done").is_on is False
+        assert _sensor(hass, child, "present_today").is_on is True
+    assert _sensor(hass, CORY, "quests_due_today").native_value == 0
+    assert _sensor(hass, CORY, "completion_pct_today").native_value == 100
+    assert _sensor(hass, CORY, "all_done").is_on is False
+    assert _sensor(hass, CORY, "next_quest").native_value == "none"
 
     # --- Household rollups equal the per-child sums.
     assert hass.entities[
@@ -138,22 +223,31 @@ async def test_entity_and_event_matrix(hass, make_entry) -> None:
         ), unique_id
 
     # --- Completing both of Ada's quests fires the events exactly
-    # once each and flips her entities immediately.
-    instances = await QuestInstancesDao(
-        entry.runtime_data.database
-    ).list_by_date_range(
-        ada.id, datetime.date.today().isoformat(), datetime.date.today().isoformat()
+    # once each and flips her entities immediately.  The transition
+    # events arrive over the API's SSE stream (the subscription
+    # re-fires them), never from the service handler.
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {"instance_id": 7, "actor": "panel", "actor_child_id": ADA},
     )
-    for instance in instances:
-        await hass.services.call(
-            DOMAIN,
-            SERVICE_COMPLETE_QUEST,
-            {
-                "instance_id": instance.id,
-                "actor": "panel",
-                "actor_child_id": ada.id,
-            },
-        )
+    await hass.services.call(
+        DOMAIN,
+        SERVICE_COMPLETE_QUEST,
+        {"instance_id": 8, "actor": "panel", "actor_child_id": ADA},
+    )
+    client.published_frames.extend(
+        [
+            _completed_frame(7, ADA, "Ada", "morning"),
+            _completed_frame(8, ADA, "Ada", "evening"),
+            # The API publishes the day-complete frame only when the
+            # day clears — after the LAST completion of the day.
+            _day_complete_frame(ADA, "Ada"),
+        ]
+    )
+    from conftest import refire_api_transitions
+
+    await refire_api_transitions(hass, entry, client)
     assert len(hass.bus.fired(EVENT_QUEST_COMPLETED)) == 2
     for payload in hass.bus.fired(EVENT_QUEST_COMPLETED):
         assert _TIMESTAMP.match(payload["occurred_at"])
@@ -162,53 +256,53 @@ async def test_entity_and_event_matrix(hass, make_entry) -> None:
         assert payload["quest_title"] == "Brush teeth"
         assert isinstance(payload["instance_id"], int)
     assert len(hass.bus.fired(EVENT_CHILD_DAY_COMPLETE)) == 1
-    assert _sensor(hass, ada.id, "all_done").is_on is True
-    assert _sensor(hass, ada.id, "quests_remaining_today").native_value == 0
+    # The next scripted snapshot reflects both completions.
+    await coordinator.async_refresh()
+    assert _sensor(hass, ADA, "all_done").is_on is True
+    assert _sensor(hass, ADA, "quests_remaining_today").native_value == 0
     assert (
-        _sensor(hass, ada.id, "completion_pct_today").native_value == 100
+        _sensor(hass, ADA, "completion_pct_today").native_value == 100
     )
 
-    # --- Reversing one quest fires the uncompleted event exactly once
-    # and restores the owed counts.
-    await hass.services.call(
-        DOMAIN,
-        SERVICE_UNCOMPLETE_QUEST,
-        {"instance_id": instances[0].id, "actor": "user"},
-        context={"user_id": "admin-1"},
+    # --- Reversing one quest fires the uncompleted event exactly once.
+    #  The HA ``uncomplete_quest`` service is gone (the API service's
+    # admin route is the reversal path), so the reversal is the API's:
+    # it publishes the uncompleted frame and the integration re-fires
+    # it; the coordinator's next poll picks the restored counts up.
+    client.published_frames.append(
+        (
+            EVENT_QUEST_UNCOMPLETED,
+            {
+                "child_id": ADA,
+                "child_name": "Ada",
+                "instance_id": 7,
+                "quest_title": "Brush teeth",
+                "window": "morning",
+                "due_date": "2026-09-23",
+                "due_time": "08:00",
+                "occurred_at": _OCCURRED,
+            },
+        )
     )
+    await refire_api_transitions(hass, entry, client)
     assert len(hass.bus.fired(EVENT_QUEST_UNCOMPLETED)) == 1
-    assert _sensor(hass, ada.id, "all_done").is_on is False
-    assert _sensor(hass, ada.id, "quests_remaining_today").native_value == 1
 
-    # --- The instances payload omits missed instances while
-    # admin_instances includes them (D-009): pin the derive clock
-    # forward in the TEST ONLY so today's open instances read missed.
-    original_refresh = coordinator._async_update_data
-
-    async def _future_dated_refresh():
-        import custom_components.nestquest.core.snapshot as snapshot_module
-
-        real_derive = snapshot_module.derive_state
-
-        def _derive(instance, latest, today):
-            return real_derive(instance, latest, today + datetime.timedelta(days=1))
-
-        snapshot_module.derive_state = _derive
-        try:
-            return await original_refresh()
-        finally:
-            snapshot_module.derive_state = real_derive
-
-    coordinator._async_update_data = _future_dated_refresh
+    # --- The panel payload omits missed instances (D-009) — the API
+    # panel route omits missed rows ENTIRELY, so admin_instances
+    # cannot carry them either (the admin surface for missed quests is
+    # the PWA, reading the API directly).  A snapshot built from the
+    # payload can only ever hold open and completed rows: pin that
+    # the payload round-trips verbatim.
     await coordinator.async_refresh()
-    attributes = _sensor(hass, bo.id, "quests_due_today").extra_state_attributes
-    assert attributes["instances"] == [], "panel payload omits missed"
-    assert len(attributes["admin_instances"]) == 2
-    assert all(
-        entry["state"] == "missed" for entry in attributes["admin_instances"]
+    attributes = _sensor(hass, BO, "quests_due_today").extra_state_attributes
+    assert attributes["instances"] == [
+        dict(_instance(9, BO)),
+        dict(_instance(10, BO, window="evening")),
+    ], "the panel payload round-trips the API's open rows verbatim"
+    assert attributes["admin_instances"] == attributes["instances"], (
+        "the API payload omits missed rows, so the admin payload "
+        "carries none either (the PWA is the admin surface now)"
     )
-    coordinator._async_update_data = original_refresh
-    await coordinator.async_refresh()
 
 
 async def test_payload_schema_matches_the_documented_contract(
@@ -216,21 +310,16 @@ async def test_payload_schema_matches_the_documented_contract(
 ) -> None:
     """Every fired payload carries the documented fields with the
     documented types."""
-    entry, (ada, _bo, _cory, _ghost) = await _fixture(hass, make_entry)
-    instances = await QuestInstancesDao(
-        entry.runtime_data.database
-    ).list_by_date_range(
-        ada.id, datetime.date.today().isoformat(), datetime.date.today().isoformat()
-    )
+    entry, client = await _fixture(hass, make_entry)
     await hass.services.call(
         DOMAIN,
         SERVICE_COMPLETE_QUEST,
-        {
-            "instance_id": instances[0].id,
-            "actor": "panel",
-            "actor_child_id": ada.id,
-        },
+        {"instance_id": 7, "actor": "panel", "actor_child_id": ADA},
     )
+    client.published_frames.append(_completed_frame(7, ADA, "Ada", "morning"))
+    from conftest import refire_api_transitions
+
+    await refire_api_transitions(hass, entry, client)
     payload = hass.bus.fired(EVENT_QUEST_COMPLETED)[0]
     for key, check in (
         ("child_id", lambda v: isinstance(v, int)),

tests/test_lifecycle.py

@@ -9,27 +9,103 @@ from conftest import make_config_entry, make_hass, wire_entry_to_registry
 
 from custom_components.nestquest import DOMAIN, async_setup_entry, async_unload_entry
 from custom_components.nestquest.const import (
-    CONF_ADMIN_USER_IDS,
-    CONF_DAY_ROLLOVER_TIME,
-    CONF_HORIZON_DAYS,
-    CONF_MORNING_SUMMARY_TIME,
-    DEFAULT_HORIZON_DAYS,
-    SERVICE_REGENERATE,
     DOMAIN as DOMAIN_CONST,
+    SERVICE_COMPLETE_QUEST,
+)
+from custom_components.nestquest.dashboard import (
+    DASHBOARD_STRATEGY_TYPE,
+    DASHBOARD_URL_PATH,
+    async_register_dashboard,
 )
-
-ADMIN_ID = "admin-1"
-ADMIN_CTX = {"user_id": ADMIN_ID}
-
-
-def _admin_data():
-    return {CONF_ADMIN_USER_IDS: [ADMIN_ID]}
 
 
 def _wire(entry, registry):
     return wire_entry_to_registry(entry, registry)
 
 
+class FakeDashboardStore:
+    """Stand-in for a per-dashboard CONTENT manager (LovelaceStorage).
+
+    In the real API the dashboard CONFIG (the strategy reference) is
+    saved through THIS manager's ``async_save``, NOT through the
+    metadata collection — so every strategy-save assertion reads here.
+    """
+
+    def __init__(self) -> None:
+        self.saved: list[dict] = []
+        self.config: dict | None = None
+
+    async def async_save(self, config: dict) -> None:
+        self.saved.append(dict(config))
+        self.config = dict(config)
+
+
+class FakeDashboardsCollection:
+    """Stand-in mirroring the REAL Lovelace dashboards API shapes.
+
+    Faithful to ``homeassistant/components/lovelace`` +
+    ``helpers/collection.py``: ``async_items()`` is a SYNC ``@callback``
+    (ObservableCollection.async_items returns list(data.values())),
+    ``async_create_item`` IS async, and — mirroring lovelace's
+    ``storage_dashboard_changed`` listener — a successful create
+    registers a fresh CONTENT manager under
+    ``hass.data["lovelace"]["dashboards"][url_path]``, which is where
+    the dashboard config is then saved.  Records ``async_create_item``
+    calls so tests can assert exactly what the setup path registered —
+    and that a reload registers nothing more.
+    """
+
+    def __init__(self, hass, items=None) -> None:
+        self.hass = hass
+        self.items = list(items or [])
+        self.created: list[dict] = []
+        #: url_path -> content manager, mirroring the real listener's
+        # registrations (pre-existing items included).
+        self.stores: dict[str, FakeDashboardStore] = {}
+
+    def async_items(self):
+        """SYNC, like the real ``ObservableCollection.async_items``."""
+        return list(self.items)
+
+    async def async_create_item(self, item_config: dict) -> None:
+        # The real collection awaits validation and change notification
+        # around the item insertion; yield first so two concurrent
+        # callers without a single-flight guard would BOTH get here.
+        await asyncio.sleep(0)
+        self.created.append(dict(item_config))
+        self.items.append(dict(item_config))
+        self.stores[item_config["url_path"]] = FakeDashboardStore()
+        self.hass.data["lovelace"]["dashboards"][item_config["url_path"]] = (
+            self.stores[item_config["url_path"]]
+        )
+
+
+def _install_dashboard_collection(
+    hass, items=None
+) -> FakeDashboardsCollection:
+    """Install the REAL-API-shaped lovelace surfaces on the hass stub.
+
+    Mirrors what lovelace's ``async_setup`` leaves behind in storage
+    mode: ``hass.data["lovelace"]`` is a DICT with the metadata
+    collection under ``dashboards_collection`` and the per-url_path
+    CONTENT managers under ``dashboards``.  Any pre-existing item gets
+    a content manager, exactly as lovelace's change listener would
+    have registered one when the dashboard was created.
+    """
+    collection = FakeDashboardsCollection(hass, items)
+    hass.data["lovelace"] = {
+        "mode": "storage",
+        "dashboards": {},
+        "dashboards_collection": collection,
+    }
+    for item in collection.items:
+        url_path = item.get("url_path")
+        store = FakeDashboardStore()
+        collection.stores[url_path] = store
+        hass.data["lovelace"]["dashboards"][url_path] = store
+    return collection
+
+
 async def test_setup_stores_runtime_data_in_hass_data(hass, make_entry) -> None:
     entry = _wire(make_entry(), hass.registry)
     assert await async_setup_entry(hass, entry) is True
@@ -37,15 +113,25 @@ async def test_setup_stores_runtime_data_in_hass_data(hass, make_entry) -> None:
     assert hass.data[DOMAIN][entry.entry_id] is entry.runtime_data
 
 
-async def test_setup_runtime_data_has_entry_id_and_settings(hass, make_entry) -> None:
-    entry = _wire(make_entry(options={"horizon_days": 7}), hass.registry)
+async def test_setup_runtime_data_has_entry_id_and_coordinator(hass, make_entry) -> None:
+    entry = _wire(make_entry(), hass.registry)
     await async_setup_entry(hass, entry)
     runtime = entry.runtime_data
     assert runtime.entry_id == entry.entry_id
-    assert runtime.settings.horizon_days == 7
+    assert runtime.coordinator is not None
     assert callable(runtime.remove_update_listener)
 
 
+async def test_setup_registers_no_time_change_listener(hass, make_entry) -> None:
+    """The integration owns no database any more: the daily
+    day-rollover/materialization listener is gone (the API service
+    owns the horizon), so setup registers NOTHING against the
+    time-change listener bookkeeping."""
+    entry = _wire(make_entry(), hass.registry)
+    await async_setup_entry(hass, entry)
+    assert hass.time_change.size == 0
+
+
 async def test_unload_returns_true_and_removes_hass_data(hass, make_entry) -> None:
     registry = hass.registry
     entry = _wire(make_entry(), registry)
@@ -120,7 +206,7 @@ async def test_options_update_triggers_reload_once(hass, make_entry) -> None:
     registry = hass.registry
     entry = _wire(make_entry(), registry)
     await async_setup_entry(hass, entry)
-    entry.options = {"horizon_days": 30}
+    entry.options = {"update_interval": 60}
     await registry.async_dispatch_options_update(entry)
     assert hass.config_entries.async_reload.call_count == 1
     assert registry.reloaded == [entry.entry_id]
@@ -198,6 +284,16 @@ async def test_setup_entry_uses_domain_constant(hass, make_entry) -> None:
     assert set(hass.data) == {DOMAIN_CONST}
 
 
+async def test_setup_registers_the_completion_service(hass, make_entry) -> None:
+    """The one domain-global service registers with setup and deregisters
+    on the last unload."""
+    entry = _wire(make_entry(), hass.registry)
+    await async_setup_entry(hass, entry)
+    assert hass.services.has_service(DOMAIN, SERVICE_COMPLETE_QUEST)
+    await async_unload_entry(hass, entry)
+    assert not hass.services.has_service(DOMAIN, SERVICE_COMPLETE_QUEST)
+
+
 async def test_setup_awaitable_listener_removal_supported() -> None:
     """A coroutine-returning remover is awaited during unload."""
     removed = []
@@ -216,9 +312,9 @@ async def test_setup_awaitable_listener_removal_supported() -> None:
     assert entry.runtime_data is None
 
 
-async def test_setup_closes_database_when_listener_registration_fails() -> None:
-    """A listener-registration failure must not leak the opened database."""
-    from custom_components.nestquest.db import NestQuestDatabase
+async def test_setup_unwinds_when_listener_registration_fails() -> None:
+    """A listener-registration failure must not leak partial setup state."""
+    from custom_components.nestquest.const import DOMAIN as DOMAIN_CONST
 
     class _Boom(Exception):
         pass
@@ -228,13 +324,16 @@ async def test_setup_closes_database_when_listener_registration_fails() -> None:
     hass, _registry = make_hass()
     with pytest.raises(_Boom):
         await async_setup_entry(hass, entry)
-    assert hass.data.get(DOMAIN, {}) == {}
+    assert hass.data.get(DOMAIN_CONST, {}) == {}
     assert not hasattr(entry, "runtime_data")
+    assert not hass.services.has_service(DOMAIN_CONST, SERVICE_COMPLETE_QUEST)
 
 
-async def test_unload_closes_database_even_when_listener_removal_raises() -> None:
-    """Unload removes the listener, closes the DB in a finally, then raises."""
-    from custom_components.nestquest.db import NestQuestDatabase
+async def test_unload_shuts_coordinator_even_when_listener_removal_raises() -> None:
+    """A raising update-listener remover must not skip the coordinator
+    shutdown: the retained error is re-raised only after the teardown
+    ran and the runtime record was cleared."""
+    from custom_components.nestquest.const import DOMAIN as DOMAIN_CONST
 
     class _RemoveBoom(Exception):
         pass
@@ -246,504 +345,175 @@ async def test_unload_closes_database_even_when_listener_removal_raises() -> Non
     entry.add_update_listener = lambda listener: _remover
     hass, _registry = make_hass()
     await async_setup_entry(hass, entry)
-    database = entry.runtime_data.database
+    coordinator = entry.runtime_data.coordinator
+    seen = []
+
+    async def _shutdown():
+        seen.append("shutdown")
+
+    coordinator.async_shutdown = _shutdown
+
     with pytest.raises(_RemoveBoom):
         await async_unload_entry(hass, entry)
-    assert database.connected is False, "database leaked despite remover error"
+    assert seen == ["shutdown"], "coordinator shutdown must have run"
     assert entry.runtime_data is None
-    assert DOMAIN not in hass.data
-    assert hass.time_change.size == 0, "time-change listener leaked"
-
-
-async def test_unload_cancels_time_listener_even_when_update_remover_raises() -> None:
-    """A raising update-listener remover must not skip the time-change cancel.
-
-    Both removers are independent: the update-listener remover raising must
-    still cancel the daily time-change callback, whose action would otherwise
-    fire after unload against a closed database.
-    """
-
-    class _RemoveBoom(Exception):
-        pass
-
-    def _remover():
-        raise _RemoveBoom()
-
-    entry = make_config_entry(entry_id="update-boom-time-cancel")
-    entry.add_update_listener = lambda listener: _remover
-    hass, _registry = make_hass()
-    await async_setup_entry(hass, entry)
-    assert hass.time_change.size == 1
-    with pytest.raises(_RemoveBoom):
-        await async_unload_entry(hass, entry)
-    assert hass.time_change.size == 0, "time-change listener not cancelled"
-    assert entry.runtime_data is None
-    assert DOMAIN not in hass.data
-
-
-async def test_setup_registers_day_rollover_listener(hass, make_entry) -> None:
-    """Setup registers a daily rollover listener and stores its cancel fn."""
-    entry = _wire(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    assert hass.time_change.size == 1
-    registration = hass.time_change.registrations[0]
-    assert registration["hour"] == 0
-    assert registration["minute"] == 0
-    assert callable(entry.runtime_data.remove_time_change_listener)
-
-
-async def test_setup_registers_day_rollover_at_configured_time(hass, make_entry) -> None:
-    """The listener fires at the entry option's rollover time, not the default."""
-    entry = _wire(make_entry(options={CONF_DAY_ROLLOVER_TIME: "06:30"}), hass.registry)
-    await async_setup_entry(hass, entry)
-    registration = hass.time_change.registrations[0]
-    assert registration["hour"] == 6
-    assert registration["minute"] == 30
-
-
-async def test_unload_cancels_day_rollover_listener(hass, make_entry) -> None:
-    """Unload removes the time-change listener alongside the update listener."""
-    entry = _wire(make_entry(), hass.registry)
-    await async_setup_entry(hass, entry)
-    assert hass.time_change.size == 1
-    assert await async_unload_entry(hass, entry) is True
+    assert DOMAIN_CONST not in hass.data
     assert hass.time_change.size == 0
 
 
-async def test_rollover_time_change_reregisters_listener_at_new_time(
+async def test_setup_creates_the_panel_dashboard(hass, make_entry) -> None:
+    """A fresh install gets the storage-mode strategy dashboard via the
+    REAL two-step Lovelace sequence: the METADATA (url_path, title,
+    icon, sidebar, single-word allowance — nothing else: the real
+    create schema rejects unknown keys like ``strategy``) through the
+    collection, then the dashboard CONFIG (the strategy reference)
+    through the fresh dashboard's content manager."""
+    collection = _install_dashboard_collection(hass)
+    entry = _wire(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    # Step 1: the metadata create through the collection.
+    assert len(collection.created) == 1
+    created = collection.created[0]
+    assert created["url_path"] == DASHBOARD_URL_PATH
+    assert created["title"]
+    assert created["show_in_sidebar"] is True
+    assert created["allow_single_word"] is True
+    assert "icon" in created
+    # The create payload carries METADATA only: a ``strategy`` key is
+    # rejected by the real collection's create schema (the silent
+    # no-op the first implementation shipped).
+    assert "strategy" not in created
+    assert "mode" not in created
+    # Step 2: the strategy CONFIG saved through the content manager
+    # the create registered, with the custom strategy type.
+    store = hass.data["lovelace"]["dashboards"][DASHBOARD_URL_PATH]
+    assert store is collection.stores[DASHBOARD_URL_PATH]
+    assert store.saved == [{"strategy": {"type": DASHBOARD_STRATEGY_TYPE}}]
+    assert store.config == {"strategy": {"type": DASHBOARD_STRATEGY_TYPE}}
+
+
+async def test_setup_reload_does_not_duplicate_the_dashboard(
     hass, make_entry
 ) -> None:
-    """A rollover-time options change re-registers the listener at the new time."""
-    entry = _wire(
-        make_entry(options={CONF_DAY_ROLLOVER_TIME: "00:00"}), hass.registry
-    )
-    await async_setup_entry(hass, entry)
-    assert (hass.time_change.registrations[0]["hour"], hass.time_change.registrations[0]["minute"]) == (0, 0)
-
-    # The options flow writes the new rollover time, then HA reloads the
-    # entry: unload tears down the old listener, setup re-registers it.
-    entry.options = {CONF_DAY_ROLLOVER_TIME: "06:30"}
+    """A reload (or a second entry) must not create a second dashboard:
+    the one under the stable url_path is reused as-is — BOTH steps are
+    skipped, so the strategy config is not re-saved either."""
+    collection = _install_dashboard_collection(hass)
+    entry = _wire(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    assert len(collection.created) == 1
+    store = hass.data["lovelace"]["dashboards"][DASHBOARD_URL_PATH]
+    assert len(store.saved) == 1
+    # A reload: setup again on the same hass (the reload cycle) —
+    # the existing dashboard must be left alone.
     await async_unload_entry(hass, entry)
-    assert hass.time_change.size == 0
-
     assert await async_setup_entry(hass, entry) is True
-    assert hass.time_change.size == 1
-    registration = hass.time_change.registrations[0]
-    assert (registration["hour"], registration["minute"]) == (6, 30)
+    assert len(collection.created) == 1
+    assert len(store.saved) == 1
+    # And a second entry on the same install.
+    other = _wire(make_entry(entry_id="other"), hass.registry)
+    assert await async_setup_entry(hass, other) is True
+    assert len(collection.created) == 1
+    assert len(store.saved) == 1
 
 
-async def test_day_rollover_listener_materializes_ha_local_horizon(
-    hass, make_entry, monkeypatch
-) -> None:
-    """Firing the listener materializes today..today+horizon in HA local time."""
-    import datetime
-    from unittest.mock import AsyncMock
-    from zoneinfo import ZoneInfo
-
-    import custom_components.nestquest as nestquest
-
-    entry = _wire(make_entry(), hass.registry)
-    await async_setup_entry(hass, entry)
-    database = entry.runtime_data.database
-
-    fake = AsyncMock()
-    monkeypatch.setattr(nestquest, "_materialize_run", fake)
-
-    time_zone = ZoneInfo(hass.config.time_zone)
-    today = datetime.datetime.now(time_zone).date()
-    expected_start = today.isoformat()
-    expected_end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
-
-    await hass.time_change.fire()
-
-    fake.assert_awaited_once_with(
-        database, expected_start, expected_end, today=today
-    )
-
-
-async def test_day_rollover_uses_configured_horizon_days(hass, make_entry) -> None:
-    """The daily run materializes only the configured horizon window."""
-    import datetime
-
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-
-    entry = _wire(make_entry(options={CONF_HORIZON_DAYS: 5}), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    database = entry.runtime_data.database
-
-    # A definition created AFTER setup has no instances yet (create does not
-    # materialize); firing the daily listener must generate only the horizon.
-    child_id = await _seed_daily_child_and_definition(
-        database, _local_today(hass)
-    )
-    await hass.time_change.fire()
-
-    today = _local_today(hass)
-    end = (today + datetime.timedelta(days=5)).isoformat()
-    records = await QuestInstancesDao(database).list_by_date_range(
-        child_id, today.isoformat(), end
-    )
-    assert len(records) == 6
-
-    beyond = (today + datetime.timedelta(days=6)).isoformat()
-    beyond_end = (
-        today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
-    ).isoformat()
-    assert await QuestInstancesDao(database).list_by_date_range(
-        child_id, beyond, beyond_end
-    ) == []
-
-
-def test_day_rollover_time_change_tracker_rejects_local_kwarg() -> None:
-    """The fake async_track_time_change mirrors HA 2024.6 (no ``local`` kwarg).
-
-    Setup drives the local-time wrapper directly, so passing ``local=`` must
-    raise TypeError — otherwise a regression in the production call would be
-    silently masked by the fake.
-    """
-    import inspect as _inspect
-
-    from homeassistant.helpers.event import async_track_time_change
-
-    params = _inspect.signature(async_track_time_change).parameters
-    assert list(params) == ["hass", "action", "hour", "minute", "second"]
-    with pytest.raises(TypeError):
-        async_track_time_change(None, lambda _now: None, hour=0, minute=0, local=True)
-
-
-async def test_setup_applies_all_v1_tables(hass, make_entry) -> None:
-    """Setup applies the full v1 DDL: all four v1 tables exist afterwards."""
-    entry = _wire(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    database = entry.runtime_data.database
-    rows = await database.fetch_all(
-        "SELECT name FROM sqlite_master WHERE type = 'table' "
-        "AND name IN ('children', 'admin_users', 'schedule_rules', "
-        "'quest_definitions') ORDER BY name"
-    )
-    assert [row[0] for row in rows] == [
-        "admin_users",
-        "children",
-        "quest_definitions",
-        "schedule_rules",
-    ]
-    await async_unload_entry(hass, entry)
-
-
-async def _seed_daily_child_and_definition(database, today) -> int:
-    """Create one always-present child + a daily definition starting today.
-
-    Returns the child's id.  No presence schedule means the child is present
-    every day, so the daily rule yields exactly one instance per horizon day.
-    """
-    from custom_components.nestquest.dao_children import ChildrenDao
-    from custom_components.nestquest.quest_definitions import (
-        create_quest_definition,
-    )
-    from custom_components.nestquest.recurrence import RuleType, ScheduleRule
-
-    NOW = "2026-09-14T12:00:00+00:00"
-    child = await ChildrenDao(database).create("Ada", NOW)
-    await create_quest_definition(
-        database,
-        "Daily chore",
-        ScheduleRule(rule_type=RuleType.DAILY, start_date=today.isoformat()),
-        [child.id],
-        ["morning"],
-    )
-    return child.id
-
-
-def _local_today(hass) -> "datetime.date":
-    import datetime
-    from zoneinfo import ZoneInfo
-
-    return datetime.datetime.now(ZoneInfo(hass.config.time_zone)).date()
-
-
-async def test_setup_backfills_instances_over_horizon(hass, make_entry) -> None:
-    """Setup materializes once so a restart backfills any missed days."""
-    import datetime
-
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-    from custom_components.nestquest.db import NestQuestDatabase
-    from custom_components.nestquest.migrations import apply_migrations
-    from custom_components.nestquest.store import async_get_db_path
-
-    # Seed the database BEFORE setup: a restart reopens an existing file that
-    # already holds definitions.  The startup backfill must pick them up.
-    db_path = await async_get_db_path(hass)
-    pre = NestQuestDatabase(hass.async_add_executor_job)
-    await pre.open(db_path)
-    await apply_migrations(pre)
-    child_id = await _seed_daily_child_and_definition(pre, _local_today(hass))
-    await pre.close()
-
-    entry = _wire(make_entry(), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-
-    today = _local_today(hass)
-    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
-    records = await QuestInstancesDao(entry.runtime_data.database).list_by_date_range(
-        child_id, today.isoformat(), end
-    )
-    assert len(records) == DEFAULT_HORIZON_DAYS + 1
-
-
-async def test_setup_backfills_configured_horizon_days(hass, make_entry) -> None:
-    """Setup backfills only the configured (non-default) horizon window."""
-    import datetime
-
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-    from custom_components.nestquest.db import NestQuestDatabase
-    from custom_components.nestquest.migrations import apply_migrations
-    from custom_components.nestquest.store import async_get_db_path
-
-    db_path = await async_get_db_path(hass)
-    pre = NestQuestDatabase(hass.async_add_executor_job)
-    await pre.open(db_path)
-    await apply_migrations(pre)
-    child_id = await _seed_daily_child_and_definition(pre, _local_today(hass))
-    await pre.close()
-
-    entry = _wire(
-        make_entry(options={CONF_HORIZON_DAYS: 5}), hass.registry
-    )
-    assert await async_setup_entry(hass, entry) is True
-
-    today = _local_today(hass)
-    end = (today + datetime.timedelta(days=5)).isoformat()
-    records = await QuestInstancesDao(
-        entry.runtime_data.database
-    ).list_by_date_range(child_id, today.isoformat(), end)
-    assert len(records) == 6
-
-    beyond = (today + datetime.timedelta(days=6)).isoformat()
-    beyond_end = (
-        today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
-    ).isoformat()
-    assert await QuestInstancesDao(
-        entry.runtime_data.database
-    ).list_by_date_range(child_id, beyond, beyond_end) == []
-
-
-async def test_setup_succeeds_with_fully_malformed_options(
+async def test_setup_leaves_an_existing_user_dashboard_alone(
     hass, make_entry
 ) -> None:
-    """A fully malformed options dict falls back per field and setup succeeds.
-
-    ``horizon_days=True``, ``day_rollover_time='99:99'`` and
-    ``morning_summary_time='25:00'`` are all invalid; the integration's
-    ``from_options_resilient`` falls each back to its default, so setup
-    SUCCEEDS, the day-rollover listener registers at the default hour 0
-    minute 0, and the startup backfill materializes the default horizon
-    window.
-    """
-    import datetime
-
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-    from custom_components.nestquest.db import NestQuestDatabase
-    from custom_components.nestquest.migrations import apply_migrations
-    from custom_components.nestquest.store import async_get_db_path
-
-    db_path = await async_get_db_path(hass)
-    pre = NestQuestDatabase(hass.async_add_executor_job)
-    await pre.open(db_path)
-    await apply_migrations(pre)
-    child_id = await _seed_daily_child_and_definition(pre, _local_today(hass))
-    await pre.close()
-
-    entry = _wire(
-        make_entry(
-            options={
-                CONF_HORIZON_DAYS: True,
-                CONF_DAY_ROLLOVER_TIME: "99:99",
-                CONF_MORNING_SUMMARY_TIME: "25:00",
-            }
-        ),
-        hass.registry,
-    )
-    assert await async_setup_entry(hass, entry) is True
-
-    # The day-rollover listener fell back to the default 00:00.
-    registration = hass.time_change.registrations[0]
-    assert registration["hour"] == 0
-    assert registration["minute"] == 0
-
-    # The startup backfill used the default horizon window.
-    today = _local_today(hass)
-    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
-    records = await QuestInstancesDao(
-        entry.runtime_data.database
-    ).list_by_date_range(child_id, today.isoformat(), end)
-    assert len(records) == DEFAULT_HORIZON_DAYS + 1
-
-
-async def test_setup_keeps_horizon_when_sibling_option_is_bad(
-    hass, make_entry
-) -> None:
-    """A malformed sibling option does not reset the configured horizon.
-
-    ``horizon_days=5`` is valid while ``morning_summary_time='25:00'`` is
-    invalid; ``from_options_resilient`` falls back ONLY the bad sibling,
-    so the entry's resolved settings keep ``horizon_days == 5``.
-    """
-    entry = _wire(
-        make_entry(
-            options={
-                CONF_HORIZON_DAYS: 5,
-                CONF_MORNING_SUMMARY_TIME: "25:00",
-            }
-        ),
-        hass.registry,
-    )
-    assert await async_setup_entry(hass, entry) is True
-    assert entry.runtime_data.settings.horizon_days == 5
-
-
-async def test_regenerate_service_registered_and_materializes(
-    hass, make_entry
-) -> None:
-    """``nestquest.regenerate`` is registered and calling it regenerates."""
-    import datetime
-
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-
-    entry = _wire(make_entry(data=_admin_data()), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
-
-    # A definition created AFTER setup has no instances yet (create does not
-    # materialize); the service must generate them on demand.
-    database = entry.runtime_data.database
-    child_id = await _seed_daily_child_and_definition(database, _local_today(hass))
-
-    await hass.services.call(DOMAIN, SERVICE_REGENERATE, context=ADMIN_CTX)
-
-    today = _local_today(hass)
-    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
-    records = await QuestInstancesDao(database).list_by_date_range(
-        child_id, today.isoformat(), end
-    )
-    assert len(records) == DEFAULT_HORIZON_DAYS + 1
-
-
-async def test_regenerate_service_uses_configured_horizon_days(
-    hass, make_entry
-) -> None:
-    """``nestquest.regenerate`` regenerates only the configured horizon."""
-    import datetime
-
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-
-    entry = _wire(
-        make_entry(options={CONF_HORIZON_DAYS: 5}, data=_admin_data()),
-        hass.registry,
-    )
-    assert await async_setup_entry(hass, entry) is True
-
-    database = entry.runtime_data.database
-    child_id = await _seed_daily_child_and_definition(database, _local_today(hass))
-
-    await hass.services.call(DOMAIN, SERVICE_REGENERATE, context=ADMIN_CTX)
-
-    today = _local_today(hass)
-    end = (today + datetime.timedelta(days=5)).isoformat()
-    records = await QuestInstancesDao(database).list_by_date_range(
-        child_id, today.isoformat(), end
-    )
-    assert len(records) == 6
-
-    beyond = (today + datetime.timedelta(days=6)).isoformat()
-    beyond_end = (
-        today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
-    ).isoformat()
-    assert await QuestInstancesDao(database).list_by_date_range(
-        child_id, beyond, beyond_end
-    ) == []
-
-
-async def test_unload_deregisters_regenerate_service(hass, make_entry) -> None:
-    """Unload removes the ``regenerate`` service so no stale entry leaks."""
+    """A dashboard already occupying the stable url_path — the user's
+    own — is never overwritten, deleted or duplicated: no metadata
+    create AND no strategy save against its content manager."""
+    users_dashboard = {"url_path": DASHBOARD_URL_PATH, "title": "My Board"}
+    collection = _install_dashboard_collection(hass, items=[users_dashboard])
     entry = _wire(make_entry(), hass.registry)
     assert await async_setup_entry(hass, entry) is True
-    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
-
-    assert await async_unload_entry(hass, entry) is True
-    assert not hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
+    assert collection.created == []
+    assert collection.items[0] is users_dashboard
+    users_store = hass.data["lovelace"]["dashboards"][DASHBOARD_URL_PATH]
+    assert users_store.saved == []
+    assert users_store.config is None
 
 
-async def test_regenerate_service_is_domain_scoped_across_entries(
+async def test_setup_succeeds_without_the_dashboards_collection(
+    hass, make_entry, caplog
+) -> None:
+    """YAML mode / lovelace not loaded: log a warning, continue setup."""
+    entry = _wire(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    assert entry.entry_id in hass.data[DOMAIN]
+    assert any(
+        "dashboard" in record.message.lower()
+        and record.levelname == "WARNING"
+        for record in caplog.records
+    )
+
+
+async def test_setup_survives_a_failing_dashboards_collection(
     hass, make_entry
 ) -> None:
-    """The ``regenerate`` service is domain-global, not per-entry.
-
-    With two loaded entries the service must be registered and functional;
-    unloading one entry must keep it registered and functional for the
-    remaining entry; unloading the final entry must remove it.
-    """
-    import datetime
-
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-
-    entry_a = _wire(
-        make_entry(entry_id="entry_a", data=_admin_data()), hass.registry
-    )
-    entry_b = _wire(
-        make_entry(entry_id="entry_b", data=_admin_data()), hass.registry
-    )
-
-    assert await async_setup_entry(hass, entry_a) is True
-    assert await async_setup_entry(hass, entry_b) is True
-    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
-
-    # The domain-global handler resolves a live database from any entry.
-    database_b = entry_b.runtime_data.database
-    child_id = await _seed_daily_child_and_definition(
-        database_b, _local_today(hass)
-    )
-    await hass.services.call(DOMAIN, SERVICE_REGENERATE, context=ADMIN_CTX)
-    today = _local_today(hass)
-    end = (today + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)).isoformat()
-    records = await QuestInstancesDao(database_b).list_by_date_range(
-        child_id, today.isoformat(), end
-    )
-    assert len(records) == DEFAULT_HORIZON_DAYS + 1
-
-    # Unloading one entry must not tear down the shared service.
-    assert await async_unload_entry(hass, entry_a) is True
-    assert hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
-
-    # It still works for the remaining entry.
-    await hass.services.call(DOMAIN, SERVICE_REGENERATE, context=ADMIN_CTX)
-
-    # Unloading the final entry removes the domain-global service.
-    assert await async_unload_entry(hass, entry_b) is True
-    assert not hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
-
-
-async def test_setup_cleans_listeners_when_materialization_raises(
-    hass, make_entry, monkeypatch
-) -> None:
-    """A startup-materialization failure rolls back every registered listener.
-
-    The daily and update listeners are installed before the startup
-    materialization runs; when that walk raises, the database is closed but
-    the remover callables must also be invoked so no listener survives
-    firing against a closed database.
-    """
-    import custom_components.nestquest as nestquest
-
-    async def _boom(*_args, **_kwargs):
-        raise RuntimeError("materialization failed")
-
-    monkeypatch.setattr(nestquest, "_materialize_run", _boom)
+    """A collection that refuses the create (permissions, admin-only)
+    logs a warning and setup still succeeds — entities come up."""
+    class _RefusingCollection(FakeDashboardsCollection):
+        async def async_create_item(self, item_config):
+            raise PermissionError("not an admin")
 
+    collection = _RefusingCollection(hass)
+    hass.data["lovelace"] = {
+        "mode": "storage",
+        "dashboards": {},
+        "dashboards_collection": collection,
+    }
     entry = _wire(make_entry(), hass.registry)
-    with pytest.raises(RuntimeError, match="materialization failed"):
-        await async_setup_entry(hass, entry)
+    assert await async_setup_entry(hass, entry) is True
+    assert collection.created == []
 
-    assert hass.time_change.size == 0
-    assert hass.registry.size == 0
-    assert not hass.services.has_service(DOMAIN, SERVICE_REGENERATE)
-    assert not hasattr(entry, "runtime_data")
+
+async def test_setup_survives_a_failing_content_manager_save(
+    hass, make_entry
+) -> None:
+    """A content manager that refuses the config save after the
+    metadata create succeeded (storage write failure) logs a warning
+    and setup still succeeds — the dashboard exists, the strategy
+    simply was not persisted through it."""
+    class _RefusingStore(FakeDashboardStore):
+        async def async_save(self, config):
+            raise OSError("disk full")
+
+    class _StorelessCreateCollection(FakeDashboardsCollection):
+        async def async_create_item(self, item_config):
+            await asyncio.sleep(0)
+            self.created.append(dict(item_config))
+            self.items.append(dict(item_config))
+            self.stores[item_config["url_path"]] = _RefusingStore()
+            self.hass.data["lovelace"]["dashboards"][
+                item_config["url_path"]
+            ] = self.stores[item_config["url_path"]]
+
+    collection = _StorelessCreateCollection(hass)
+    hass.data["lovelace"] = {
+        "mode": "storage",
+        "dashboards": {},
+        "dashboards_collection": collection,
+    }
+    entry = _wire(make_entry(), hass.registry)
+    assert await async_setup_entry(hass, entry) is True
+    assert len(collection.created) == 1
+    store = hass.data["lovelace"]["dashboards"][DASHBOARD_URL_PATH]
+    assert store.saved == []
+
+
+async def test_concurrent_registrations_create_the_dashboard_once(hass) -> None:
+    """Two CONCURRENT registrations (the race two entry setups run)
+    must produce exactly ONE dashboard: the single-flight guard makes
+    the second caller's exists-check run after the first caller's
+    create completed, so it skips both steps.  The fake's create
+    yields before recording, so without the guard both callers would
+    pass the exists-check and the dashboard would be created twice."""
+    collection = _install_dashboard_collection(hass)
+    results = await asyncio.gather(
+        async_register_dashboard(hass),
+        async_register_dashboard(hass),
+    )
+    assert results == [True, True]
+    assert len(collection.created) == 1
+    assert len(collection.stores[DASHBOARD_URL_PATH].saved) == 1

tests/test_materialize.py

@@ -6,29 +6,29 @@ import datetime
 
 import pytest
 
-from custom_components.nestquest.dao_children import ChildrenDao
+from custom_components.nestquest.core.dao_children import ChildrenDao
 from custom_components.nestquest.const import DEFAULT_HORIZON_DAYS
-from custom_components.nestquest.dao_instances import (
+from custom_components.nestquest.core.dao_instances import (
     CompletionEventsDao,
     QuestInstancesDao,
 )
-from custom_components.nestquest.dao_presence import PresenceSchedulesDao
-from custom_components.nestquest.dao_rules import (
+from custom_components.nestquest.core.dao_presence import PresenceSchedulesDao
+from custom_components.nestquest.core.dao_rules import (
     QuestDefinitionsDao,
     schedule_rule_to_storage,
 )
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.materialize import (
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.materialize import (
     materialize,
     regenerate_for_child,
     regenerate_for_definition,
 )
-from custom_components.nestquest.migrations import apply_migrations
-from custom_components.nestquest.quest_definitions import (
+from custom_components.nestquest.core.migrations import apply_migrations
+from custom_components.nestquest.core.quest_definitions import (
     create_quest_definition,
     edit_quest_definition,
 )
-from custom_components.nestquest.recurrence import (
+from custom_components.nestquest.core.recurrence import (
     RuleType,
     ScheduleRule,
     occurs_on,
@@ -505,7 +505,7 @@ def test_materialize_skips_deactivated_child_mid_walk(tmp_path) -> None:
 
 def test_materialize_uses_single_presence_snapshot_mid_walk(tmp_path) -> None:
     async def _body(database):
-        from custom_components.nestquest.dao_presence import (
+        from custom_components.nestquest.core.dao_presence import (
             PresenceOverridesDao,
         )
 
@@ -628,7 +628,7 @@ def test_materialize_does_not_overwrite_regenerated_due_time(tmp_path) -> None:
 
 def test_materialize_honours_overrides(tmp_path) -> None:
     async def _body(database):
-        from custom_components.nestquest.dao_presence import (
+        from custom_components.nestquest.core.dao_presence import (
             PresenceOverridesDao,
         )
 
@@ -758,7 +758,7 @@ def test_materialize_clamps_past_start_to_today(tmp_path) -> None:
 
 def test_materialize_skips_inactive_definitions(tmp_path) -> None:
     async def _body(database):
-        from custom_components.nestquest.quest_definitions import (
+        from custom_components.nestquest.core.quest_definitions import (
             set_quest_definition_active,
         )
 
@@ -906,7 +906,7 @@ def test_regenerate_for_child_rebuilds_horizon_preserves_history(
     tmp_path,
 ) -> None:
     async def _body(database):
-        from custom_components.nestquest.dao_presence import (
+        from custom_components.nestquest.core.dao_presence import (
             PresenceOverridesDao,
         )
 
@@ -1091,7 +1091,7 @@ def test_regenerate_for_child_uses_single_anchor_across_midnight(
 def test_regenerate_for_child_is_child_scoped(tmp_path) -> None:
     """Regenerating one child must never touch another child's rows."""
     async def _body(database):
-        from custom_components.nestquest.dao_presence import (
+        from custom_components.nestquest.core.dao_presence import (
             PresenceOverridesDao,
         )
 
@@ -1493,10 +1493,10 @@ def test_materialize_end_to_end_six_rule_types(tmp_path, monkeypatch) -> None:
     monkeypatch.setattr(materialize_module, "_now_stamp", _distinct_stamp)
 
     async def _body(database):
-        from custom_components.nestquest.dao_presence import (
+        from custom_components.nestquest.core.dao_presence import (
             PresenceOverridesDao,
         )
-        from custom_components.nestquest.presence import PresenceSchedule
+        from custom_components.nestquest.core.presence import PresenceSchedule
 
         children = ChildrenDao(database)
         schedules = PresenceSchedulesDao(database)

tests/test_migrations.py

@@ -9,16 +9,16 @@ from unittest.mock import AsyncMock
 
 import pytest
 
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.schema import SCHEMA_V7_META_STATE_DDL
-from custom_components.nestquest.migrations import (
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.schema import SCHEMA_V7_META_STATE_DDL
+from custom_components.nestquest.core.migrations import (
     MIGRATIONS,
     VERSION_TABLE,
     VERSION_TABLE_DDL,
     apply_migrations,
     read_schema_version,
 )
-from custom_components.nestquest.schema import (
+from custom_components.nestquest.core.schema import (
     SCHEMA_V1_STATEMENTS,
     SCHEMA_V1_QUEST_DEFINITION_WINDOWS_DDL,
 )
@@ -1064,133 +1064,3 @@ def test_partial_pending_migrations_resume_from_current_version(
         assert "step_b" in _tables(database)
     finally:
         _run(database.close())
-
-
-# ---------------------------------------------------------------------------
-# Startup wiring: setup runs the migration runner, not raw DDL
-# ---------------------------------------------------------------------------
-
-
-async def _setup_entry(hass, entry, registry) -> object:
-    from tests.test_lifecycle import _wire  # reuse the established wiring
-
-    entry = _wire(entry, registry)
-    from custom_components.nestquest import async_setup_entry
-
-    await async_setup_entry(hass, entry)
-    return entry
-
-
-async def test_setup_entry_migrates_fresh_database(hass, make_entry) -> None:
-    import sqlite3 as sqlite3_mod
-
-    from custom_components.nestquest.migrations import read_schema_version
-    from custom_components.nestquest.store import async_get_db_path
-
-    entry = await _setup_entry(hass, make_entry(), hass.registry)
-    database = entry.runtime_data.database
-    assert await read_schema_version(database) == len(MIGRATIONS)
-    # The v1 tables exist because the runner applied migration 1.
-    names = {
-        row[0]
-        for row in await database.fetch_all(
-            "SELECT name FROM sqlite_master WHERE type = 'table' "
-            "AND name NOT LIKE 'sqlite_%'"
-        )
-    }
-    assert "children" in names and "completion_events" in names
-    # The version table exists with its singleton row stamped.
-    columns = await database.fetch_all(f"PRAGMA table_info({VERSION_TABLE})")
-    assert [(row[1], row[3]) for row in columns] == [("id", 1), ("version", 1)]
-    db_path = await async_get_db_path(hass)
-    conn = sqlite3_mod.connect(db_path)
-    try:
-        conn.execute(f"INSERT INTO {VERSION_TABLE} (id, version) VALUES (2, 1)")
-        violated = False
-    except sqlite3_mod.IntegrityError:
-        violated = True
-    finally:
-        conn.close()
-    assert violated, "singleton-row CHECK must be live in the setup-created DB"
-    await database.close()
-
-
-async def test_options_reload_reopens_and_rechecks_version(
-    hass, make_entry
-) -> None:
-    """A listener-triggered reload re-runs setup against the same file.
-
-    Unload then setup is the reload lifecycle: the old connection is
-    closed, apply_migrations runs again on the persisted file, keeps
-    version and rows intact, and the reopened connection is live.
-    """
-    from custom_components.nestquest import async_unload_entry
-    from custom_components.nestquest.migrations import read_schema_version
-
-    entry = await _setup_entry(hass, make_entry(), hass.registry)
-    database_a = entry.runtime_data.database
-    await database_a.execute(
-        "INSERT INTO children (display_name, created_at) VALUES (?, ?)",
-        ("Ada", "2026-09-13T00:00:00+00:00"),
-    )
-    assert await async_unload_entry(hass, entry) is True
-    assert not database_a.connected
-
-    entry_reloaded = await _setup_entry(hass, make_entry(), hass.registry)
-    database_b = entry_reloaded.runtime_data.database
-    assert database_b is not database_a
-    try:
-        assert await read_schema_version(database_b) == len(MIGRATIONS)
-        row = await database_b.fetch_one("SELECT COUNT(*) FROM children")
-        assert row == (1,)
-    finally:
-        await database_b.close()
-
-
-async def test_setup_entry_failure_closes_database(
-    hass, make_entry, monkeypatch
-) -> None:
-    """A failing migration closes the opened connection before re-raising.
-
-    A migration failure surfaces as ConfigEntryNotReady (HA retries
-    setup) with the original error preserved as __cause__.  Spies on
-    the real wrapper instance: records whether close() ran, rather
-    than inferring from hass.data (a failed setup never stores a
-    runtime record).
-    """
-    import pytest as pytest_module
-    from homeassistant.exceptions import ConfigEntryNotReady
-
-    import custom_components.nestquest as nestquest_module
-    from custom_components.nestquest.db import NestQuestDatabase
-    from custom_components.nestquest.migrations import (
-        MIGRATIONS as _MIGRATIONS,
-    )
-
-    async def _failing(database, migrations=_MIGRATIONS):
-        raise RuntimeError("boom")
-
-    monkeypatch.setattr(
-        nestquest_module, "apply_migrations", _failing, raising=True
-    )
-
-    close_calls: list[bool] = []
-    original_close = NestQuestDatabase.close
-
-    async def _spy_close(self):
-        close_calls.append(True)
-        return await original_close(self)
-
-    monkeypatch.setattr(NestQuestDatabase, "close", _spy_close)
-
-    entry = make_entry()
-    with pytest_module.raises(ConfigEntryNotReady) as excinfo:
-        await _setup_entry(hass, entry, hass.registry)
-    assert isinstance(excinfo.value.__cause__, RuntimeError)
-    assert "boom" in str(excinfo.value.__cause__)
-
-    assert close_calls == [True], (
-        "failed setup must close the connection it opened"
-    )
-    record = hass.data["nestquest"].get(entry.entry_id)
-    assert record is None, "failed setup must not store runtime data"

tests/test_options_flow.py

@@ -14,27 +14,16 @@ from conftest import make_config_entry, make_hass, options_flow_base as _options
 from custom_components.nestquest import config_flow
 from custom_components.nestquest import options_flow
 from custom_components.nestquest.const import (
-    CONF_ADMIN_USER_IDS,
-    CONF_DAY_ROLLOVER_TIME,
-    CONF_HORIZON_DAYS,
+    CONF_API_BASE_URL,
     CONF_PANEL_IDLE_TIMEOUT,
+    CONF_PANEL_TOKEN,
+    CONF_SNAPSHOT_STALENESS,
     CONF_UPDATE_INTERVAL,
-    CONF_AFTERNOON_REMINDER_ENABLED,
-    CONF_AFTERNOON_REMINDER_TIME,
-    CONF_CELEBRATION_ENABLED,
-    CONF_END_OF_DAY_REPORT_ENABLED,
-    CONF_END_OF_DAY_REPORT_TIME,
-    CONF_MORNING_SUMMARY_ENABLED,
-    CONF_MORNING_SUMMARY_TIME,
-    CONF_NOTIFY_TARGET,
-    DEFAULT_AFTERNOON_REMINDER_TIME,
-    DEFAULT_AUTOMATION_ENABLED,
-    DEFAULT_END_OF_DAY_REPORT_TIME,
-    DEFAULT_MORNING_SUMMARY_TIME,
-    DEFAULT_UPDATE_INTERVAL,
-    DEFAULT_DAY_ROLLOVER_TIME,
-    DEFAULT_HORIZON_DAYS,
+    DEFAULT_API_BASE_URL,
     DEFAULT_PANEL_IDLE_TIMEOUT,
+    DEFAULT_PANEL_TOKEN,
+    DEFAULT_SNAPSHOT_STALENESS,
+    DEFAULT_UPDATE_INTERVAL,
     DOMAIN,
 )
 
@@ -43,25 +32,19 @@ STRINGS_PATH = PKG_DIR / "strings.json"
 TRANSLATIONS_EN_PATH = PKG_DIR / "translations" / "en.json"
 
 VALID_INPUT = {
-    CONF_HORIZON_DAYS: 7,
-    CONF_DAY_ROLLOVER_TIME: "03:30",
     CONF_PANEL_IDLE_TIMEOUT: 60,
 }
 
 #: What a schema-validated submit produces from a bare VALID_INPUT on a
-#: fresh entry: the Feature 10 refresh interval and the Feature 11
-#: notification section fill from their defaults.
+#: fresh entry: the Feature 10 refresh interval, the Feature 18
+#: staleness threshold, and the Feature 18 API connection fill from
+#: their defaults.
 FULL_INPUT = {
     **VALID_INPUT,
     CONF_UPDATE_INTERVAL: DEFAULT_UPDATE_INTERVAL,
-    CONF_NOTIFY_TARGET: "",
-    CONF_MORNING_SUMMARY_TIME: DEFAULT_MORNING_SUMMARY_TIME,
-    CONF_AFTERNOON_REMINDER_TIME: DEFAULT_AFTERNOON_REMINDER_TIME,
-    CONF_END_OF_DAY_REPORT_TIME: DEFAULT_END_OF_DAY_REPORT_TIME,
-    CONF_MORNING_SUMMARY_ENABLED: DEFAULT_AUTOMATION_ENABLED,
-    CONF_AFTERNOON_REMINDER_ENABLED: DEFAULT_AUTOMATION_ENABLED,
-    CONF_END_OF_DAY_REPORT_ENABLED: DEFAULT_AUTOMATION_ENABLED,
-    CONF_CELEBRATION_ENABLED: DEFAULT_AUTOMATION_ENABLED,
+    CONF_SNAPSHOT_STALENESS: DEFAULT_SNAPSHOT_STALENESS,
+    CONF_API_BASE_URL: DEFAULT_API_BASE_URL,
+    CONF_PANEL_TOKEN: DEFAULT_PANEL_TOKEN,
 }
 
 
@@ -77,48 +60,13 @@ def _make_entry(entry_id: str = "test_entry", options: dict | None = None, data:
     return make_config_entry(entry_id=entry_id, options=options, data=data)
 
 
-def _make_flow(entry, *, users=None, database=None) -> options_flow.NestQuestOptionsFlow:
-    """Create an options flow instance bound to a stubbed config entry.
-
-    ``users`` populates a stubbed hass.auth for the admin picker;
-    ``database`` wires the runtime record so the flow can read and
-    write the allowlist like real HA's options flow does.
-    """
-    from unittest.mock import AsyncMock
-
+def _make_flow(entry) -> options_flow.NestQuestOptionsFlow:
+    """Create an options flow instance bound to a stubbed config entry."""
     flow = options_flow.NestQuestOptionsFlow(config_entry=entry)
     flow.hass = SimpleNamespace()
-    flow.hass.auth = SimpleNamespace(
-        async_get_users=AsyncMock(return_value=users or [])
-    )
-    if database is not None:
-        from custom_components.nestquest.const import DOMAIN
-
-        flow.hass.data = {
-            DOMAIN: {entry.entry_id: SimpleNamespace(database=database)}
-        }
     return flow
 
 
-def _user(user_id: str, name: str):
-    return SimpleNamespace(id=user_id, name=name)
-
-
-def _open_allowlist_db(tmp_path, name):
-    """A real migrated temp database for the flow to read and write."""
-    from unittest.mock import AsyncMock, MagicMock
-
-    from custom_components.nestquest.db import NestQuestDatabase
-    from custom_components.nestquest.migrations import apply_migrations
-
-    hass = MagicMock()
-    hass.async_add_executor_job = AsyncMock(side_effect=(lambda fn, *a: fn(*a)))
-    database = NestQuestDatabase(hass.async_add_executor_job)
-    _run(database.open(tmp_path / name))
-    _run(apply_migrations(database))
-    return database
-
-
 def _schema_values(schema) -> dict:
     """Extract the per-field default values from a real voluptuous schema."""
     return {
@@ -145,11 +93,11 @@ def test_options_flow_get_options_flow_is_ha_callback() -> None:
 
 def test_options_flow_constructs_through_2024_6_surface() -> None:
     """The handler constructs against the mocked 2024.6 base and inherits its contract."""
-    entry = _make_entry(options={CONF_HORIZON_DAYS: 21})
+    entry = _make_entry(options={CONF_UPDATE_INTERVAL: 90})
     flow = options_flow.NestQuestOptionsFlow(config_entry=entry)
     assert isinstance(flow, _options_flow_base())
     assert flow.config_entry is entry
-    assert flow.options == {CONF_HORIZON_DAYS: 21}
+    assert flow.options == {CONF_UPDATE_INTERVAL: 90}
 
 
 def test_options_flow_submits_through_2024_6_surface() -> None:
@@ -184,82 +132,66 @@ def test_options_flow_prefills_from_defaults() -> None:
     flow = _make_flow(_make_entry())
     result = _run(flow.async_step_init(None))
     values = _schema_values(result["data_schema"])
-    assert values[CONF_HORIZON_DAYS] == DEFAULT_HORIZON_DAYS
-    assert values[CONF_DAY_ROLLOVER_TIME] == DEFAULT_DAY_ROLLOVER_TIME
     assert values[CONF_PANEL_IDLE_TIMEOUT] == DEFAULT_PANEL_IDLE_TIMEOUT
+    assert values[CONF_UPDATE_INTERVAL] == DEFAULT_UPDATE_INTERVAL
+    assert values[CONF_SNAPSHOT_STALENESS] == DEFAULT_SNAPSHOT_STALENESS
 
 
 def test_options_flow_prefills_from_entry_options() -> None:
     """Stored entry options win over entry data and defaults."""
     entry = _make_entry(
         options={
-            CONF_HORIZON_DAYS: 21,
-            CONF_DAY_ROLLOVER_TIME: "05:45",
             CONF_PANEL_IDLE_TIMEOUT: 120,
+            CONF_UPDATE_INTERVAL: 90,
+            CONF_SNAPSHOT_STALENESS: 450,
         },
         data={
-            CONF_HORIZON_DAYS: 99,
-            CONF_DAY_ROLLOVER_TIME: "23:59",
             CONF_PANEL_IDLE_TIMEOUT: 999,
+            CONF_UPDATE_INTERVAL: 999,
+            CONF_SNAPSHOT_STALENESS: 999,
         },
     )
     result = _run(_make_flow(entry).async_step_init(None))
     values = _schema_values(result["data_schema"])
-    assert values[CONF_HORIZON_DAYS] == 21
-    assert values[CONF_DAY_ROLLOVER_TIME] == "05:45"
     assert values[CONF_PANEL_IDLE_TIMEOUT] == 120
+    assert values[CONF_UPDATE_INTERVAL] == 90
+    assert values[CONF_SNAPSHOT_STALENESS] == 450
 
 
 def test_options_flow_falls_back_to_entry_data() -> None:
     """Pre-upgrade entries without options fall back to entry.data."""
     entry = _make_entry(
         data={
-            CONF_HORIZON_DAYS: 10,
-            CONF_DAY_ROLLOVER_TIME: "01:15",
             CONF_PANEL_IDLE_TIMEOUT: 90,
+            CONF_UPDATE_INTERVAL: 60,
+            CONF_SNAPSHOT_STALENESS: 240,
         }
     )
     result = _run(_make_flow(entry).async_step_init(None))
     values = _schema_values(result["data_schema"])
-    assert values[CONF_HORIZON_DAYS] == 10
-    assert values[CONF_DAY_ROLLOVER_TIME] == "01:15"
     assert values[CONF_PANEL_IDLE_TIMEOUT] == 90
+    assert values[CONF_UPDATE_INTERVAL] == 60
+    assert values[CONF_SNAPSHOT_STALENESS] == 240
 
 
 def test_options_flow_schema_applies_stored_defaults() -> None:
-    """A real voluptuous validate({}) fills every field from the stored defaults.
-
-    Without a runtime database (and no auth in the bare harness), the
-    admin picker's default is the empty selection and its choice set is
-    empty — the three legacy settings are unaffected.
-    """
+    """A real voluptuous validate({}) fills every field from the stored defaults."""
     entry = _make_entry(
         options={
-            CONF_HORIZON_DAYS: 21,
-            CONF_DAY_ROLLOVER_TIME: "05:45",
             CONF_PANEL_IDLE_TIMEOUT: 120,
             CONF_UPDATE_INTERVAL: 90,
-            CONF_NOTIFY_TARGET: "notify.mobile_app_test",
-            CONF_MORNING_SUMMARY_TIME: "07:00",
-            CONF_AFTERNOON_REMINDER_TIME: "14:00",
-            CONF_END_OF_DAY_REPORT_TIME: "21:30",
+            CONF_SNAPSHOT_STALENESS: 450,
+            CONF_API_BASE_URL: "http://panel.lan:8443",
+            CONF_PANEL_TOKEN: "stored-token",
         }
     )
     result = _run(_make_flow(entry).async_step_init(None))
     assert result["data_schema"]({}) == {
-        CONF_HORIZON_DAYS: 21,
-        CONF_DAY_ROLLOVER_TIME: "05:45",
         CONF_PANEL_IDLE_TIMEOUT: 120,
         CONF_UPDATE_INTERVAL: 90,
-        CONF_NOTIFY_TARGET: "notify.mobile_app_test",
-        CONF_MORNING_SUMMARY_TIME: "07:00",
-        CONF_AFTERNOON_REMINDER_TIME: "14:00",
-        CONF_END_OF_DAY_REPORT_TIME: "21:30",
-        CONF_MORNING_SUMMARY_ENABLED: True,
-        CONF_AFTERNOON_REMINDER_ENABLED: True,
-        CONF_END_OF_DAY_REPORT_ENABLED: True,
-        CONF_CELEBRATION_ENABLED: True,
-        CONF_ADMIN_USER_IDS: [],
+        CONF_SNAPSHOT_STALENESS: 450,
+        CONF_API_BASE_URL: "http://panel.lan:8443",
+        CONF_PANEL_TOKEN: "stored-token",
     }
 
 
@@ -269,50 +201,12 @@ def test_options_flow_schema_coerces_field_types() -> None:
     result = _run(flow.async_step_init(None))
     schema = result["data_schema"]
     validators = {marker.schema: validator for marker, validator in schema.schema.items()}
-    assert validators[CONF_HORIZON_DAYS] is int
-    assert validators[CONF_DAY_ROLLOVER_TIME] is str
     assert validators[CONF_PANEL_IDLE_TIMEOUT] is int
-
-
-@pytest.mark.parametrize("bad_horizon", [0, -5])
-def test_options_flow_rejects_non_positive_horizon(bad_horizon: int) -> None:
-    """Zero or negative horizon values yield a field-level error, no exception."""
-    flow = _make_flow(_make_entry())
-    result = _run(
-        flow.async_step_init({**VALID_INPUT, CONF_HORIZON_DAYS: bad_horizon})
-    )
-    assert result["type"] == "form"
-    assert result["errors"] == {CONF_HORIZON_DAYS: "invalid"}
-
-
-def test_options_flow_rejects_malformed_time_not_a_time() -> None:
-    """Non-HH:MM strings are rejected with invalid_time."""
-    flow = _make_flow(_make_entry())
-    result = _run(
-        flow.async_step_init({**VALID_INPUT, CONF_DAY_ROLLOVER_TIME: "noon"})
-    )
-    assert result["type"] == "form"
-    assert result["errors"] == {CONF_DAY_ROLLOVER_TIME: "invalid_time"}
-
-
-def test_options_flow_rejects_malformed_time_out_of_range() -> None:
-    """Out-of-range HH:MM values are rejected with invalid_time."""
-    flow = _make_flow(_make_entry())
-    result = _run(
-        flow.async_step_init({**VALID_INPUT, CONF_DAY_ROLLOVER_TIME: "25:99"})
-    )
-    assert result["type"] == "form"
-    assert result["errors"] == {CONF_DAY_ROLLOVER_TIME: "invalid_time"}
-
-
-def test_options_flow_rejects_pasted_unicode_superscript_time() -> None:
-    """Pasted Unicode digits like '²²:²²' yield a field-level error, no exception."""
-    flow = _make_flow(_make_entry())
-    result = _run(
-        flow.async_step_init({**VALID_INPUT, CONF_DAY_ROLLOVER_TIME: "²²:²²"})
-    )
-    assert result["type"] == "form"
-    assert result["errors"] == {CONF_DAY_ROLLOVER_TIME: "invalid_time"}
+    assert validators[CONF_UPDATE_INTERVAL] is int
+    assert validators[CONF_SNAPSHOT_STALENESS] is int
+    # The Feature 18 API connection fields are free-text strings.
+    assert validators[CONF_API_BASE_URL] is str
+    assert validators[CONF_PANEL_TOKEN] is str
 
 
 @pytest.mark.parametrize("bad_timeout", ["abc", 0, -10, 10])
@@ -326,8 +220,21 @@ def test_options_flow_rejects_invalid_idle_timeout(bad_timeout) -> None:
     assert result["errors"] == {CONF_PANEL_IDLE_TIMEOUT: "invalid"}
 
 
-def test_options_flow_creates_entry_with_four_keys() -> None:
-    """A valid submit creates an entry with exactly the four validated keys."""
+@pytest.mark.parametrize("bad_interval", ["abc", True, 0, -10, 29])
+def test_options_flow_rejects_invalid_update_interval(bad_interval) -> None:
+    """Non-numeric, boolean, and below-floor update intervals reject."""
+    flow = _make_flow(_make_entry())
+    result = _run(
+        flow.async_step_init({**VALID_INPUT, CONF_UPDATE_INTERVAL: bad_interval})
+    )
+    assert result["type"] == "form"
+    assert result["errors"] == {CONF_UPDATE_INTERVAL: "invalid"}
+
+
+def test_options_flow_creates_entry_with_validated_keys() -> None:
+    """A valid submit creates an entry with exactly the validated keys
+    (the client-facing settings, filled from defaults where the raw
+    submit omitted them)."""
     flow = _make_flow(_make_entry())
     result = _run(flow.async_step_init(dict(VALID_INPUT)))
     assert result["type"] == "create_entry"
@@ -342,7 +249,7 @@ def test_options_flow_create_entry_data_lands_in_entry_options_and_reloads_once(
     entry = _make_entry()
     entry.add_update_listener = lambda listener: registry.add(entry.entry_id, listener)
 
-    # Simulate setup registering the merged lifecycle update listener.
+    # Simulate setup registering the lifecycle update listener.
     from custom_components.nestquest import async_setup_entry
 
     _run(async_setup_entry(hass, entry))
@@ -361,14 +268,13 @@ def test_options_flow_create_entry_data_lands_in_entry_options_and_reloads_once(
 
 def test_options_flow_validation_never_raises() -> None:
     """Validation returns errors instead of raising for arbitrary junk input."""
-    junk = {CONF_HORIZON_DAYS: None, CONF_DAY_ROLLOVER_TIME: None, CONF_PANEL_IDLE_TIMEOUT: None}
+    junk = {CONF_PANEL_IDLE_TIMEOUT: None, CONF_UPDATE_INTERVAL: "abc"}
     flow = _make_flow(_make_entry())
     result = _run(flow.async_step_init(junk))
     assert result["type"] == "form"
     assert result["errors"] == {
-        CONF_HORIZON_DAYS: "invalid",
-        CONF_DAY_ROLLOVER_TIME: "invalid_time",
         CONF_PANEL_IDLE_TIMEOUT: "invalid",
+        CONF_UPDATE_INTERVAL: "invalid",
     }
 
 
@@ -398,10 +304,10 @@ def test_options_strings_present_and_matching(strings: dict, translations_en: di
     assert init["title"]
     assert init["description"]
     data = init["data"]
-    for key in (CONF_HORIZON_DAYS, CONF_DAY_ROLLOVER_TIME, CONF_PANEL_IDLE_TIMEOUT):
+    for key in (CONF_PANEL_IDLE_TIMEOUT,):
         assert data.get(key), f"Missing field name for '{key}'"
     errors = options["errors"]
-    for key in ("invalid", "invalid_time"):
+    for key in ("invalid",):
         assert errors.get(key), f"Missing error string for '{key}'"
 
 
@@ -457,345 +363,199 @@ def test_options_flow_no_hardcoded_domain_or_db_filename() -> None:
                 f"Hard-coded database filename in {py_file.name}:{node.lineno}"
             )
 
+
 # ---------------------------------------------------------------------------
-# Admin allowlist picker (Feature 03)
+# Panel-plane API connection section (Feature 18)
 # ---------------------------------------------------------------------------
 
 
-def test_options_flow_picker_lists_existing_users(tmp_path) -> None:
-    """The picker offers EXISTING HA users (id -> name), never free text."""
-    import voluptuous as vol
-
-    database = _open_allowlist_db(tmp_path, "picker-users.db")
-    try:
-        from custom_components.nestquest.admin_allowlist import set_admin_ids
-
-        _run(set_admin_ids(database, ["u1"]))
-        entry = _make_entry()
-        flow = _make_flow(
-            entry,
-            users=[_user("u1", "Joshua"), _user("u2", "Sam")],
-            database=database,
-        )
-        result = _run(flow.async_step_init(None))
-        schema = result["data_schema"]
-        marker = next(
-            m for m in schema.schema
-            if getattr(m, "schema", None) == CONF_ADMIN_USER_IDS
-        )
-        # Default is the CURRENT database allowlist.
-        values = _schema_values(schema)
-        assert values[CONF_ADMIN_USER_IDS] == ["u1"]
-        # Both users are selectable; an unknown id is rejected by the
-        # schema itself (this is what real HA submits go through).
-        validated = schema(
-            {
-                CONF_HORIZON_DAYS: 7,
-                CONF_DAY_ROLLOVER_TIME: "03:30",
-                CONF_PANEL_IDLE_TIMEOUT: 60,
-                CONF_ADMIN_USER_IDS: ["u1", "u2"],
-            }
-        )
-        assert validated[CONF_ADMIN_USER_IDS] == ["u1", "u2"]
-        with pytest.raises(vol.Invalid):
-            schema(
-                {
-                    CONF_HORIZON_DAYS: 7,
-                    CONF_DAY_ROLLOVER_TIME: "03:30",
-                    CONF_PANEL_IDLE_TIMEOUT: 60,
-                    CONF_ADMIN_USER_IDS: ["impostor"],
-                }
-            )
-    finally:
-        _run(database.close())
-
-
-def test_options_flow_submit_applies_selection_to_database(tmp_path) -> None:
-    database = _open_allowlist_db(tmp_path, "picker-apply.db")
-    try:
-        from custom_components.nestquest.admin_allowlist import (
-            list_admin_ids,
-            set_admin_ids,
-        )
-
-        _run(set_admin_ids(database, ["u1"]))
-        entry = _make_entry()
-        flow = _make_flow(
-            entry,
-            users=[_user("u1", "Joshua"), _user("u2", "Sam")],
-            database=database,
-        )
-        result = _run(
-            flow.async_step_init({**VALID_INPUT, CONF_ADMIN_USER_IDS: ["u2"]})
-        )
-        assert result["type"] == "create_entry"
-        assert result["data"][CONF_ADMIN_USER_IDS] == ["u2"]
-        # The allowlist (and the entry's recovery copy) carry the pick.
-        assert await_gather(list_admin_ids(database)) == ["u2"]
-    finally:
-        _run(database.close())
-
-
-def await_gather(coro):
-    return _run(coro)
-
-
-def test_options_flow_empty_selection_refused(tmp_path) -> None:
-    """Saving zero admins is refused: an empty allowlist fails closed."""
-    database = _open_allowlist_db(tmp_path, "picker-empty.db")
-    try:
-        from custom_components.nestquest.admin_allowlist import (
-            list_admin_ids,
-            set_admin_ids,
-        )
-
-        _run(set_admin_ids(database, ["u1"]))
-        entry = _make_entry()
-        flow = _make_flow(
-            entry,
-            users=[_user("u1", "Joshua")],
-            database=database,
-        )
-        result = _run(
-            flow.async_step_init({**VALID_INPUT, CONF_ADMIN_USER_IDS: []})
-        )
-        assert result["type"] == "form"
-        assert result["errors"] == {CONF_ADMIN_USER_IDS: "no_admins"}
-        assert await_gather(list_admin_ids(database)) == ["u1"]
-    finally:
-        _run(database.close())
-
-
-def test_options_flow_unknown_selection_refused(tmp_path) -> None:
-    database = _open_allowlist_db(tmp_path, "picker-unknown.db")
-    try:
-        from custom_components.nestquest.admin_allowlist import (
-            list_admin_ids,
-            set_admin_ids,
-        )
-
-        _run(set_admin_ids(database, ["u1"]))
-        entry = _make_entry()
-        flow = _make_flow(
-            entry,
-            users=[_user("u1", "Joshua")],
-            database=database,
-        )
-        result = _run(
-            flow.async_step_init(
-                {**VALID_INPUT, CONF_ADMIN_USER_IDS: ["impostor"]}
-            )
-        )
-        assert result["type"] == "form"
-        assert result["errors"] == {CONF_ADMIN_USER_IDS: "invalid_admin"}
-        assert await_gather(list_admin_ids(database)) == ["u1"]
-    finally:
-        _run(database.close())
-
-
-def test_options_flow_submit_without_admin_key_keeps_allowlist(tmp_path) -> None:
-    """Raw callers omitting the key (pre-picker payloads) do not
-    touch the allowlist; the CURRENT allowlist is carried forward on
-    the options copy so no removed admin can be resurrected later."""
-    database = _open_allowlist_db(tmp_path, "picker-legacy.db")
-    try:
-        from custom_components.nestquest.admin_allowlist import (
-            list_admin_ids,
-            set_admin_ids,
-        )
-
-        _run(set_admin_ids(database, ["u1"]))
-        entry = _make_entry()
-        flow = _make_flow(
-            entry,
-            users=[_user("u1", "Joshua")],
-            database=database,
-        )
-        result = _run(flow.async_step_init(dict(VALID_INPUT)))
-        assert result["type"] == "create_entry"
-        assert result["data"][CONF_ADMIN_USER_IDS] == ["u1"]
-        assert await_gather(list_admin_ids(database)) == ["u1"]
-    finally:
-        _run(database.close())
-
-
-def test_options_flow_duplicate_selection_refused(tmp_path) -> None:
-    """Duplicate ids surface as a field error, not an unhandled
-    ValueError from the business layer."""
-    database = _open_allowlist_db(tmp_path, "picker-dupe.db")
-    try:
-        from custom_components.nestquest.admin_allowlist import (
-            list_admin_ids,
-            set_admin_ids,
-        )
-
-        _run(set_admin_ids(database, ["u1"]))
-        entry = _make_entry()
-        flow = _make_flow(
-            entry,
-            users=[_user("u1", "Joshua"), _user("u2", "Sam")],
-            database=database,
-        )
-        result = _run(
-            flow.async_step_init(
-                {**VALID_INPUT, CONF_ADMIN_USER_IDS: ["u2", "u2"]}
-            )
-        )
-        assert result["type"] == "form"
-        assert result["errors"] == {CONF_ADMIN_USER_IDS: "invalid_admin"}
-        assert await_gather(list_admin_ids(database)) == ["u1"]
-    finally:
-        _run(database.close())
-
-
-def test_options_flow_omitted_picker_carries_allowlist_forward(
-    tmp_path,
-) -> None:
-    """An omitted picker field must not drop the allowlist copy from
-    the returned options: HA replaces entry.options wholesale, and a
-    later database loss must not resurrect removed admins from the
-    stale config-flow copy in entry.data."""
-    database = _open_allowlist_db(tmp_path, "picker-carry.db")
-    try:
-        from custom_components.nestquest.admin_allowlist import (
-            set_admin_ids,
-        )
-
-        _run(set_admin_ids(database, ["u2"]))
-        entry = _make_entry()
-        flow = _make_flow(
-            entry,
-            users=[_user("u1", "Joshua"), _user("u2", "Sam")],
-            database=database,
-        )
-        result = _run(flow.async_step_init(dict(VALID_INPUT)))
-        assert result["type"] == "create_entry"
-        # The current allowlist rides along on the legacy three-key path.
-        assert result["data"][CONF_ADMIN_USER_IDS] == ["u2"]
-        assert result["data"][CONF_HORIZON_DAYS] == VALID_INPUT[CONF_HORIZON_DAYS]
-    finally:
-        _run(database.close())
-
-
-def test_options_flow_notification_section_defaults() -> None:
-    """A bare submit fills the notification section from const defaults:
-    08:00 / 15:00 / 20:00 — the report deliberately BEFORE the midnight
-    rollover sweep — an empty notify target, and all toggles enabled."""
+def test_options_flow_api_section_defaults_saved() -> None:
+    """A bare submit saves the API connection defaults: the const base
+    URL and an EMPTY panel token (no token is ever invented)."""
     flow = _make_flow(_make_entry())
     result = _run(flow.async_step_init(dict(VALID_INPUT)))
     assert result["type"] == "create_entry"
-    assert result["data"][CONF_MORNING_SUMMARY_TIME] == "08:00"
-    assert result["data"][CONF_AFTERNOON_REMINDER_TIME] == "15:00"
-    assert result["data"][CONF_END_OF_DAY_REPORT_TIME] == "20:00"
-    assert result["data"][CONF_NOTIFY_TARGET] == ""
-    for toggle in (
-        CONF_MORNING_SUMMARY_ENABLED,
-        CONF_AFTERNOON_REMINDER_ENABLED,
-        CONF_END_OF_DAY_REPORT_ENABLED,
-        CONF_CELEBRATION_ENABLED,
-    ):
-        assert result["data"][toggle] is True
+    assert result["data"][CONF_API_BASE_URL] == DEFAULT_API_BASE_URL
+    assert result["data"][CONF_PANEL_TOKEN] == ""
 
 
-def test_options_flow_notification_times_must_be_strict_hh_mm() -> None:
+def test_options_flow_api_base_url_must_be_full_http_url() -> None:
+    """Scheme-less, host-less, empty, and non-string base URLs reject
+    with a field error — the same rule the client's constructor
+    enforces, so a malformed URL fails at the form, not at the first
+    request."""
     flow = _make_flow(_make_entry())
-    for bad_time in ("9:00", "25:00", "08:0", "08-00", 800):
+    for bad_url in ("api.lan:8000", "http://", "", "   ", 42):
         result = _run(
             flow.async_step_init(
-                {
-                    **VALID_INPUT,
-                    CONF_MORNING_SUMMARY_TIME: bad_time,
-                }
+                {**VALID_INPUT, CONF_API_BASE_URL: bad_url}
             )
         )
         assert result["type"] == "form"
-        assert result["errors"] == {CONF_MORNING_SUMMARY_TIME: "invalid_time"}
+        assert result["errors"] == {CONF_API_BASE_URL: "invalid_url"}
 
 
-def test_options_flow_notify_target_validation() -> None:
-    """The empty target is VALID (it is the shipped default and must be
-    savable); only malformed non-empty values reject."""
+def test_options_flow_panel_token_validation() -> None:
+    """The EMPTY token is valid (the API connection is simply not
+    configured yet); padded and non-string values reject — a padded
+    paste would fail the token check at request time instead."""
     flow = _make_flow(_make_entry())
-    # The empty default saves cleanly.
     result = _run(
-        flow.async_step_init(
-            {**VALID_INPUT, CONF_NOTIFY_TARGET: ""}
-        )
+        flow.async_step_init({**VALID_INPUT, CONF_PANEL_TOKEN: ""})
     )
     assert result["type"] == "create_entry"
-    assert result["data"][CONF_NOTIFY_TARGET] == ""
+    assert result["data"][CONF_PANEL_TOKEN] == ""
 
-    # Malformed non-empty values reject.
-    for bad_target in ("  notify.x  ", "   ", 42):
+    for bad_token in ("  secret  ", "   ", 42):
         flow = _make_flow(_make_entry())
         result = _run(
             flow.async_step_init(
-                {
-                    **VALID_INPUT,
-                    CONF_NOTIFY_TARGET: bad_target,
-                }
+                {**VALID_INPUT, CONF_PANEL_TOKEN: bad_token}
             )
         )
         assert result["type"] == "form"
-        assert result["errors"] == {CONF_NOTIFY_TARGET: "invalid"}
+        assert result["errors"] == {CONF_PANEL_TOKEN: "invalid"}
 
 
-def test_options_flow_toggles_must_be_real_booleans() -> None:
-    flow = _make_flow(_make_entry())
-    result = _run(
-        flow.async_step_init(
-            {
-                **VALID_INPUT,
-                CONF_CELEBRATION_ENABLED: "on",
-            }
-        )
-    )
-    assert result["type"] == "form"
-    assert result["errors"] == {CONF_CELEBRATION_ENABLED: "invalid"}
-
-
-def test_options_flow_notification_stored_values_round_trip() -> None:
-    """Stored notification settings are the form's defaults and a raw
+def test_options_flow_api_section_stored_values_round_trip() -> None:
+    """Stored API settings are the form's defaults and a raw legacy
     submit without them keeps the stored values."""
     entry = _make_entry(
         options={
             **VALID_INPUT,
-            CONF_UPDATE_INTERVAL: 90,
-            CONF_NOTIFY_TARGET: "notify.mobile_app_dad",
-            CONF_MORNING_SUMMARY_TIME: "07:15",
-            CONF_AFTERNOON_REMINDER_TIME: "16:45",
-            CONF_END_OF_DAY_REPORT_TIME: "21:00",
-            CONF_MORNING_SUMMARY_ENABLED: False,
-            CONF_AFTERNOON_REMINDER_ENABLED: True,
-            CONF_END_OF_DAY_REPORT_ENABLED: False,
-            CONF_CELEBRATION_ENABLED: True,
+            CONF_API_BASE_URL: "http://panel.lan:8443",
+            CONF_PANEL_TOKEN: "stored-token",
         }
     )
     flow = _make_flow(entry)
     form = _run(flow.async_step_init(None))
     schema_defaults = form["data_schema"]({})
-    assert schema_defaults[CONF_NOTIFY_TARGET] == "notify.mobile_app_dad"
-    assert schema_defaults[CONF_MORNING_SUMMARY_TIME] == "07:15"
-    assert schema_defaults[CONF_END_OF_DAY_REPORT_ENABLED] is False
+    assert schema_defaults[CONF_API_BASE_URL] == "http://panel.lan:8443"
+    assert schema_defaults[CONF_PANEL_TOKEN] == "stored-token"
 
-    # A raw submit carrying only the legacy keys keeps the stored
-    # notification settings.
+    # A raw submit carrying only the panel-idle key keeps the stored
+    # API connection settings.
     result = _run(flow.async_step_init(dict(VALID_INPUT)))
     assert result["type"] == "create_entry"
-    assert result["data"][CONF_NOTIFY_TARGET] == "notify.mobile_app_dad"
-    assert result["data"][CONF_MORNING_SUMMARY_TIME] == "07:15"
-    assert result["data"][CONF_MORNING_SUMMARY_ENABLED] is False
-    assert result["data"][CONF_CELEBRATION_ENABLED] is True
+    assert result["data"][CONF_API_BASE_URL] == "http://panel.lan:8443"
+    assert result["data"][CONF_PANEL_TOKEN] == "stored-token"
 
 
-def test_options_flow_no_hard_coded_personal_target_in_source() -> None:
-    """The notify target's DEFAULT is the empty string: the household
-    fills their own service name, and no personal target ships as a
-    value anywhere in the const/flow defaults."""
-    from custom_components.nestquest import const
+def test_options_flow_strings_cover_api_section(
+    strings: dict, translations_en: dict
+) -> None:
+    """Both string files name the API fields and the URL error."""
+    data = strings["options"]["step"]["init"]["data"]
+    for key in (CONF_API_BASE_URL, CONF_PANEL_TOKEN):
+        assert data.get(key), f"Missing field name for '{key}'"
+    assert strings["options"]["errors"]["invalid_url"]
+    assert translations_en["options"] == strings["options"]
 
-    assert getattr(const, "CONF_NOTIFY_TARGET", None) == "notify_target"
-    # No const default carries a concrete notify service.
-    assert const.__dict__.get("DEFAULT_NOTIFY_TARGET", "") == ""
-    form = _run(_make_flow(_make_entry()).async_step_init(None))
-    assert form["data_schema"]({})[CONF_NOTIFY_TARGET] == ""
+
+# ---------------------------------------------------------------------------
+# Last-good snapshot staleness section (Feature 18)
+# ---------------------------------------------------------------------------
+
+
+def test_options_flow_staleness_below_update_interval_refused() -> None:
+    """A staleness threshold shorter than the submit's update interval
+    is refused with the dedicated error: such a threshold could never
+    serve even one cached snapshot."""
+    flow = _make_flow(_make_entry())
+    result = _run(
+        flow.async_step_init(
+            {
+                **VALID_INPUT,
+                CONF_UPDATE_INTERVAL: 300,
+                CONF_SNAPSHOT_STALENESS: 60,
+            }
+        )
+    )
+    assert result["type"] == "form"
+    assert result["errors"] == {CONF_SNAPSHOT_STALENESS: "invalid_staleness"}
+
+
+def test_options_flow_staleness_below_stored_interval_refused() -> None:
+    """A raw submit setting the staleness but omitting the update
+    interval is checked against the STORED interval, not the default."""
+    entry = _make_entry(options={CONF_UPDATE_INTERVAL: 300})
+    flow = _make_flow(entry)
+    result = _run(
+        flow.async_step_init({**VALID_INPUT, CONF_SNAPSHOT_STALENESS: 60})
+    )
+    assert result["type"] == "form"
+    assert result["errors"] == {CONF_SNAPSHOT_STALENESS: "invalid_staleness"}
+
+
+def test_options_flow_staleness_must_be_positive_int() -> None:
+    """Non-int, boolean, and non-positive staleness values reject with
+    the plain invalid error."""
+    flow = _make_flow(_make_entry())
+    for bad_staleness in ("900", True, 0, -10):
+        result = _run(
+            flow.async_step_init(
+                {**VALID_INPUT, CONF_SNAPSHOT_STALENESS: bad_staleness}
+            )
+        )
+        assert result["type"] == "form"
+        assert result["errors"] == {CONF_SNAPSHOT_STALENESS: "invalid"}
+
+
+def test_options_flow_staleness_equal_to_interval_saves() -> None:
+    """A threshold exactly as long as the update interval is valid (the
+    boundary is inclusive)."""
+    flow = _make_flow(_make_entry())
+    result = _run(
+        flow.async_step_init(
+            {
+                **VALID_INPUT,
+                CONF_UPDATE_INTERVAL: 300,
+                CONF_SNAPSHOT_STALENESS: 300,
+            }
+        )
+    )
+    assert result["type"] == "create_entry"
+    assert result["data"][CONF_SNAPSHOT_STALENESS] == 300
+
+
+def test_options_flow_staleness_defaults_saved() -> None:
+    """A bare submit saves the staleness default (three update
+    intervals) alongside the other defaults."""
+    flow = _make_flow(_make_entry())
+    result = _run(flow.async_step_init(dict(VALID_INPUT)))
+    assert result["type"] == "create_entry"
+    assert result["data"][CONF_SNAPSHOT_STALENESS] == DEFAULT_SNAPSHOT_STALENESS
+
+
+def test_options_flow_staleness_stored_values_round_trip() -> None:
+    """A stored staleness is the form's default and a raw legacy submit
+    without it keeps the stored value."""
+    entry = _make_entry(
+        options={
+            **VALID_INPUT,
+            CONF_UPDATE_INTERVAL: 300,
+            CONF_SNAPSHOT_STALENESS: 1200,
+        }
+    )
+    flow = _make_flow(entry)
+    form = _run(flow.async_step_init(None))
+    schema_defaults = form["data_schema"]({})
+    assert schema_defaults[CONF_SNAPSHOT_STALENESS] == 1200
+
+    # A raw submit carrying only the panel-idle key keeps the stored
+    # staleness (and never trips the interval cross-check).
+    result = _run(flow.async_step_init(dict(VALID_INPUT)))
+    assert result["type"] == "create_entry"
+    assert result["data"][CONF_SNAPSHOT_STALENESS] == 1200
+
+
+def test_options_flow_strings_cover_staleness_section(
+    strings: dict, translations_en: dict
+) -> None:
+    """Both string files name the staleness field and its error."""
+    data = strings["options"]["step"]["init"]["data"]
+    assert data.get(CONF_SNAPSHOT_STALENESS), (
+        f"Missing field name for '{CONF_SNAPSHOT_STALENESS}'"
+    )
+    assert strings["options"]["errors"]["invalid_staleness"]
+    assert translations_en["options"] == strings["options"]

tests/test_panel_cards.py

@@ -5,16 +5,27 @@ the contract by reading the card sources and the built bundle, in the same
 spirit as test_frontend.py. They cover the states decided in
 design/PANEL-EMPTY-STATES.md and PANEL-SPEC.md, and guard the kid-facing
 bundles against ever gaining a parent-only service call.
+
+The party board additionally has render tests: they drive
+frontend/tests/render-party-board.mjs, which imports the built bundle into a
+jsdom window and reports the ordered plates the shadow DOM renders, so the
+zero-config discovery contract is asserted against the bundle HACS ships.
 """
 from __future__ import annotations
 
+import json
+import subprocess
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).parent.parent
-FRONTEND_CARDS_DIR = REPO_ROOT / "frontend" / "src" / "cards"
+FRONTEND_DIR = REPO_ROOT / "frontend"
+FRONTEND_CARDS_DIR = FRONTEND_DIR / "src" / "cards"
 PARTY_BOARD = FRONTEND_CARDS_DIR / "party-board.ts"
 QUEST_LOG = FRONTEND_CARDS_DIR / "quest-log.ts"
 BUNDLE_PATH = REPO_ROOT / "custom_components" / "nestquest" / "www" / "nestquest-cards.js"
+RENDER_HARNESS = FRONTEND_DIR / "tests" / "render-party-board.mjs"
+STRATEGY_HARNESS = FRONTEND_DIR / "tests" / "render-strategy.mjs"
+STRATEGY_SOURCE = FRONTEND_DIR / "src" / "strategy.ts"
 
 PANEL_SOURCES = (PARTY_BOARD, QUEST_LOG)
 
@@ -157,4 +168,281 @@ def test_panel_cards_reference_no_admin_only_services() -> None:
     assert BUNDLE_PATH.is_file()
     bundle = _read(BUNDLE_PATH)
     assert "nestquest-party-board-card" in bundle
-    assert "nestquest-quest-log-card" in bundle
+    assert "nestquest-quest-log-card" in bundle
+
+
+def test_party_board_discovers_children_from_the_household_roster() -> None:
+    """Feature 20: with no child_order configured, the board discovers
+    the ordered child slugs from the household rollup's child_roster
+    attribute; explicit configuration still wins."""
+    source = _read(PARTY_BOARD)
+    assert "child_roster" in source
+    assert "sensor.nestquest_household_quests_due_today" in source
+    # Discovery only fills in for a MISSING child_order; a supplied
+    # order array is honoured verbatim before the discovered list is
+    # ever consulted.
+    assert "Array.isArray(order)" in source
+    assert "_discoveredChildSlugs()" in source
+
+
+# --- Render tests (built bundle under jsdom) ---------------------------------
+
+#: The seeded three-child household, in the API's sort order: Ada and
+#: Bo share one daily quest (Bo is away today), Cory has none.
+ROSTER = [
+    {"child_id": 1, "name": "Ada", "slug": "ada"},
+    {"child_id": 2, "name": "Bo", "slug": "bo"},
+    {"child_id": 3, "name": "Cory", "slug": "cory"},
+]
+
+
+def _state(state: str, **attributes) -> dict:
+    return {"state": state, "attributes": attributes}
+
+
+def _three_child_states() -> dict:
+    """The hass states a three-child household exposes.
+
+    Entity ids follow the documented naming contract
+    (design/ENTITIES-AND-SERVICES.md §1): the household rollup and the
+    per-child sensors slugged from the child names.
+    """
+    return {
+        "sensor.nestquest_household_quests_due_today": _state(
+            "2",
+            children={"1": 1, "2": 1, "3": 0},
+            child_roster=ROSTER,
+        ),
+        "sensor.nestquest_ada_quests_due_today": _state(
+            "1", child_name="Ada", present=True
+        ),
+        "sensor.nestquest_ada_quests_completed_today": _state("0"),
+        "sensor.nestquest_ada_completion_pct_today": _state("0"),
+        "binary_sensor.nestquest_ada_present_today": _state("on"),
+        "sensor.nestquest_bo_quests_due_today": _state(
+            "1", child_name="Bo", present=False
+        ),
+        "sensor.nestquest_bo_quests_completed_today": _state("0"),
+        "sensor.nestquest_bo_completion_pct_today": _state("0"),
+        "binary_sensor.nestquest_bo_present_today": _state("off"),
+        "sensor.nestquest_cory_quests_due_today": _state(
+            "0", child_name="Cory", present=True
+        ),
+        "sensor.nestquest_cory_quests_completed_today": _state("0"),
+        "sensor.nestquest_cory_completion_pct_today": _state("100"),
+        "binary_sensor.nestquest_cory_present_today": _state("on"),
+    }
+
+
+def _render_party_board(config: dict, states: dict) -> dict:
+    """Render the built bundle's party board and return its plates.
+
+    Drives frontend/tests/render-party-board.mjs: the harness imports
+    the committed bundle (the artifact HACS ships) into a jsdom window,
+    mounts the card with the given config and hass snapshot, and prints
+    the ordered plates its shadow DOM renders.
+    """
+    assert BUNDLE_PATH.is_file(), "bundle missing: run cd frontend && npm run build"
+    assert RENDER_HARNESS.is_file()
+    spec = {
+        "bundle": str(BUNDLE_PATH),
+        "tag": "nestquest-party-board-card",
+        "config": config,
+        "hass": {"config": {"time_zone": "UTC"}, "states": states},
+    }
+    completed = subprocess.run(
+        ["node", str(RENDER_HARNESS)],
+        input=json.dumps(spec),
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    assert completed.returncode == 0, (
+        f"render harness failed: {completed.stderr}"
+    )
+    return json.loads(completed.stdout)
+
+
+def test_party_board_renders_discovered_children_in_sort_order() -> None:
+    """No child_order key: three plates render in the roster's sort
+    order (the coordinator snapshot's order), one per child."""
+    result = _render_party_board(
+        {"type": "custom:nestquest-party-board-card"},
+        _three_child_states(),
+    )
+    assert result["plates"] == [
+        {"name": "Ada", "kind": "present"},
+        {"name": "Bo", "kind": "away"},
+        {"name": "Cory", "kind": "present"},
+    ]
+
+
+def test_explicit_child_order_still_wins_over_discovery() -> None:
+    """A supplied child_order keeps working: it overrides the household
+    roster's order and limits the plates to the configured slugs."""
+    result = _render_party_board(
+        {
+            "type": "custom:nestquest-party-board-card",
+            "child_order": ["bo", "ada"],
+        },
+        _three_child_states(),
+    )
+    assert [plate["name"] for plate in result["plates"]] == ["Bo", "Ada"]
+    assert "Cory" not in [plate["name"] for plate in result["plates"]]
+
+# --- Dashboard strategy tests -------------------------------------------------
+
+STRATEGY_NAME = "nestquest-party"
+
+
+def _generate_dashboard(config: dict, states: dict, url: str | None = None) -> dict:
+    """Generate the strategy's dashboard from the built bundle.
+
+    Drives frontend/tests/render-strategy.mjs: the harness imports the
+    committed bundle into a jsdom window at the given dashboard URL and
+    prints the views ``window.customStrategies["nestquest-party"].
+    generate(config, hass)`` returns.
+    """
+    assert BUNDLE_PATH.is_file(), "bundle missing: run cd frontend && npm run build"
+    assert STRATEGY_HARNESS.is_file()
+    spec = {
+        "bundle": str(BUNDLE_PATH),
+        "url": url or "http://homeassistant.local/nestquest/party",
+        "config": config,
+        "hass": {"config": {"time_zone": "UTC"}, "states": states},
+    }
+    completed = subprocess.run(
+        ["node", str(STRATEGY_HARNESS)],
+        input=json.dumps(spec),
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    assert completed.returncode == 0, (
+        f"strategy harness failed: {completed.stderr}"
+    )
+    return json.loads(completed.stdout)
+
+
+def test_strategy_is_registered_on_the_bundle() -> None:
+    """The strategy ships in the same bundle as the cards and registers
+    itself under window.customStrategies so a dashboard can use
+    strategy: { type: custom:nestquest-party }."""
+    source = _read(STRATEGY_SOURCE)
+    assert "customStrategies" in source
+    assert f'["{STRATEGY_NAME}"]' in source or f'"{STRATEGY_NAME}"' in source
+    bundle = _read(BUNDLE_PATH)
+    assert "nestquest-party" in bundle
+
+
+def test_strategy_generates_views_for_three_children() -> None:
+    """For the seeded three-child household the strategy generates one
+    party-board view plus one quest-log view per child in roster order,
+    with COMPUTED paths: the board view at the dashboard root, each log
+    view at the child's slug so quest-log.ts's childSlugFromPath reads
+    the child from the URL's last segment."""
+    result = _generate_dashboard({}, _three_child_states())
+    views = result["views"]
+    assert len(views) == 4
+    assert [view["path"] for view in views] == [
+        "party",
+        "ada",
+        "bo",
+        "cory",
+    ]
+    assert [view["title"] for view in views] == [
+        "The Party",
+        "Ada's Quest Log",
+        "Bo's Quest Log",
+        "Cory's Quest Log",
+    ]
+
+
+def test_strategy_every_view_is_panel_type() -> None:
+    """Every generated view carries ``type: "panel"``: Home Assistant
+    defaults an unspecified view to Masonry, which constrains the
+    1080px-tall NestQuest card to a narrow column (README's TouchHub
+    setup warns of exactly this); with a generated dashboard there is
+    no editor step left to set Panel by hand."""
+    result = _generate_dashboard({}, _three_child_states())
+    for view in result["views"]:
+        assert view["type"] == "panel"
+
+
+def test_strategy_log_view_titles_use_the_roster_display_name() -> None:
+    """Quest-log view titles come from the roster's ``name`` field (the
+    child's display name), not the lowercased entity-id slug; the slug
+    stays the view's path."""
+    result = _generate_dashboard(
+        {},
+        {
+            "sensor.nestquest_household_quests_due_today": _state(
+                "0",
+                child_roster=[
+                    {"child_id": 7, "name": "Milo", "slug": "milo"},
+                ],
+            ),
+        },
+    )
+    views = result["views"]
+    assert len(views) == 2
+    assert views[1]["path"] == "milo"
+    assert views[1]["title"] == "Milo's Quest Log"
+
+
+def test_strategy_passes_weather_entity_through_to_the_cards() -> None:
+    """An explicit ``weather_entity`` in the strategy configuration is
+    passed through to the generated card configs (both the board and
+    the quest log render the weather dock when it is set)."""
+    result = _generate_dashboard(
+        {"weather_entity": "weather.home"},
+        _three_child_states(),
+    )
+    views = result["views"]
+    for view in views:
+        assert view["cards"][0]["weather_entity"] == "weather.home"
+    # And without it, no weather_entity key is emitted at all.
+    unset = _generate_dashboard({}, _three_child_states())
+    for view in unset["views"]:
+        assert "weather_entity" not in view["cards"][0]
+
+
+def test_strategy_wires_navigation_between_the_views() -> None:
+    """The board's quest_log_path and each log's board_path are computed
+    to the dashboard root the strategy renders at, so party-board.ts's
+    crest tap pushes <root>/<slug> and quest-log.ts's idle return goes
+    back to the board — neither path is configured by hand."""
+    dashboard_url = "http://homeassistant.local/nestquest"
+    root = "/nestquest"
+    result = _generate_dashboard(
+        {}, _three_child_states(), url=dashboard_url
+    )
+    views = result["views"]
+    board = views[0]["cards"][0]
+    assert board["type"] == "custom:nestquest-party-board-card"
+    assert board["quest_log_path"] == root
+    for slug, view in zip(("ada", "bo", "cory"), views[1:]):
+        assert view["cards"][0]["type"] == "custom:nestquest-quest-log-card"
+        assert view["cards"][0]["board_path"] == root
+
+
+def test_strategy_zero_children_still_generates_the_board() -> None:
+    """With an empty roster (NestQuest not set up yet) the strategy
+    renders the board view alone — the board card shows its own
+    "not set up yet" notice for an empty roster — and never crashes."""
+    result = _generate_dashboard({}, {})
+    assert len(result["views"]) == 1
+    assert result["views"][0]["path"] == "party"
+
+
+def test_strategy_config_overrides_still_apply() -> None:
+    """Explicit strategy configuration wins where the design allows: an
+    explicit url_path pins the computed dashboard root."""
+    result = _generate_dashboard(
+        {"url_path": "/wallboard"},
+        _three_child_states(),
+    )
+    root = "/wallboard"
+    assert result["views"][0]["cards"][0]["quest_log_path"] == root
+    for view in result["views"][1:]:
+        assert view["cards"][0]["board_path"] == root

tests/test_permission_matrix.py

@@ -1,238 +0,0 @@
-"""Feature 09 permission test matrix across every registered service."""
-from __future__ import annotations
-
-import datetime
-
-import pytest
-from homeassistant.exceptions import Unauthorized
-
-from conftest import wire_entry_to_registry
-
-from custom_components.nestquest import async_setup_entry
-from custom_components.nestquest.const import (
-    CONF_ADMIN_USER_IDS,
-    DEFAULT_HORIZON_DAYS,
-    DOMAIN,
-    DOMAIN_SERVICES,
-    SERVICE_COMPLETE_QUEST,
-    SERVICE_CREATE_PRESENCE_OVERRIDE,
-    SERVICE_CREATE_QUEST_DEFINITION,
-    SERVICE_DELETE_PRESENCE_OVERRIDE,
-    SERVICE_EXPORT_HISTORY_CSV,
-    SERVICE_MANAGE_CHILD,
-    SERVICE_REGENERATE,
-    SERVICE_SET_PRESENCE_PATTERN,
-    SERVICE_SET_QUEST_DEFINITION_ACTIVE,
-    SERVICE_UNCOMPLETE_QUEST,
-    SERVICE_UPDATE_QUEST_DEFINITION,
-)
-from custom_components.nestquest.service_policy import (
-    ADMIN_ONLY,
-    OPEN,
-    SERVICE_POLICY,
-)
-
-ADMIN_ID = "admin-1"
-ADMIN_CTX = {"user_id": ADMIN_ID}
-NON_ADMIN_ID = "non-admin"
-NON_ADMIN_CTX = {"user_id": NON_ADMIN_ID}
-KIOSK_ID = "kiosk-panel"
-KIOSK_CTX = {"user_id": KIOSK_ID}
-
-
-def test_every_registered_service_is_in_the_operation_registry() -> None:
-    """The registry is total: a service outside it could never be gated."""
-    missing = [
-        service for service in DOMAIN_SERVICES if service not in SERVICE_POLICY
-    ]
-    extra = [
-        service for service in SERVICE_POLICY if service not in DOMAIN_SERVICES
-    ]
-    assert not missing, f"registered but ungated: {missing}"
-    assert not extra, f"gated but never registered: {extra}"
-    assert set(SERVICE_POLICY.values()) == {OPEN, ADMIN_ONLY}
-
-
-async def _setup(hass, make_entry, *, admin=True):
-    data = {CONF_ADMIN_USER_IDS: [ADMIN_ID]} if admin else {}
-    entry = wire_entry_to_registry(make_entry(data=data), hass.registry)
-    assert await async_setup_entry(hass, entry) is True
-    return entry
-
-
-async def _seed(hass, entry) -> dict:
-    """Seed one child, one definition, and materialized instances."""
-    from custom_components.nestquest.children import list_children
-    from custom_components.nestquest.dao_instances import QuestInstancesDao
-
-    database = entry.runtime_data.database
-    await hass.services.call(
-        DOMAIN,
-        SERVICE_MANAGE_CHILD,
-        {"action": "create", "display_name": "Ada"},
-        context=ADMIN_CTX,
-    )
-    await hass.services.call(
-        DOMAIN,
-        SERVICE_CREATE_QUEST_DEFINITION,
-        {
-            "title": "Brush teeth",
-            "rule": {"rule_type": "daily"},
-            "assignee_child_ids": [(await list_children(database))[0].id],
-            "windows": ["morning"],
-        },
-        context=ADMIN_CTX,
-    )
-    await hass.services.call(DOMAIN, SERVICE_REGENERATE, context=ADMIN_CTX)
-    child = (await list_children(database))[0]
-    today = datetime.date.today().isoformat()
-    end = (
-        datetime.date.today() + datetime.timedelta(days=DEFAULT_HORIZON_DAYS)
-    ).isoformat()
-    instances = await QuestInstancesDao(database).list_by_date_range(
-        child.id, today, end
-    )
-    assert instances
-    from custom_components.nestquest.dao_presence import (
-        PresenceOverridesDao,
-    )
-
-    return {
-        "child_id": child.id,
-        "instance_id": instances[0].id,
-        "definition_id": instances[0].definition_id,
-        "override": await PresenceOverridesDao(database).create(
-            child.id, "2027-01-01", "2027-01-02", False
-        ),
-        "today": today,
-        "database": database,
-    }
-
-
-def _admin_success_payload(service: str, ctx: dict) -> dict | None:
-    """A schema-valid, end-to-end-successful payload per admin service."""
-    if service == SERVICE_UNCOMPLETE_QUEST:
-        return {"instance_id": ctx["instance_id"], "actor": "user"}
-    if service == SERVICE_CREATE_QUEST_DEFINITION:
-        return {
-            "title": "Second quest",
-            "rule": {"rule_type": "daily"},
-            "assignee_child_ids": [ctx["child_id"]],
-            "windows": ["afternoon"],
-        }
-    if service == SERVICE_UPDATE_QUEST_DEFINITION:
-        return {"definition_id": ctx["definition_id"], "title": "Brush teeth 2"}
-    if service == SERVICE_SET_QUEST_DEFINITION_ACTIVE:
-        return {"definition_id": ctx["definition_id"], "is_active": False}
-    if service == SERVICE_SET_PRESENCE_PATTERN:
-        return {
-            "child_id": ctx["child_id"],
-            "cycle_length_weeks": 1,
-            "anchor_date": ctx["today"],
-            "pattern": {0: [0, 1, 2, 3, 4, 5, 6]},
-        }
-    if service == SERVICE_CREATE_PRESENCE_OVERRIDE:
-        return {
-            "child_id": ctx["child_id"],
-            "start_date": "2027-03-01",
-            "end_date": "2027-03-02",
-            "is_present": False,
-        }
-    if service == SERVICE_DELETE_PRESENCE_OVERRIDE:
-        return {"override_id": ctx["override"].id}
-    if service == SERVICE_EXPORT_HISTORY_CSV:
-        return None  # raises HomeAssistantError (Feature 13) — not Unauthorized
-    if service == SERVICE_MANAGE_CHILD:
-        return {"action": "create", "display_name": "Bo"}
-    if service == SERVICE_REGENERATE:
-        return {}
-    raise AssertionError(f"unexpected service {service}")
-
-
-_ADMIN_ONLY = [
-    service for service, policy in SERVICE_POLICY.items() if policy == ADMIN_ONLY
-]
-
-
-@pytest.mark.parametrize("service", _ADMIN_ONLY)
-async def test_admin_succeeds_on_every_admin_only_service(
-    hass, make_entry, service
-) -> None:
-    from homeassistant.exceptions import HomeAssistantError
-
-    entry = await _setup(hass, make_entry)
-    ctx = await _seed(hass, entry)
-    if service == SERVICE_EXPORT_HISTORY_CSV:
-        # The gate passes; the Feature 13 stub raises its "not
-        # implemented" HomeAssistantError — NOT Unauthorized.
-        with pytest.raises(HomeAssistantError, match="Feature 13"):
-            await hass.services.call(
-                DOMAIN, service, None, context=ADMIN_CTX
-            )
-        return
-    await hass.services.call(
-        DOMAIN, service, _admin_success_payload(service, ctx), context=ADMIN_CTX
-    )
-
-
-@pytest.mark.parametrize("service", _ADMIN_ONLY)
-async def test_non_admin_refused_on_every_admin_only_service(
-    hass, make_entry, service
-) -> None:
-    entry = await _setup(hass, make_entry)
-    ctx = await _seed(hass, entry)
-    if service != SERVICE_EXPORT_HISTORY_CSV:
-        await hass.services.call(
-            DOMAIN,
-            service,
-            _admin_success_payload(service, ctx),
-            context=ADMIN_CTX,
-        )
-    with pytest.raises(Unauthorized):
-        await hass.services.call(
-            DOMAIN,
-            service,
-            _admin_success_payload(service, ctx),
-            context=NON_ADMIN_CTX,
-        )
-
-
-async def test_non_admin_allowed_on_complete_quest(hass, make_entry) -> None:
-    from custom_components.nestquest.completion import instance_state
-
-    entry = await _setup(hass, make_entry)
-    ctx = await _seed(hass, entry)
-    await hass.services.call(
-        DOMAIN,
-        SERVICE_COMPLETE_QUEST,
-        {
-            "instance_id": ctx["instance_id"],
-            "actor": "panel",
-            "actor_child_id": ctx["child_id"],
-        },
-        context=NON_ADMIN_CTX,
-    )
-    assert (
-        await instance_state(ctx["database"], ctx["instance_id"]) == "done"
-    )
-
-
-async def test_kiosk_refused_on_uncomplete_and_regenerate(
-    hass, make_entry
-) -> None:
-    entry = await _setup(hass, make_entry)
-    ctx = await _seed(hass, entry)
-    from custom_components.nestquest.admin_allowlist import list_admin_ids
-
-    assert KIOSK_ID not in await list_admin_ids(ctx["database"])
-    with pytest.raises(Unauthorized):
-        await hass.services.call(
-            DOMAIN,
-            SERVICE_UNCOMPLETE_QUEST,
-            {"instance_id": ctx["instance_id"], "actor": "user"},
-            context=KIOSK_CTX,
-        )
-    with pytest.raises(Unauthorized):
-        await hass.services.call(
-            DOMAIN, SERVICE_REGENERATE, context=KIOSK_CTX
-        )

tests/test_permissions.py

@@ -1,122 +0,0 @@
-"""Tests for the Feature 09 permission gate's audit logging."""
-from __future__ import annotations
-
-import logging
-import re
-
-import pytest
-from homeassistant.exceptions import Unauthorized
-
-from conftest import wire_entry_to_registry
-
-from custom_components.nestquest import async_setup_entry
-from custom_components.nestquest.const import (
-    CONF_ADMIN_USER_IDS,
-    DOMAIN,
-    SERVICE_MANAGE_CHILD,
-)
-
-ADMIN_ID = "admin-1"
-ADMIN_CTX = {"user_id": ADMIN_ID}
-_TIMESTAMP = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}")
-
-
-async def _set_up(hass, make_entry):
-    entry = wire_entry_to_registry(
-        make_entry(data={CONF_ADMIN_USER_IDS: [ADMIN_ID]}), hass.registry
-    )
-    assert await async_setup_entry(hass, entry) is True
-    return entry
-
-
-async def test_denied_call_logs_warning_with_fields(
-    hass, make_entry, caplog
-) -> None:
-    entry = await _set_up(hass, make_entry)
-    with pytest.raises(Unauthorized):
-        await hass.services.call(
-            DOMAIN,
-            SERVICE_MANAGE_CHILD,
-            {"action": "create", "display_name": "Ada"},
-            context={"user_id": "kiosk-panel"},
-        )
-    denials = [
-        record
-        for record in caplog.records
-        if record.levelno == logging.WARNING
-        and "denied" in record.getMessage()
-    ]
-    assert len(denials) == 1
-    message = denials[0].getMessage()
-    assert SERVICE_MANAGE_CHILD in message
-    assert "kiosk-panel" in message
-    assert _TIMESTAMP.search(message), message
-
-
-async def test_denied_no_context_logs_user_none(
-    hass, make_entry, caplog
-) -> None:
-    entry = await _set_up(hass, make_entry)
-    with pytest.raises(Unauthorized):
-        await hass.services.call(
-            DOMAIN,
-            SERVICE_MANAGE_CHILD,
-            {"action": "create", "display_name": "Ada"},
-        )
-    denials = [
-        record
-        for record in caplog.records
-        if record.levelno == logging.WARNING
-        and "denied" in record.getMessage()
-    ]
-    assert len(denials) == 1
-    message = denials[0].getMessage()
-    assert "none" in message
-    assert _TIMESTAMP.search(message), message
-
-
-async def test_successful_admin_call_logs_debug_with_fields(
-    hass, make_entry, caplog
-) -> None:
-    caplog.set_level(logging.DEBUG, logger="custom_components.nestquest")
-    entry = await _set_up(hass, make_entry)
-    await hass.services.call(
-        DOMAIN,
-        SERVICE_MANAGE_CHILD,
-        {"action": "create", "display_name": "Ada"},
-        context=ADMIN_CTX,
-    )
-    allowed = [
-        record
-        for record in caplog.records
-        if record.levelno == logging.DEBUG
-        and "allowed" in record.getMessage()
-    ]
-    assert len(allowed) == 1
-    message = allowed[0].getMessage()
-    assert SERVICE_MANAGE_CHILD in message
-    assert ADMIN_ID in message
-    assert _TIMESTAMP.search(message), message
-
-
-async def test_denied_log_carries_no_personal_data_beyond_user_id(
-    hass, make_entry, caplog
-) -> None:
-    """The log line names the caller's user id only: the payload's
-    display name must not leak into the audit trail."""
-    entry = await _set_up(hass, make_entry)
-    with pytest.raises(Unauthorized):
-        await hass.services.call(
-            DOMAIN,
-            SERVICE_MANAGE_CHILD,
-            {"action": "create", "display_name": "Ada"},
-            context={"user_id": "kiosk-panel"},
-        )
-    denials = [
-        record.getMessage()
-        for record in caplog.records
-        if record.levelno == logging.WARNING and "denied" in record.getMessage()
-    ]
-    assert denials, "expected a denial log line"
-    assert "Ada" not in denials[0]
-    assert "display_name" not in denials[0]

tests/test_presence.py

@@ -5,7 +5,7 @@ import datetime
 
 import pytest
 
-from custom_components.nestquest.presence import (
+from custom_components.nestquest.core.presence import (
     MAX_CYCLE_LENGTH_WEEKS,
     PresenceEngine,
     PresenceOverride,

tests/test_quest_definitions.py

@@ -7,20 +7,20 @@ import re
 
 import pytest
 
-from custom_components.nestquest.dao_children import ChildrenDao
+from custom_components.nestquest.core.dao_children import ChildrenDao
 from custom_components.nestquest.const import DEFAULT_HORIZON_DAYS
-from custom_components.nestquest.dao_instances import (
+from custom_components.nestquest.core.dao_instances import (
     CompletionEventsDao,
     QuestInstancesDao,
 )
-from custom_components.nestquest.dao_rules import (
+from custom_components.nestquest.core.dao_rules import (
     QuestDefinitionsDao,
     ScheduleRulesDao,
     schedule_rule_to_storage,
 )
-from custom_components.nestquest.db import NestQuestDatabase
-from custom_components.nestquest.migrations import apply_migrations
-from custom_components.nestquest.quest_definitions import (
+from custom_components.nestquest.core.db import NestQuestDatabase
+from custom_components.nestquest.core.migrations import apply_migrations
+from custom_components.nestquest.core.quest_definitions import (
     CreatedQuestDefinition,
     assign_child,
     create_quest_definition,
@@ -31,7 +31,7 @@ from custom_components.nestquest.quest_definitions import (
     set_quest_definition_active,
     unassign_child,
 )
-from custom_components.nestquest.recurrence import RuleType, ScheduleRule
+from custom_components.nestquest.core.recurrence import RuleType, ScheduleRule
 
 
 def _run(coro):
@@ -1150,7 +1150,7 @@ def test_concurrent_assign_unassign_returns_consistent_roster(
         )
         bo = await children.create("Bo", NOW)
 
-        import custom_components.nestquest.dao_rules as dao_rules
+        import custom_components.nestquest.core.dao_rules as dao_rules
 
         original_list = dao_rules.QuestDefinitionsDao.list_assignees
         started = asyncio.Event()
@@ -1666,7 +1666,7 @@ def test_list_query_snapshot_coherent_under_racing_edit(tmp_path) -> None:
             start_date="2026-09-14",
         )
 
-        import custom_components.nestquest.dao_rules as dao_rules
+        import custom_components.nestquest.core.dao_rules as dao_rules
 
         original_list = dao_rules.QuestDefinitionsDao.list_windows
         started = asyncio.Event()
@@ -1732,7 +1732,7 @@ def test_list_definitions_for_child_snapshot_coherent_under_racing_unassign(
             database, "Brush teeth", _daily_rule(), [child.id], ["morning"]
         )
 
-        import custom_components.nestquest.dao_rules as dao_rules
+        import custom_components.nestquest.core.dao_rules as dao_rules
 
         original_list = dao_rules.QuestDefinitionsDao.list_assignees
         started = asyncio.Event()
@@ -1795,7 +1795,7 @@ def test_list_active_definitions_snapshot_coherent_under_racing_edit(
             start_date="2026-09-14",
         )
 
-        import custom_components.nestquest.dao_rules as dao_rules
+        import custom_components.nestquest.core.dao_rules as dao_rules
 
         original_list = dao_rules.QuestDefinitionsDao.list_windows
         started = asyncio.Event()

tests/test_recurrence_bounds.py

@@ -12,7 +12,7 @@ import datetime
 
 import pytest
 
-from custom_components.nestquest.recurrence import (
+from custom_components.nestquest.core.recurrence import (
     RuleType,
     RuleValidationError,
     ScheduleRule,

tests/test_recurrence_consolidated.py

@@ -15,7 +15,7 @@ import datetime
 
 import pytest
 
-from custom_components.nestquest.recurrence import (
+from custom_components.nestquest.core.recurrence import (
     ScheduleRule,
     RuleType,
     occurs_on,
@@ -395,7 +395,7 @@ def test_recurrence_engine_imports_nothing_forbidden() -> None:
 
     module_file = Path(
         importlib.util.find_spec(
-            "custom_components.nestquest.recurrence"
+            "custom_components.nestquest.core.recurrence"
         ).origin
     )
     tree = ast.parse(module_file.read_text())

tests/test_recurrence_daily.py

@@ -5,7 +5,7 @@ import datetime
 
 import pytest
 
-from custom_components.nestquest.recurrence import (
+from custom_components.nestquest.core.recurrence import (
     RuleType,
     RuleValidationError,
     ScheduleRule,
@@ -219,7 +219,7 @@ def test_occurs_on_rejects_unknown_shapes_loudly() -> None:
     than a silent wrong answer.  Forged via a private enum extension
     because ScheduleRule validation rejects unknown names."""
     import enum as enum_module
-    from custom_components.nestquest import recurrence as mod
+    from custom_components.nestquest.core import recurrence as mod
 
     ForgedType = enum_module.Enum(
         "ForgedType", {"UNKNOWN_SHAPE": "unknown_shape"}

tests/test_recurrence_model.py

@@ -5,7 +5,7 @@ import datetime
 
 import pytest
 
-from custom_components.nestquest.recurrence import (
+from custom_components.nestquest.core.recurrence import (
     RuleType,
     RuleValidationError,
     ScheduleRule,
@@ -344,12 +344,12 @@ def test_purity_guard_logic_catches_probe_statements(tmp_path) -> None:
         "from homeassistant.core import HomeAssistant",
         "import sqlite3",
         "from .db import NestQuestDatabase",
-        "from custom_components.nestquest.db import NestQuestDatabase",
+        "from custom_components.nestquest.core.db import NestQuestDatabase",
         "from custom_components.nestquest import db",
-        "import custom_components.nestquest.dao_rules",
+        "import custom_components.nestquest.core.dao_rules",
         "from . import db",
         "from . import schema",
-        "from custom_components.nestquest.migrations import apply_migrations",
+        "from custom_components.nestquest.core.migrations import apply_migrations",
     ]
     for probe in probes:
         offenders = _scan_forbidden_imports(probe)