makelore/.project-docs/30-worklog/tasks/20260816-guided-hotspot-binding-7c4d2e.md

# Task: Implement Robot Guided Hotspot Binding V1

## Identity

- Task ID: 20260816-guided-hotspot-binding-7c4d2e
- Mode: Feature
- Branch: codex/20260816-guided-hotspot-binding-7c4d2e-guided-hotspot-binding
- Worktree: D:\Datas\OthersProjects\makelore-guided-hotspot-binding-7c4d2e
- Base commit: 54443232dd6a07dc1f3df5b33df00f665540497a
- Owner: codex-root
- Status: Ready for Integration

## Scope

- Add the accepted default-off Guided Hotspot Binding V1 to the existing Robot binding experience.
- Add a strict Renderer facade for reading the Main-owned capability and asking Main to open the fixed firmware portal in the system browser.
- Add local Host API branches that return before Works authentication/upstream access, own the fixed portal URL, redact native opener failures, and force invalid activation-code errors to non-retryable.
- Add the in-memory guided/manual binding states, security/recovery copy, and success wording without claiming device online readiness.
- Add focused Renderer API, Main route, and page regressions. Keep Electron/physical-device smoke as release gates while the capability remains false by default.

## Intent And Constraints

- Implement ADR-002 and source proposal `14afe4a` without modifying firmware, adding BLE/Wi-Fi discovery, adding cloud claim routes, or changing the positional six-digit Binding interface.
- Preserve `Renderer -> Host API -> Electron Main -> Works Square`; Renderer must not call direct IPC, accept an arbitrary portal URL, or collect/log/persist Wi-Fi credentials or activation codes.
- Capability ownership remains in Electron Main and defaults to false. Renderer can read but cannot override it; disabled/public behavior remains the existing direct six-digit Binding dialog.
- Main owns literal `http://192.168.4.1/`, validates exact local wire shapes, checks the capability before calling the opener, and returns before access-token/upstream code.
- Preserve same-process same-code/Agent operation identity retry. Invalid/expired code clears both code and retry identity; application restart persists neither.
- Treat Binding success as account association only and show that the device may still be offline.
- Do not modify canonical project memory from this feature task; record only this task's progress and promotion candidates.

## Project Context Loaded

- Task: `20260816-guided-hotspot-binding-7c4d2e`, Feature mode, isolated worktree and branch, base `54443232dd6a07dc1f3df5b33df00f665540497a`.
- Read: active task record, Concurrent/Planning/Coding gates, project memory index, project positioning, current state, decision index, ADR-002, system overview, evidence/reflection/commitment indexes, source proposal `14afe4a`, related Robot source/tests, and every registered peer task's Scope/Intent/Promotion sections.
- Peer assessment: prior Robot configuration tasks are completed and do not overlap the new local portal or wizard seams. The earlier Security 2/automatic-claim proposal conflicts semantically but is explicitly superseded for V1 by accepted ADR-002. No active peer owns this task's worktree or is implementing the same seam.
- Gate result: Concurrent Task Gate and Planning Gate passed. The feature remains default-off because exact shipped firmware, issuer/validator behavior, Electron external-open E2E, and physical smoke are not yet verified.

## Plan

1. Extend the typed Renderer API with strict capability/open response readers and freeze their exact Host requests in unit tests.
2. Add dependency-injected, default-off local Main routes for capability and fixed portal open; prove no token/upstream access, exact body/query handling, error redaction, and non-retryable invalid-code projection.
3. Embed a small in-memory guided/manual state machine in the current Binding dialog, keep cancellation/back disabled during Binding, and preserve current direct Binding when gated off.
4. Cover both paths, legal transitions, portal failures, cleanup, retry identity, and bound-without-online copy in page tests.
5. Run focused tests, typecheck, scoped lint, production build, project-document gates, and independent Sol final review. Do not enable the capability or claim physical acceptance.

## Outcome

- Implemented the accepted Guided Hotspot Binding V1 entirely in Makelore; the firmware repository was not modified.
- Added strict Renderer facade methods for the Main-owned capability and fixed portal-open action. Expanded or malformed DTOs fail closed.
- Added default-off local Host API branches that run before Works token/upstream handling, accept only the exact method/query/body shapes, open only `http://192.168.4.1/`, and redact native opener failures.
- Added the guided/manual Binding state machine to the existing Robot dialog, including legal back/cancel behavior, unencrypted-hotspot and credential-boundary warnings, secret cleanup, an explicit non-cancellable Binding state, and a Bound result that does not claim the robot is online.
- Native portal-open failures expose only the same fixed address with a copy fallback; no caller-provided or user-entered URL is accepted. Binding conflict/already-bound outcomes refresh the current overview without replacing the safe upstream message.
- Preserved the current direct six-digit Binding path when the capability is disabled. Same-process ambiguous retries retain identity only for the same code/Agent; invalid codes discard it even if an upstream response incorrectly marks them retryable.
- The capability remains disabled by default. No BLE/Wi-Fi discovery, cloud claim flow, arbitrary URL input, credential collection, or firmware changes were introduced.

## Verification

- PASS: `pnpm vitest run tests/unit/ai-hardware-page.test.tsx tests/unit/ai-hardware-api.test.ts tests/unit/ai-hardware-routes.test.ts` — 3 files, 90 tests.
- PASS: `pnpm run typecheck`.
- PASS: scoped ESLint over all six changed source/test files.
- PASS: `pnpm run build:vite` — Renderer, Electron Main, and Preload production builds completed; existing chunk-size/dynamic-import warnings remain non-blocking.
- PASS: `pnpm test` — 156 files, 1754 tests.
- PASS: `pnpm playwright test tests/e2e/main-navigation.spec.ts` — 2 Electron navigation smoke tests, including entry into the Robot route.
- PASS: focused tests cover capability fail-closed behavior, fixed portal ownership, no token/upstream access, opener error redaction and fixed-address copy recovery, exact wire shapes, default-off direct Binding, every legal guided/direct back transition, cancellation before and after portal handoff, Binding navigation lock, conflict/already-bound refresh, retry identity, restart-style remount cleanup, activation-code cleanup, and Bound-without-online copy.
- Independent Sol review initially returned FAIL with two P2 and one P3: missing fixed-address copy recovery, missing conflict/already-bound overview refresh, and incomplete state-machine regression coverage. All three findings were corrected and the complete verification set was rerun before re-review.
- PASS: independent Sol re-review confirmed all three findings closed and reported no remaining P0–P3 findings.
- Not claimed: the existing Electron fixture cannot reach an authenticated Robot Binding workspace or observe the native external opener. Gate-on external-open E2E, exact shipped firmware/issuer validation, and a physical-device smoke remain release gates before enabling the capability.

## Follow-ups

- Keep `NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING` unset in production until the exact shipped firmware image is confirmed to expose the expected `Xiaozhi-*` SoftAP, portal at `http://192.168.4.1/`, and compatible six-digit issuer/validator behavior.
- Before a pilot, add or extend a real Electron Robot fixture capable of authenticated overview data and native-opener observation, then run Windows/macOS gate-on smoke plus at least one physical-device end-to-end pass.
- Treat nearby-device discovery/selection as a later protocol project. It cannot be delivered honestly with the current unmodified firmware because SoftAP SSID presence is not authenticated device identity.

## Promotion Candidates

- Target canonical document: `.project-docs/40-operations/release-acceptance.md` (or the release-guidance document current at promotion time).
- Proposal: after physical and gate-on Electron evidence exists, document the validated enablement procedure, rollback/default-off behavior, and supported firmware matrix.
- Evidence required: exact shipped firmware image and issuer/validator compatibility, native external-open E2E on supported desktop platforms, and at least one physical-device end-to-end pass.
- Future impact: release owners can enable the Main-owned capability only for a verified product/firmware combination without reinterpreting ADR-002.
- Semantic conflicts: none with ADR-002 while default-off remains authoritative; promotion must not imply authenticated nearby-device discovery or device-online readiness.
- Human confirmation required: yes, from the release owner after the physical and desktop evidence is reviewed.