Summary

Four changes that together restore arm/disarm functionality from the Home Assistant alarm panel and cut its end-to-end latency from ~2s to subsecond:

1. Use {{ action }} not {{ value }} in the alarm command_template. Without this, every click landed on the broker as {"action": "None", "code": "..."} and was rejected as "Unknown action."
2. Append a per-process random suffix to the broker client_id. Defends against two MqttConnectionManager instances inside the same container (e.g. a diagnostic script that ran django.setup()) fighting the live daphne client for the same MQTT identity.
3. Treat an empty code field in the MQTT command payload as no-code. Without this, arming with code_arm_required=False was rejected with "Code required." because HA always sends code: "" in the rendered template, and our parser surfaced that as "" rather than None.
4. Lower-cost Argon2 hasher for UserCode PINs (~150-300ms → ~30ms per verify). Alarm PINs are 4-8 digits; the strong user-password cost gives no real attacker bar against a tiny keyspace but stacks ~hundreds of ms on every arm/disarm round trip.

Bug 1 — {{ action }} not {{ value }}

HA's alarm_control_panel.mqtt exposes only action and code to command_template — value is lock.mqtt's variable, not alarm's (HA docs). With {{ value }}, Jinja saw value as undefined and rendered it as the literal string "None", so HA published payloads like:

{"action": "None", "code": "1234"}

Latchpoint's parser uppercased "None" → "NONE", found no match in _ACTION_TO_STATE, and replied "Unknown action." to the error topic without invoking the state machine.

Why nothing caught it: the previous test round-tripped the broken template through json.loads and asserted equality against itself — it locked the bug in place. Replaced with a test that asserts the documented HA variable name, plus a render-simulation test using Django's template engine that proves the action survives substitution as a real string.

Bug 2 — Per-process client_id suffix

When two paho clients share the configured client_id (default "latchpoint-alarm"), the MQTT broker enforces single-client-per-id and boots the older one with session taken over. The loser auto-reconnects within ~1s, ping-ponging forever. Each successful connect fires _after_connect, republishing retained discovery + availability + state.

The collision shape encountered in practice during this debug session: a diagnostic script run via docker exec into the live container called django.setup(), which triggered transports_mqtt.apps.ready() and spawned a second MqttConnectionManager in the same container. Both clients connected as latchpoint-alarm. Same shape would hit any future scenario where a second consumer (parallel deploy, dev side-car, accidental import path) imports transports_mqtt.

Fix: append a per-process random suffix (secrets.token_hex(3), 6 hex chars) to the configured client_id when building the paho client. Stable within one process so reconnects don't churn the broker's view of the live client; divergent across processes so they cannot collide. test_connection() opts into a fresh suffix per call so its throwaway client never knocks the live one off, even from inside the same process.

The 6-hex suffix is sized so the default composed client_id latchpoint-alarm-XXXXXX lands at exactly 23 bytes — the MQTT 3.1 spec limit. paho-mqtt 2.0+ defaults to 3.1.1 (which raises this to 65535), but staying inside the 3.1 limit guards against any stricter broker. 6 hex still gives 16M distinct values, far above what's needed for 1-2 process collision avoidance. The user-facing setting was renamed to Client ID prefix with description noting the 16-char prefix budget; rc=2 connect-error messages were updated to match.

Bug 3 — Empty code field treated as missing

HA's MQTT alarm panel renders the command template with code = code or "", so when a user arms (or disarms) without typing a PIN the broker payload is {"action": "ARM_HOME", "code": ""} — the field is present but empty.

_handle_command_payload returned "" for that case, while the arm branch of handle_mqtt_alarm_command checked code_required = get_setting_bool(profile, "code_arm_required") or raw_code is not None. Empty string is not None, so the handler forced code validation even when code_arm_required was False, and the broker payload came back as error: "Code required.".

Fix: normalize empty/whitespace code to None once at the parser boundary in _handle_command_payload. The disarm branch already used truthiness (if not raw_code:) and was unaffected — collapsing the two representations at the parser removes the boundary inconsistency for any future caller too.

Verified on the live HA instance via the MCP server: alarm_control_panel.latchpoint_alarm already had code_arm_required: false in its state attributes, confirming the discovery republish pipeline was healthy and the failure was purely backend-side.

Perf — Lower-cost Argon2 for PINs

UserCode PINs are 4-8 digits (10K-100M keyspace). Stretching them at the default user-password Argon2 cost (~150-300ms/verify) doesn't materially raise an offline-brute-force attacker's bar — the entire keyspace is recoverable in minutes-to-hours even at strong cost — while the slow verify shows up as a multi-hundred-ms tax on every arm/disarm round trip from the HA MQTT alarm panel.

Add UserCodeArgon2Hasher (algorithm argon2-pin, time_cost=1, memory_cost=8 MiB, parallelism=2; ~30ms/verify) and route create_user_code / update_user_code through it. User passwords keep the strong default. Existing UserCode rows hashed under the original argon2 algorithm continue to verify on the strong hasher with no migration required — check_password resolves by hash prefix.

Combined with Bug 1, HA-driven arm/disarm clicks now land subsecond on the live home-lab broker.

Verification

• ✅ python manage.py test transports_mqtt integrations_home_assistant.tests.test_mqtt_alarm_entity accounts.tests.test_user_codes_hasher -v 2 → 34 tests pass
• ✅ uvx ruff check backend/transports_mqtt/ backend/integrations_home_assistant/ backend/accounts/ backend/alarm/settings_registry.py → clean
• ✅ uvx ruff format --check ... → clean
• ✅ Empirical: live broker capture before this change showed {"action": "None", "code": "1234"} on every click
• ✅ Empirical: HA entity attributes already report code_arm_required: false after the discovery republish — confirmed via MCP ha_get_state alarm_control_panel.latchpoint_alarm

Test plan

After merge and a fresh image is built/redeployed:

• Sniff latchpoint_alarm/alarm/# on the broker
• Click arm-away in HA → expect {"action": "ARM_AWAY", "code": "..."} followed by latchpoint_alarm/alarm/state :: armed_away within ~1s
• Repeat for arm-home, arm-night, and disarm
• Confirm broker mqtt log shows a single stable latchpoint-alarm-XXXXXX client (6 hex chars, no session taken over cycling)
• With code_arm_required: false in alarm settings, click arm-away in HA without typing a PIN → expect successful state transition (not error: "Code required.")
• With code_arm_required: true, arm with a valid PIN → still works
• Disarm with a valid PIN → still works and feels noticeably faster (PIN verify dropped from hundreds of ms to ~30ms)
• In the MQTT settings UI, confirm the field is now labelled "Client ID prefix" with the suffix-explanation description
• If HA's UI still doesn't update after a successful state publish, remove the Latchpoint device under HA's MQTT integration; Latchpoint's _after_connect will republish discovery and HA will recreate the entity with the corrected template.

Files changed

• backend/integrations_home_assistant/mqtt_alarm_entity.py — template variable fix + empty-code normalization in _handle_command_payload
• backend/integrations_home_assistant/tests/test_mqtt_alarm_entity.py — replace mirror-test, add render simulation, add HandleCommandPayloadTests for empty/whitespace/missing/real codes
• backend/transports_mqtt/manager.py — _client_id_suffix in __init__ (3 bytes / 6 hex chars to fit MQTT 3.1's 23-byte limit); _build_client becomes an instance method that appends the suffix and uses the paho 2.0+ kwarg call without a fallback; test_connection overrides with a fresh suffix; rc=2 error messages reference "client_id prefix"
• backend/transports_mqtt/tests/test_manager.py — six tests covering distinct/stable/prefix-preserving/default-prefix/override/MQTT-3.1-length behaviors plus a wiring guard that test_connection forwards a non-live suffix
• backend/alarm/settings_registry.py — client_id schema title renamed to "Client ID prefix" with description explaining the auto-suffix and the 16-char prefix budget
• backend/accounts/hashers.py — new UserCodeArgon2Hasher (argon2-pin, low cost)
• backend/accounts/tests/test_user_codes_hasher.py — coverage for the PIN hasher
• backend/accounts/use_cases/user_codes.py — route create/update through the PIN hasher
• backend/config/settings.py — register the new hasher