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.

test(home-connect): verify every connect state against a real house and retire order 05

nirholasfa1cc81be788
diff --git a/prompts/finish/302-home-05-connect-flow.md b/prompts/finish/302-home-05-connect-flow.md
deleted file mode 100644
index 4f016098b..000000000
--- a/prompts/finish/302-home-05-connect-flow.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# 05. The connect flow: `/home` onboarding, every state
-
-**How to run this:** paste this whole file into a fresh Claude Code chat opened in
-`/workspaces/three.ws`. Read [00-CONTEXT.md](_context/home-00-CONTEXT.md) first. Order
-[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. Start the dev server and exercise this in a real browser; a UI
-order that was never opened is not done.
-
-**Nothing in this file is a status claim to trust.** Step 0 re-measures.
-
----
-
-## Step 0: re-derive the current state
-
-```bash
-npm run dev & # port 3000
-curl -s localhost:3000/api/home -H "cookie: <dev session>" | head -c 300
-grep -n "materialize" vercel.json | head -4 # the page-route pattern to copy
-ls pages/ | grep -E "materialize|agent-detail" ; ls src/ | grep -E "materialize|agent-detail"
-grep -n "^--" public/tokens.css | head -20 # the vocabulary you must use
-```
-
-## What this order owns
-
-Getting a stranger from "I have a Home Assistant somewhere" to "my agent is connected", and
-every way that goes wrong. It owns no 3D (order 06) and no voice (order 08).
-
-Route `/home` via a `vercel.json` `routes` entry to `pages/home.html`, controller `src/home/connect.js`.
-Follow the `/materialize` precedent exactly: a `routes` entry, a page file, a module in `src/`.
-
-## The flow
-
-1. **Signed out**: the value proposition and a sign-in, not a form that will fail.
-2. **No home yet**: the connect card. Two fields, base URL and token, plus a link to the exact
- Home Assistant path for minting one (Profile, Security, Long-lived access tokens, Create
- token). Never make the user search for it.
-3. **URL typed**: validate client-side with `normalizeBaseUrl` and `isPrivateHost` from
- `@three-ws/home-bridge`, **before** any network call, and say the true thing immediately:
- a `192.168.x.x` or `.local` address cannot be reached by three.ws. Offer the two real paths
- (a remote https URL now, or the add-on from order 10 when it lands) rather than a dead end.
-4. **Verifying**: a real progress state naming what is happening ("opening a connection",
- "reading your rooms"), never a bare spinner and never a fake progress bar.
-5. **Connected**: the house summarised. Rooms found, entities found, whether `mcp_server` is on
- and how many tools it exposes, the Home Assistant version. All measured, never assumed.
-6. **Managing**: the list of homes, per-home status, the standing allowances with a revoke on
- each, the action log, and a disconnect that says plainly what it does to the stored token.
-
-## Every state you must build
-
-There are eleven, and a missing one is what makes a product feel unfinished. Each gets a
-designed treatment using `public/tokens.css` primitives:
-
-| # | State | Must |
-|---|---|---|
-| 1 | Signed out | explain the feature, offer sign-in, never a disabled form |
-| 2 | Empty (no homes) | the connect card, with the token instructions inline |
-| 3 | Validating input | inline, immediate, before the network |
-| 4 | Private-host refusal | name the address class and give the two real options |
-| 5 | Verifying | named steps, skeleton not spinner, cancellable |
-| 6 | Connected | the measured summary, and a clear next action into `/home/:id` |
-| 7 | `auth` failure | "create a new long-lived token", with the path, and the field refocused |
-| 8 | `unreachable` failure | distinguishes "wrong address" from "house offline", offers a retry and the add-on path |
-| 9 | Degraded (connected, breaker open, or stale) | the last known state visibly marked stale with its age, never an empty house |
-| 10 | Revoked / disconnected | says the stored credential was scrubbed, offers reconnect |
-| 11 | Many homes | the list scales past one without a redesign; long labels truncate without breaking layout |
-
-## Quality bar (non-negotiable)
-
-- Every interactive element has hover, active, focus-visible and disabled states.
-- Keyboard: the whole flow is completable without a mouse. Focus moves to the error on failure.
-- The token field is `type="password"` with a reveal toggle, `autocomplete="off"`, and is never
- written to `localStorage`, never logged, never put in a URL, and never echoed back by the API.
-- Nothing shifts layout when async data lands. Reserve the space.
-- 320px, 768px and 1440px all work. Test all three.
-- Every user-supplied string (the label, entity names, area names) is rendered as text, never as
- HTML. This is the same untrusted-input rule as order 04, on the render side.
-- Copy is plain language. "Your home is only on your local network" beats "ERR_PRIVATE_HOST".
-
-## Tasks
-
-| # | Task | Files |
-|---|---|---|
-| 1 | Route and page shell, wired into `data/pages.json` so it is discoverable. | `vercel.json`, `pages/home.html`, `data/pages.json` |
-| 2 | The connect controller with all eleven states. | `src/home/connect.js`, `src/home/home.css` |
-| 3 | Client-side reachability validation using the published package, so the same logic runs both sides. | same |
-| 4 | The manage view: list, status, grants with revoke, action log, disconnect. | `src/home/manage.js` |
-| 5 | i18n: every string through the existing extraction path (`npm run i18n:extract`). | as generated |
-| 6 | Playwright e2e covering the happy path and at least four failure states. | `tests/e2e/home-connect.spec.js` |
-| 7 | Docs and changelog. | `docs/smart-home.md`, `data/changelog.json`, `STRUCTURE.md` |
-
-## Definition of done
-
-- [ ] Screenshots of all eleven states at 1440px, and states 2, 5, 6 and 8 at 320px.
-- [ ] A real connect against a real local Home Assistant, in a real browser, with the network tab showing the real `POST /api/home/connect` and its real response.
-- [ ] A private-host address produces the designed refusal with no network call. Prove it with an empty network tab.
-- [ ] A wrong token produces state 7 with the field refocused, not a generic error.
-- [ ] Stopping the Home Assistant container puts a connected home into state 9 with a visible staleness age, and the room list stays on screen.
-- [ ] Zero console errors and zero console warnings from your code, on every state.
-- [ ] `npm run audit:web` passes for `/home` (see `docs/ops/page-audit.md`; use `audit:web:login` first for the authed sweep).
-- [ ] Keyboard-only completion of the connect flow, recorded as a step list in your report.
-- [ ] `npx playwright test tests/e2e/home-connect.spec.js` passes.
-- [ ] The token never appears in `localStorage`, in a URL, in a console line, or in any API response. Prove each with the command you used.
-- [ ] `npm run audit:docs` clean, `npm run check:rules -- --paths <your files>` clean.
-
-## Never blocked
-
-| Blocker | Do this |
-|---|---|
-| No Home Assistant to connect to | Run one; the docker command is in the context file. Never build a UI against a fixture and call it verified. |
-| No QA login | `AUDIT_EMAIL` / `AUDIT_PASSWORD` in `.env`, or `npm run audit:web:provision` to create one through the real register page. |
-| A state is hard to reproduce | Force it: stop the container for state 9, use a junk token for 7, use `192.168.1.10` for 4. Every state here is reachable in under a minute. |
-| Tempted to store the token client-side "to make reconnect easier" | Refuse. It goes to the server once, encrypted at rest, and never comes back. |
-| The design feels sparse | Read `DESIGN-TOKENS.md` and a shipped surface (`/materialize`) before inventing anything. Consistency beats novelty here. |
-
-## Report format
-
-1. The screenshot set (eleven states, plus the four mobile ones).
-2. The real connect transcript from the browser network tab.
-3. The no-network-call proof for the private-host refusal.
-4. The keyboard-only walkthrough.
-5. The four token-leak proofs.
-6. `audit:web`, Playwright and `check:rules` output.
-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/_context/home-PROGRESS.md`, commit with
-explicit paths, and delete this file in that commit:
-
- git rm prompts/finish/302-home-05-connect-flow.md
-
-Never delete it on a partial.
diff --git a/prompts/finish/_context/home-PROGRESS.md b/prompts/finish/_context/home-PROGRESS.md
index 207af3d8f..d18210066 100644
--- a/prompts/finish/_context/home-PROGRESS.md
+++ b/prompts/finish/_context/home-PROGRESS.md
@@ -34,7 +34,7 @@ One section per finished order, newest at the bottom:
| 02 bridge runtime | done | 2026-09-03 |
| 03 API surface | done | 2026-09-03 |
| 04 agent tools | done | 2026-09-09 |
-| 05 connect flow | mostly done, see entry | 2026-09-03 |
+| 05 connect flow | done | 2026-09-09 |
| 06 3D home scene | open | |
| 07 floorplan editor | built, browser verification blocked, see entry | |
| 08 voice loop | done | 2026-09-09 |
@@ -2230,3 +2230,131 @@ repeats. Neither is a product defect and neither reproduces on `https://three.ws
**Commits:** `9e9a2f42f` (the two service fixes and their tests, committed from the shared worktree
by a concurrent agent mid-run), `6fc8dccff` (README), plus this entry.
+
+---
+
+## 05. The connect flow: `/smart-home` onboarding, every state, run 2 (2026-09-09)
+
+**Verdict: done.** Run 1 (2026-09-03, above) built the surface and marked itself PARTIAL for one
+reason: the order 11 SSRF guard had closed the only route to a real Home Assistant, so the live
+half of the acceptance criteria could not be run at all. That is resolved. `api/_lib/home-url-guard.js`
+now carries the two-condition seam run 1 asked for (`HOME_ALLOW_LOCAL_INSTANCE=1` AND no
+`K_SERVICE`, tested positively so it is off on Cloud Run whatever else is configured), and
+`playwright.home.config.js` sets it for the lane. Every item run 1 left open is closed below
+against a real house, and no product code needed changing to close them.
+
+**Shipped:** nothing new on the surface. This run is the verification run 1 could not do, plus
+five defects fixed in the lane's own evidence harness, each of which was making a green result
+mean less than it appeared to.
+
+**Measured, all from run 7 of the tier this session (`npm run test:home:e2e`, connect specs):**
+- `tests/e2e/home-connect.spec.js` + `home-connect-live.spec.js` + `home-connect-gallery.spec.js`:
+ **39 passed, 0 failed** in 3.2 minutes, against Home Assistant `2026.9.0` in a real container.
+- **The real connect:** `HTTP 201`, capabilities measured live as `entityCount 125, areaCount 4,
+ floorCount 1, macroCount 2, haVersion 2026.9.0, mcp true, mcpToolCount 29`. `haVersion` is
+ asserted equal to what `/api/config` on the house itself returns, not scraped off an entity.
+ The whole browser console for the connect was two lines, both `debug: [vite] connecting/connected`.
+ Transcript and screenshots: `reports/home-connect-live/`.
+- **State 9, live, not rendered:** the container was really stopped mid-test. The card kept its
+ entire measured summary (4 rooms, 125 devices, 2 scenes, 2026.9.0, MCP 29 tools), the status
+ line read "Not answering right now. It last answered moments ago, and that is the state shown
+ below", `data-state` was `degraded`, and the home polled back to `connected` on its own once the
+ container returned, with no reconnect and no new token. This is the item run 1 could only assert
+ against a two-hour-old timestamp.
+- **State 7, live:** a junk token against the real house is classified `auth` on the wire (a 4xx,
+ never a 5xx), lands on `data-state="auth_failed"`, refocuses `#hm-token`, names the Long-lived
+ access tokens path, keeps the address the user typed, and stores no half-home. Added this run;
+ the tier previously proved only that the page maps code `auth` onto state 7, never that a real
+ Home Assistant 401 is classified as `auth` at all.
+- **All fifteen states photographed at 1440px and 320px** into `reports/home-connect-states/`
+ (30 PNGs), each asserted to add **zero horizontal overflow at 320px** and to write nothing to
+ the console.
+- **Private-host refusal: zero network requests** between submit and the rendered refusal,
+ counted on the Playwright request event.
+- **Keyboard:** the connect completes from the keyboard against the real house. Tab stops from
+ the top of the document to the first field: `Skip to content`, then `What we store, in full`,
+ then `hm-label`; then Tab to `hm-url`, Tab to `hm-token`, Enter submits.
+- **Token leak, four proofs, all against a real long-lived token:** absent from `localStorage`,
+ from `sessionStorage`, from `document.cookie` and from `window.location.href` (read out of the
+ page after a real submit); absent from the response body (substring search over the whole body);
+ absent from every request URL in the transcript; absent from every console line. Statically:
+ `grep -rn "localStorage\|sessionStorage\|document.cookie" src/home/` finds nothing in
+ `connect.js` or `manage.js` (the one hit is `scene.js` storing a 2D/3D view preference), and
+ `grep -rn "console\." src/home/` finds nothing in either file.
+- `npm run audit:web` for `/smart-home`, **authed against production**, desktop and mobile:
+ **0 error, 0 warn**, 3 info. Run 1 could only report 6 errors that were all the Codespace's own
+ HMR socket; auditing the live site removes that class entirely.
+- `npm run audit:docs`: clean, 1590 files. `npm run check:rules`: clean on every file touched.
+- Home unit tests, sharded to survive concurrent agents: **655 passed, 0 failed** across 26 files
+ (`tests/home-*.test.js` plus `packages/home-bridge`); the live-tier cases skip without a house.
+
+**Five defects fixed, all in the lane's evidence harness rather than the product.** Each one was
+letting a run report something other than what it measured:
+
+1. **`tests/e2e/home-global-setup.js`: the documented escape hatch from the registration rate
+ limit was itself broken.** `raiseHomeCeiling` iterated a hardcoded `['owner', 'guest']` while
+ `HOME_E2E_ROLES` exists precisely so a lane that needs only an owner does not spend one of five
+ hourly registrations on a guest. Setting it crashed on `accounts.guest.email`, so the one way
+ out of a rate limit was a dead end. Now iterates `ROLES` and skips a role it was not asked to
+ provision.
+2. **`tests/e2e/home-connect-gallery.spec.js`: the console assertion allowlisted one HTTP status.**
+ It muted `Failed to load resource ... 401` by literal string. States 8 and 12 arrived later
+ with a 502 and a 402, and both went red over a line Chromium's network stack writes about a
+ response the spec itself fulfilled and the page handled correctly. Replaced with a filter that
+ asks WHO emitted the line rather than which status it names: HMR, `GL Driver Message` from the
+ GPU process, and `Failed to load resource` **scoped to `/api/` by URL**. The same line for a
+ stylesheet, a script or a font still fails, which is the half worth keeping.
+3. **`tests/e2e/home-connect-stubs.js`: the shared fixture had a ninety-second fuse.**
+ `HOME.last_ok_at` was stamped once when the module was imported, and a connected home whose
+ last handshake has aged past 90 seconds is state 9. The tier runs for eight minutes, so most of
+ it was on the wrong side of that line: `connected` assertions passed or failed purely as a
+ function of how long the run had been going and which order the files executed in. The three
+ timestamps are now getters, so the fixture means what it says at the moment it is used, and a
+ spec that wants a stale house still says so explicitly.
+4. **`tests/e2e/home-connect-stubs.js`: state 5 was never actually held.** The gallery holds the
+ verifying screen by returning a promise that never settles, and `stub` passed that promise
+ straight to `route.fulfill`, which answered the request immediately with an empty 200. The page
+ then read no home, asked for the list, got an empty one, and landed on the EMPTY screen. State
+ 5 existed only for as long as one round trip against a local stub, so the spec passed on a
+ quiet machine, failed on a loaded one, and on the runs where it passed it was photographing a
+ frame rather than a state. `onConnect` is now awaited, which makes a never-settling promise a
+ real hang. `05-verifying-1440.png` is the first honest picture of that screen.
+5. **`scripts/home-test-instance.mjs`: one killed harness poisoned its lane for fifteen minutes.**
+ `withLock` abandoned a lock only on age, with a 900-second threshold, while every caller of the
+ harness kills it on a much shorter timeout (`stopHomeInstance` allows 120 seconds) and a killed
+ process never reaches the `finally` that releases. So a timeout left a lock, the next call sat
+ in the wait loop until that lock aged out, died on its own caller's timeout, and left a fresh
+ one: one kill guaranteed the next several. It presented as `home-test-instance timed out after
+ 120s` on a `--stop` that takes **7 seconds** when it runs at all, which reads as a hung
+ container and is a dead process's leftovers. The lock now records its holder's pid and a waiter
+ asks the operating system whether that process still exists. Proven both ways: a planted lock
+ owned by a dead pid is reclaimed and the call completes in 11 seconds, and a planted lock owned
+ by a live pid is still waited on, by name (`[lock] waiting for pid 418469 to finish with "c05"`).
+ `EPERM` counts as held, so another user's process is never evicted. SIGTERM and SIGINT now
+ release the lock too; SIGKILL cannot be caught, which is why the pid check is the real fix.
+
+**Deviations from the order file, beyond the ones run 1 already recorded:**
+- The order file asks for eleven states and a route at `/home`. Both were already superseded and
+ are correct as they stand: the route is `/smart-home` (run 1's deviation 1, `/home` is the
+ marketing landing page), and the flow has **fifteen** states, the four beyond the original
+ twelve being the pairing host, one deep-linked home, and an id that is not this account's.
+- The order's task list (page, controller, i18n, docs, changelog, `STRUCTURE.md`, `data/pages.json`)
+ was all completed by run 1 and verified present this run, so nothing there was rebuilt.
+ `data/changelog.json` gets no entry from this run: every change here is test-harness only, with
+ no user-visible effect, which the CLAUDE.md changelog rule explicitly excludes.
+
+**Operational note for the next lane, not a defect:** `playwright.home.config.js` defaults to
+ports 8099 and 3020 and refuses to reuse a server, so two agents running the home lane at once
+collide with `http://127.0.0.1:8099/api/version is already used`. That is the config behaving as
+its own comment says it should (own the ports or fail loudly). Set `HOME_E2E_API_PORT` and
+`HOME_E2E_WEB_PORT`, as this run did (8107 and 3027), rather than killing the peer's server.
+
+**Left open: nothing for this order.**
+
+**Commits:** all five fixes reached `main` inside concurrent agents' `git add -A` sweeps before
+they could be staged from here, under commit messages about other work: `f663e9c9a` carries the
+harness lock fix, the ROLES fix, the gallery filter, the live-spec filter, the new state 7 test
+and the fixture getters, and `af50eb075` carries the `onConnect` await. The content is intact and
+verified at HEAD; only the attribution is wrong, and the shared-worktree rule against amending
+means it stays that way. This entry and the order-file retirement are the only commit from this
+session.