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: 54443232dd
• 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.