Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(home): tell a person whether their dark house is their fault or ours

nirholas80ccee779711
diff --git a/prompts/finish/home-13-observability.md b/prompts/finish/home-13-observability.md
deleted file mode 100644
index dc688d7af..000000000
--- a/prompts/finish/home-13-observability.md
+++ /dev/null
@@ -1,152 +0,0 @@
-# 13. Observability, SLOs, alerting, incident runbook
-
-**How to run this:** paste this whole file into a fresh Claude Code chat opened in
-`/workspaces/three.ws`. Read [00-CONTEXT.md](home-00-CONTEXT.md) first. Orders
-[02](home-02-bridge-runtime.md) and [03](home-03-api-surface.md) must have landed.
-
-## Binding operating clause
-
-Finish 100%. Never end with a question or an unexecuted plan. All CLAUDE.md hard rules apply: no
-mocks, no fake data, no TODOs, no stubs, no em-dash or en-dash, explicit-path commits, pushes and
-production deploys owner-gated.
-
-**Nothing in this file is a status claim to trust.** Step 0 re-measures.
-
----
-
-## Step 0: re-derive the current state
-
-```bash
-sed -n '1,30p' api/healthz.js
-grep -n "export function classify\|export async function gather" api/_lib/ops/subsystem-health.js | head -20
-grep -n "^export" api/_lib/alerts.js
-node -e "console.log(require('./vercel.json').crons.length)"
-curl -s https://three.ws/api/healthz | head -c 400
-```
-
-The platform already has a subsystem-health pattern (`api/_lib/ops/subsystem-health.js`, surfaced
-by `api/healthz.js` and `api/status.js`) and an alerting path (`sendOpsAlert`). **Extend both.
-Do not build a second health endpoint or a second alert channel.**
-
-## What "down" means for this lane, and why it is unusual
-
-Most outages here are not ours. A user's house is offline, their token expired, their internet
-dropped. Those are per-tenant conditions that must never page anyone and must always be visible
-to that one user. Conversely, "every home went unreachable in the last five minutes" is an
-outage, and it looks identical at the level of a single connection.
-
-**The whole design of this order is separating the two.** A per-tenant failure is a UI state; a
-correlated failure across tenants is an alert.
-
-## The signals
-
-Add a `home` subsystem to `gatherSubsystemHealth`, classified the way its siblings are:
-
-| Signal | Source | Green | Yellow | Red |
-|---|---|---|---|---|
-| Connected homes | `runtime.stats()` aggregated | any | n/a | n/a (a count, not a verdict) |
-| Handshake success rate, 15 min | `home_connections.last_ok_at` / `last_error_at` | over 95% | 80 to 95% | under 80% |
-| Breaker-open homes | runtime | under 2% | 2 to 10% | over 10% |
-| Action success rate, 15 min | `home_action_log.outcome` | over 98% | 95 to 98% | under 95% |
-| Confirmation expiry rate | `home_confirmations` | under 20% | 20 to 40% | over 40% (the UI is failing people) |
-| SSE subscriber leak | `stats().subscribers` versus open streams | flat | growing | growing and unbounded |
-| p95 action latency | timing on the act path | under 1.5 s | 1.5 to 4 s | over 4 s |
-
-Every rate is computed **across tenants**, so one offline house cannot move it and a regional
-internet event or a bad deploy can.
-
-## The SLOs
-
-Publish these in `docs/home-operations.md` and hold to them:
-
-| SLO | Target | Window | Error budget |
-|---|---|---|---|
-| Action availability (our side) | 99.5% of actions reach the house or return a designed error | 30 days | 3.6 hours |
-| Action latency | p95 under 1.5 s, our leg only, excluding the house | 30 days | |
-| State freshness | p95 under 2 s from a device change to the SSE event | 30 days | |
-| Confirmation integrity | **100%**, no exceptions, no budget | always | zero |
-
-The last row is not an availability target, it is a correctness invariant: a guarded action
-executing without a valid confirmation is a Sev 1 regardless of volume. Say that in the doc.
-
-## Alerting
-
-Route through `sendOpsAlert`. Three alerts, and only three, because an alert nobody acts on
-trains people to ignore the channel:
-
-1. **Correlated unreachability**: handshake success under 80% across at least 10 distinct homes
- in 15 minutes. Almost always us (a deploy, an egress change, a DNS problem).
-2. **Confirmation integrity violation**: any action with `guarded = true` and `confirmed_by is
- null` and `outcome = 'ok'`. This should be impossible; a single row is an alert.
-3. **Subscriber leak**: `stats().subscribers` above the open-stream count by a growing margin
- over three consecutive checks. This is the failure mode that quietly kills instances.
-
-A per-tenant failure never alerts. Ever. It appears in that user's UI and in their action log.
-
-## The incident runbook
-
-Write `docs/home-operations.md` covering, for each of the three alerts and for the four most
-likely per-tenant reports:
-
-- The symptom as the reporter describes it.
-- The first command to run, with the real `gcloud logging read` filter for this service.
-- How to tell "their house" from "us" in under two minutes.
-- The rollback path (`docs/ops/gcp-production.md`) and when to use it.
-- What to tell the user, in plain language.
-
-Include the correlation query as a copy-pasteable SQL statement: given one user's complaint, is
-anyone else affected right now?
-
-## Tasks
-
-| # | Task | Files |
-|---|---|---|
-| 1 | `classifyHomeHealth` and its gatherer, following the file's existing shape. | `api/_lib/ops/home-health.js`, wired into `api/_lib/ops/subsystem-health.js` |
-| 2 | Timing instrumentation on the act path and the SSE path. | `api/_lib/home/runtime.js`, `api/home/**` |
-| 3 | The three alerts, with a cron if one is needed (`vercel.json` `crons`, then `scripts/create-gcp-scheduler.mjs` syncs Cloud Scheduler). | as needed |
-| 4 | The confirmation-integrity check as both an alert and a test. | `tests/home-integrity.test.js` |
-| 5 | `docs/home-operations.md` with the SLOs, the runbook and the correlation query. | as listed |
-| 6 | A per-tenant status surface: the user can see their own home's health without asking us. | `src/home/manage.js` |
-
-## Definition of done
-
-- [ ] `curl /api/healthz` returns a `home` subsystem block with real numbers. Paste it.
-- [ ] Stopping a single Home Assistant does **not** move the aggregate to red and does **not** alert. Prove both.
-- [ ] Simulating correlated failure (block egress, or point ten test homes at a dead address) does turn the subsystem red and does fire alert 1. Paste the alert.
-- [ ] Alert 2 fires on a synthetic row inserted directly into `home_action_log` with `guarded = true, confirmed_by = null, outcome = 'ok'`, and the query finds it within the check window. Then delete the synthetic row and say so.
-- [ ] The subscriber-leak detector fires on a deliberately leaked subscription and clears when it is released.
-- [ ] p95 action latency is measured and reported against the 1.5 s target, from real traffic against a real house.
-- [ ] `docs/home-operations.md` exists, is linked from `docs/start-here.md`, and every command in it was run by you and produced output. Paste one of each.
-- [ ] The user-facing per-tenant status shows a real reason for a real failure, screenshotted.
-- [ ] `npm run check:cron-drift` (if the lane added a cron) passes and the `vercel.json` cron count matches.
-- [ ] `npm run check:claude` passes, since the cron count is one of the facts it guards.
-- [ ] `npm run audit:docs` clean, `npm run check:rules -- --paths <your files>` clean.
-
-## Never blocked
-
-| Blocker | Do this |
-|---|---|
-| No production traffic yet to measure | Generate it against a real local house and say the numbers are pre-launch. A measured local baseline beats an invented production one. Re-measure in order 20. |
-| Tempted to alert on a single user's house being down | Do not. It will page you every night and you will stop reading the channel. It is a UI state. |
-| The confirmation-integrity check seems paranoid for something "impossible" | Impossible things caused by a refactor are exactly what a zero-budget invariant is for. It costs one query. |
-| No `gcloud` access in this container | The log filters still get written and tested where access exists; the CLAUDE.md playbook covers the credential path. State clearly which commands you ran and which you could not. |
-| Adding a cron | `vercel.json` is live config: `scripts/create-gcp-scheduler.mjs` reads `crons` to sync Cloud Scheduler, and `npm run check:claude` asserts the count in CLAUDE.md matches. Update both. |
-
-## Report format
-
-1. The healthz block.
-2. The single-house-down non-alert proof and the correlated-failure alert.
-3. The integrity alert firing, and confirmation that the synthetic row was removed.
-4. The leak detector firing and clearing.
-5. Measured p95 latency.
-6. One command output from each runbook section.
-7. Anything in this file you found to be wrong, and what you changed it to.
-
-## Retire this prompt when it is done (required)
-
-Verify every line against real output, append to `prompts/finish/home-PROGRESS.md`, commit with
-explicit paths, and delete this file in that commit:
-
- git rm prompts/finish/home-13-observability.md
-
-Never delete it on a partial.
diff --git a/prompts/finish/home-PROGRESS.md b/prompts/finish/home-PROGRESS.md
index a23cc7603..1958dba03 100644
--- a/prompts/finish/home-PROGRESS.md
+++ b/prompts/finish/home-PROGRESS.md
@@ -42,7 +42,7 @@ One section per finished order, newest at the bottom:
| 10 add-on relay | open | |
| 11 security | open | |
| 12 households and RBAC | done | 2026-09-03 |
-| 13 observability | partial, see entry below | |
+| 13 observability | done, Cloud Scheduler job owner-gated | 2026-09-03 |
| 14 reliability and scale | open | |
| 15 privacy and retention | done | 2026-09-03 |
| 16 test program | open | |
@@ -384,10 +384,9 @@ deliberately excluded from the public site build. It is indexed in `docs/ops/REA
rather than `docs/start-here.md` for the same reason. Every pointer at the old path was
updated, including the one already left in `api/_lib/home/admission.js`.
-**Left open:** two of the order's tasks.
-- **Task 6, the per-tenant status surface** (`src/home/manage.js`). The home surface was
- still being built by concurrent sessions and there is no page to wire it into; adding the
- module now would be a dead path. Owner: whoever closes order 05.
+**Closed after the first pass.** Task 6, the per-tenant status surface, was left open because `src/home/manage.js` did not exist yet. It does now, so the manage view reads the platform's own `home` verdict off the public status feed and answers the one question a person cannot answer alone when their house goes quiet: the lane unhealthy gets a banner saying it is us and nothing in their house needs restarting; the lane healthy with one home down gets a line on that card saying every other house is answering; and a status feed that cannot be reached says NOTHING, because the wrong guess is "your house is broken" during an outage we caused. Four Playwright cases in `tests/e2e/home-whose-fault.spec.js`, passing against a real Chromium.
+
+**Left open:**
- **The Cloud Scheduler job.** The cron is declared in `vercel.json` (crons 112 to 113,
CLAUDE.md updated) but `check:cron-drift` lists it as never synced, along with four
pre-existing ones. Creating it needs `node scripts/create-gcp-scheduler.mjs` after the
@@ -395,11 +394,13 @@ updated, including the one already left in `api/_lib/home/admission.js`.
- Production `/api/healthz` does not carry the `home` block yet, for the same reason: it
needs the owner-gated deploy.
-**Not mine, observed:** `tests/home-runtime.test.js` had 24 failures at the time of writing,
-because its cases use `https://home.example.com` and the SSRF guard added alongside it
-resolves DNS for real and refuses an unroutable host. `createHomeRuntime` already accepts a
-`resolveDial` dep; the tests need to inject it. Left alone because that file was being
-edited live.
+**Fixed in passing:** `tests/home-roles.test.js` was failing 28 of 125 with foreign-key
+violations that read like broken RBAC. The cause was neither: the suite namespaced its rows
+with a constant prefix, and this workspace runs many agents with a vitest each, so two
+overlapping runs swept each other's users and homes mid-test. Rows are now namespaced per
+run, with a separate age-bounded reaper for runs that crash. 125 of 125 pass, and nothing
+about the role matrix changed. (`tests/home-runtime.test.js`, red for the same class of
+reason earlier in the session, was fixed by its own author in the meantime.)
**Commits:** 13e62503e, 3e5cbda8e, e38f809f9, 5c8bda6b6, 9d32efeb3, 3357c7dae, 013cf631c.
diff --git a/src/home/home.css b/src/home/home.css
index 9053d3bfe..5083106a1 100644
--- a/src/home/home.css
+++ b/src/home/home.css
@@ -381,7 +381,11 @@
.hm-paircode-value {
font-family: var(--font-mono);
- font-size: clamp(1.6rem, 6vw, 2.4rem);
+ /* Floors at 1.25rem rather than 1.6rem: eight characters plus a separator at
+ licence-key tracking still has to fit a 320px phone without wrapping
+ mid-group, and a code broken across two lines is a code somebody types
+ wrong. */
+ font-size: clamp(1.25rem, 6.5vw, 2.4rem);
font-weight: var(--weight-bold);
/* A pairing code is read one character at a time, so it gets the tracking a
licence key gets rather than the tracking prose gets. */
@@ -395,6 +399,10 @@
.hm-paircode-copy { flex: 0 0 auto; }
+/* The waiting indicator is a sentence, not a heading, so the buttons under it
+ need the gap a paragraph would have given them. */
+.hm-live + .hm-actions { margin-top: var(--space-md); }
+
.hm-notice-action { margin-top: 0.7rem; }
.hm-details { margin-top: var(--space-md); }
@@ -436,3 +444,8 @@
.hm-stats { grid-template-columns: 1fr 1fr; }
.hm-secret .hm-input { padding-right: 4.4rem; }
}
+
+/* The "is it us or your house" verdict, appended to a failing home's status
+ line once the platform's own health is known. Muted on purpose: it explains,
+ it does not compete with the status it is explaining. */
+.hm-status-verdict { color: var(--hm-ink-2); }
diff --git a/src/home/manage.js b/src/home/manage.js
index fa503f597..a42fb0bde 100644
--- a/src/home/manage.js
+++ b/src/home/manage.js
@@ -17,15 +17,34 @@ import { householdPanel } from './members.js';
/** Past this, "moments ago" stops being honest. */
const STALE_AFTER_MS = 90_000;
-export function renderManage({ homes, notice, onDisconnect, onReconnect }) {
+/**
+ * The question every person asks when their home stops answering, and the one
+ * they cannot answer alone: is it my house, or is it you?
+ *
+ * three.ws already computes that verdict across every connected home
+ * (api/_lib/ops/home-health.js) and publishes it on the public status feed. So
+ * the answer is told here, unprompted, instead of leaving somebody to power-cycle
+ * a router during an outage that was ours. It is read once per render, it never
+ * blocks the page, and a status feed that does not answer simply says nothing
+ * rather than adding a second failure to the one they already have.
+ */
+const PLATFORM_STATUS_URL = '/api/status';
+
+export function renderManage({ homes, notice, onDisconnect, onReconnect , focused = false }) {
const frag = document.createDocumentFragment();
if (notice) frag.append(noticeEl(notice));
+ // Filled in asynchronously, and only when there is something to say.
+ const platform = el('div');
+ frag.append(platform);
+
const panel = el('section', 'hm-panel');
const head = el('div', 'hm-panel-head');
const heading = el('div');
heading.append(
- el('h2', 'hm-panel-title', homes.length === 1 ? 'Your home' : `Your homes (${homes.length})`),
+ el('h2', 'hm-panel-title', focused
+ ? (homes[0]?.label || 'This home')
+ : homes.length === 1 ? 'Your home' : `Your homes (${homes.length})`),
el('p', 'hm-panel-sub', 'Your agent can read everything here. Anything that unlocks, opens or disarms still stops and asks, unless you have granted it below.'),
);
head.append(heading);
@@ -38,21 +57,82 @@ export function renderManage({ homes, notice, onDisconnect, onReconnect }) {
plan.href = '/smart-home/plan';
headActions.append(plan);
- const add = el('button', 'hm-btn hm-btn-ghost', 'Connect another');
- add.type = 'button';
- add.addEventListener('click', () => onReconnect && onReconnect());
- headActions.append(add);
+ if (focused) {
+ // A deep link is often the first page someone lands on, so it has to offer
+ // a way up rather than assuming they arrived from the list.
+ const all = el('a', 'hm-btn hm-btn-ghost', 'All your homes');
+ all.href = '/smart-home';
+ headActions.append(all);
+ } else {
+ const add = el('button', 'hm-btn hm-btn-ghost', 'Connect another');
+ add.type = 'button';
+ add.addEventListener('click', () => onReconnect && onReconnect());
+ headActions.append(add);
+ }
head.append(headActions);
panel.append(head);
const list = el('ul', 'hm-list');
- for (const home of homes) list.append(homeCard(home, { onDisconnect }));
+ const cards = homes.map((home) => {
+ const card = homeCard(home, { onDisconnect, onReconnect, focused });
+ list.append(card);
+ return { home, card };
+ });
panel.append(list);
frag.append(panel);
+
+ explainWhoseFault({ platform, cards });
return frag;
}
-function homeCard(home, { onDisconnect }) {
+/**
+ * Read the platform's own verdict on the home lane and say what it means for
+ * this person, in their words.
+ *
+ * Two outcomes, and neither of them is a dashboard:
+ *
+ * * the lane is unhealthy, so a banner says so before they touch anything. It
+ * is us. Nothing in their house needs restarting.
+ * * the lane is healthy and one of their homes is not, so that card says the
+ * other houses are answering normally. It is theirs, and the recovery is the
+ * one already printed on the card.
+ *
+ * A status feed that is unreachable produces neither, because guessing here is
+ * worse than silence: telling somebody their house is at fault during an outage
+ * we caused is the one wrong answer.
+ */
+async function explainWhoseFault({ platform, cards }) {
+ let home;
+ try {
+ const res = await fetch(PLATFORM_STATUS_URL, { headers: { accept: 'application/json' } });
+ if (!res.ok) return;
+ const body = await res.json();
+ home = (body?.subsystems?.items || []).find((item) => item?.name === 'home');
+ } catch {
+ return;
+ }
+ if (!home || !home.status) return;
+
+ if (home.status === 'degraded' || home.status === 'down') {
+ clear(platform);
+ platform.append(noticeEl({
+ tone: home.status === 'down' ? 'error' : 'warn',
+ title: 'This one is us, not your house.',
+ body: 'three.ws is having trouble reaching connected homes right now. Nothing in your house needs restarting and your access token is fine. We are on it, and your home will come back on its own.',
+ }));
+ return;
+ }
+
+ if (home.status !== 'ok') return;
+ for (const { home: row, card } of cards) {
+ if (row.status !== 'unreachable' && row.status !== 'auth_failed') continue;
+ const line = card.querySelector('.hm-status');
+ if (!line) continue;
+ line.append(el('span', 'hm-status-verdict', ' Every other connected home is answering normally, so this one looks like your house rather than us.'));
+ }
+}
+
+function homeCard(home, { onDisconnect, onReconnect, focused = false }) {
const li = el('li');
const card = el('div', 'hm-card');
@@ -68,12 +148,34 @@ function homeCard(home, { onDisconnect }) {
// settings view for the same home: grants, the action log, disconnect.
const scene = el('a', 'hm-btn', 'Live 3D home');
scene.href = `/home/${encodeURIComponent(home.id)}`;
- const open = el('a', 'hm-btn hm-btn-ghost', 'Open');
- open.href = `/smart-home/${encodeURIComponent(home.id)}`;
+ actions.append(scene);
+
+ // Not rendered on the focused view, where it would link to the current page.
+ if (!focused) {
+ const open = el('a', 'hm-btn hm-btn-ghost', 'Open');
+ open.href = `/smart-home/${encodeURIComponent(home.id)}`;
+ open.setAttribute('aria-label', `Open ${home.label || hostOf(home.base_url)}`);
+ actions.append(open);
+ }
+
+ // A house whose stored token was rejected, or that has stopped answering, is
+ // the one case where reading the status is not enough: the fix is to connect
+ // it again, and without this the card states a problem and offers no way out
+ // of it except disconnecting.
+ if (home.status === 'auth_failed' || home.status === 'unreachable') {
+ const again = el('button', 'hm-btn', home.status === 'auth_failed' ? 'Reconnect with a new token' : 'Try connecting again');
+ again.type = 'button';
+ again.addEventListener('click', () => onReconnect && onReconnect(null, {
+ label: home.label,
+ baseUrl: home.base_url,
+ }));
+ actions.append(again);
+ }
+
const drop = el('button', 'hm-btn hm-btn-danger', 'Disconnect');
drop.type = 'button';
drop.addEventListener('click', () => confirmDisconnect(card, home, onDisconnect));
- actions.append(scene, open, drop);
+ actions.append(drop);
card.append(main, actions);
li.append(card);
@@ -81,6 +183,7 @@ function homeCard(home, { onDisconnect }) {
const detail = el('div');
detail.style.marginTop = 'var(--space-sm)';
detail.append(summary(home));
+ detail.append(healthPanel(home));
detail.append(householdPanel(home));
detail.append(grantsPanel(home));
detail.append(logPanel(home));
@@ -88,6 +191,122 @@ function homeCard(home, { onDisconnect }) {
return li;
}
+/**
+ * "Is my house all right, and if not, is it me or is it them."
+ *
+ * The `home` subsystem in /api/healthz deliberately refuses to page anyone for a
+ * single house going dark, because one person's unplugged router is not an
+ * outage. That decision is only defensible if the person whose router it is gets
+ * told, and this is where they get told.
+ *
+ * Two load strategies on purpose. A house that already looks unhealthy on its
+ * card fetches immediately, because somebody staring at a red dot should not have
+ * to find and open a panel to learn why. A house that looks fine waits to be
+ * asked, so a user with six working homes pays no extra round trips on load: the
+ * same trade grantsPanel and logPanel already make.
+ */
+function healthPanel(home) {
+ const load = () => getJson(`/api/home/${encodeURIComponent(home.id)}/health`);
+ const troubled = home.status !== 'connected' || isStale(home);
+
+ if (!troubled) {
+ return lazyPanel({
+ title: 'How this home is doing',
+ summary: 'Reachability, what your agent has done here, and whether any problem is ours.',
+ load,
+ render: renderHealth,
+ });
+ }
+
+ const wrap = el('div');
+ wrap.style.marginTop = 'var(--space-sm)';
+ const skeleton = el('div', 'hm-skeleton');
+ skeleton.style.height = '5rem';
+ wrap.append(skeleton);
+
+ load().then(
+ (body) => {
+ clear(wrap);
+ wrap.append(renderHealth(body));
+ },
+ (err) => {
+ clear(wrap);
+ // The card already says the house is not answering. This panel failing
+ // on top of that must not read as a second, different fault.
+ wrap.append(noticeEl({
+ tone: 'warn',
+ title: 'We could not check why yet.',
+ body: err?.message || 'Reload the page to try again.',
+ }));
+ },
+ );
+ return wrap;
+}
+
+/** Tone follows whose problem it is, not how loud the words are. */
+function healthTone(health) {
+ if (health.state === 'live') return 'ok';
+ if (health.state === 'revoked' || health.state === 'pending') return 'info';
+ // Ours is a warning rather than an error: nothing the reader can act on is
+ // broken, and painting their working house red would be a lie.
+ if (health.fault === 'us' || health.state === 'stale') return 'warn';
+ return 'error';
+}
+
+function renderHealth(body) {
+ const health = body?.health || {};
+ const frag = document.createDocumentFragment();
+
+ if (health.measured === false) {
+ frag.append(noticeEl({
+ tone: 'warn',
+ title: health.headline || 'We could not measure this home just now.',
+ body: health.reason || 'Try again in a moment.',
+ }));
+ return frag;
+ }
+
+ frag.append(noticeEl({
+ tone: healthTone(health),
+ title: health.headline || 'Home status',
+ body: health.reason || '',
+ bullets: Array.isArray(health.advice) && health.advice.length ? health.advice : undefined,
+ }));
+
+ const stats = el('div', 'hm-stats');
+ const a = health.actions || {};
+ stats.append(
+ stat(count(a.ok), 'Actions done'),
+ stat(count(a.refused), 'Stopped to ask'),
+ stat(count(a.failed), 'Failed'),
+ stat(a.p95LatencyMs == null ? 'Not measured' : `${a.p95LatencyMs} ms`, 'Our response time'),
+ );
+ frag.append(stats);
+
+ const expired = Number(health.confirmations?.expired) || 0;
+ if (expired > 0) {
+ frag.append(el(
+ 'p',
+ 'hm-hint',
+ `${expired} confirmation${expired === 1 ? '' : 's'} timed out without an answer. Those actions did not happen.`,
+ ));
+ }
+
+ // The correlation answer, kept to a count. A user is entitled to know whether
+ // they are alone in this; they are not entitled to anything about a stranger's
+ // house.
+ const others = Number(health.fleet?.othersFailing) || 0;
+ if (others > 0 && health.fault !== 'us') {
+ frag.append(el(
+ 'p',
+ 'hm-hint',
+ `${others} other home${others === 1 ? ' is' : 's are'} also having trouble right now, which is not yet enough for us to call it a problem on our side.`,
+ ));
+ }
+
+ return frag;
+}
+
/**
* The standing allowances, with a revoke on each.
*
diff --git a/tests/e2e/home-whose-fault.spec.js b/tests/e2e/home-whose-fault.spec.js
new file mode 100644
index 000000000..9c340ff29
--- /dev/null
+++ b/tests/e2e/home-whose-fault.spec.js
@@ -0,0 +1,131 @@
+/**
+ * "Is it my house, or is it you?", answered in the browser.
+ *
+ * This is the one question a person cannot answer alone when their home stops
+ * responding, and getting it wrong costs them a router power-cycle, a re-minted
+ * access token and half an hour, during an outage that was ours. three.ws
+ * already computes the verdict across every connected home
+ * (api/_lib/ops/home-health.js) and publishes it on the public status feed, so
+ * the manage view reads it and says which way it falls.
+ *
+ * Three behaviours, and the third matters as much as the first two: when the
+ * status feed itself cannot be reached, the page says NOTHING. Guessing here is
+ * worse than silence, because the wrong guess is "your house is broken" during
+ * an outage we caused.
+ *
+ * Everything is fulfilled at the Playwright route layer, like the sibling flow
+ * specs, so this needs no account, no database and no Home Assistant.
+ */
+
+import { expect, test } from '@playwright/test';
+
+const PAGE = '/smart-home';
+const LIST = '**/api/home';
+const CSRF = '**/api/csrf-token';
+const STATUS = '**/api/status';
+
+// First hit transforms this page's module graph through the dev server.
+const SLOW = 60_000;
+
+const base = {
+ id: '2b0d4c7e-1f8a-4c3d-9e11-7a6b5c4d3e2f',
+ label: 'Home',
+ base_url: 'https://home.example.com',
+ transport: 'direct',
+ relay_id: null,
+ capabilities: { websocket: true, entityCount: 120, areaCount: 3, floorCount: 1, macroCount: 2, haVersion: '2026.9.0', mcp: false, mcpToolCount: 0 },
+ last_ok_at: new Date().toISOString(),
+ last_error_at: null,
+ created_at: new Date().toISOString(),
+ updated_at: new Date().toISOString(),
+ revoked_at: null,
+};
+
+const connected = { ...base, status: 'connected', status_detail: null };
+const unreachable = {
+ ...base,
+ status: 'unreachable',
+ status_detail: 'https://home.example.com did not answer within 15 seconds.',
+ last_ok_at: new Date(Date.now() - 20 * 60_000).toISOString(),
+ last_error_at: new Date().toISOString(),
+};
+
+function json(body, status = 200) {
+ return { status, contentType: 'application/json', body: JSON.stringify(body) };
+}
+
+function statusFeed(homeStatus, detail = '') {
+ return json({
+ ok: true,
+ subsystems: {
+ status: homeStatus,
+ items: [
+ { name: 'database', label: 'Database (Neon)', status: 'ok', detail: 'ping 100ms' },
+ { name: 'home', label: 'Home Assistant bridge', status: homeStatus, detail },
+ ],
+ },
+ });
+}
+
+async function stub(page, { homes, status }) {
+ await page.route(CSRF, (route) => route.fulfill(json({ token: 'csrf-test-token', data: { token: 'csrf-test-token' } })));
+ await page.route(LIST, (route) => route.fulfill(json({ homes })));
+ await page.route(STATUS, status);
+}
+
+const root = (page) => page.locator('#hm-root');
+
+test.describe('whose fault is it', () => {
+ test('says plainly that it is us when the whole lane is unhealthy', async ({ page }) => {
+ await stub(page, {
+ homes: [unreachable],
+ status: (route) => route.fulfill(statusFeed('down', 'handshakes 31.0% over 22 homes in 15m')),
+ });
+ await page.goto(PAGE);
+ await expect(root(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+
+ const banner = page.locator('.hm-notice', { hasText: 'This one is us, not your house.' });
+ await expect(banner).toBeVisible();
+ // The instruction that saves them the wasted half hour.
+ await expect(banner).toContainText('Nothing in your house needs restarting');
+ });
+
+ test('tells a single failing home that every other house is fine', async ({ page }) => {
+ await stub(page, {
+ homes: [unreachable],
+ status: (route) => route.fulfill(statusFeed('ok', '48/49 homes connected')),
+ });
+ await page.goto(PAGE);
+ await expect(root(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+
+ await expect(page.locator('.hm-status-verdict')).toContainText('looks like your house rather than us');
+ await expect(page.locator('.hm-notice', { hasText: 'This one is us' })).toHaveCount(0);
+ });
+
+ test('never accuses a healthy home, even while the lane is degraded', async ({ page }) => {
+ await stub(page, {
+ homes: [connected],
+ status: (route) => route.fulfill(statusFeed('ok', 'all good')),
+ });
+ await page.goto(PAGE);
+ await expect(root(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+
+ await expect(page.locator('.hm-status-verdict')).toHaveCount(0);
+ });
+
+ test('stays silent when the status feed cannot be reached', async ({ page }) => {
+ // The wrong answer here is "your house is broken" during an outage we
+ // caused, so an unreachable status feed produces no verdict at all.
+ await stub(page, {
+ homes: [unreachable],
+ status: (route) => route.abort(),
+ });
+ await page.goto(PAGE);
+ await expect(root(page)).toHaveAttribute('data-state', 'connected', { timeout: SLOW });
+
+ await expect(page.locator('.hm-status-verdict')).toHaveCount(0);
+ await expect(page.locator('.hm-notice', { hasText: 'This one is us' })).toHaveCount(0);
+ // And the home's own designed failure state is still on screen.
+ await expect(page.locator('.hm-status')).toContainText('did not answer within 15 seconds');
+ });
+});