From 91921760f0dcebd6135677b1915eb22b4d8cac9d Mon Sep 17 00:00:00 2001
From: TheCryptoDonkey <TheCryptoDonkey@users.noreply.github.com>
Date: Fri, 25 Sep 2026 08:40:36 +0100
Subject: [PATCH 1/6] feat: read the firmware's at-rest report instead of
 inferring it

heartwood-esp32 #192 adds at_rest ("none"/"pin"/"vault"/"encrypted") and
unlock_phone_count to FIRMWARE_INFO and get_status, so Sapwood no longer
has to guess the power-cut recovery mode from side effects it happened
to witness this session. resolveUnlockMode reads the new fields when a
signer sends them, treats an unrecognised value as unknown rather than
guessing, and falls back to the existing inferUnlockMode heuristic for
firmware that predates the report (released beta.17).
---
 src/components/DevicePanel.svelte | 35 ++++++++++++++++------
 src/lib/device.svelte.test.ts     | 24 ++++++++++++++++
 src/lib/device.svelte.ts          | 28 ++++++++++++++++++
 src/lib/phone-unlock.test.ts      | 48 ++++++++++++++++++++++++++++++-
 src/lib/phone-unlock.ts           | 44 ++++++++++++++++++++++++++++
 5 files changed, 170 insertions(+), 9 deletions(-)

diff --git a/src/components/DevicePanel.svelte b/src/components/DevicePanel.svelte
index 8cca18a..bb16d5c 100644
--- a/src/components/DevicePanel.svelte
+++ b/src/components/DevicePanel.svelte
@@ -23,7 +23,7 @@
   import {
     PAIRING_BACKUP_EVENT, pairingBackupStatus, type PairingBackupStatus,
   } from '../lib/pairing-backup.js'
-  import { inferUnlockMode, type UnlockMode } from '../lib/phone-unlock.js'
+  import { resolveUnlockMode, type UnlockMode } from '../lib/phone-unlock.js'
   import Connectivity from './Connectivity.svelte'
   import UnlockPhones from './UnlockPhones.svelte'
   import OtaUpdate from './OtaUpdate.svelte'
@@ -74,6 +74,7 @@
     max_sign_bytes?: number; max_sign_bytes_object?: number
     free_heap?: number; largest_block?: number
     nvs_used_entries?: number; nvs_free_entries?: number; nvs_total_entries?: number
+    at_rest?: string; unlock_phone_count?: number | null
   } | null>(null)
   $effect(() => {
     if (device.connected && device.mode === 'serial') {
@@ -372,16 +373,34 @@
   }
 
   // --- After a power cut: the three modes ---
-  // The signer does not report whether it is encrypted, so the current mode
-  // is inferred (inferUnlockMode) and left unmarked when it cannot be told.
-  // "No encryption" is never a default: turning encryption off, by either
-  // route, waits for the owner to confirm the sentence that says what it costs.
+  // Firmware ≥ #192 reports `at_rest`/`unlock_phone_count` directly (over USB
+  // on FIRMWARE_INFO, over the relay on get_status), so the mode is read
+  // rather than inferred where a signer sends it. Older firmware (released
+  // beta.17) sends neither: resolveUnlockMode falls back to its side-effect
+  // guess (inferUnlockMode) and the mode is left unmarked when even that
+  // cannot tell. "No encryption" is never a default: turning encryption off,
+  // by either route, waits for the owner to confirm the sentence that says
+  // what it costs.
+  const atRestReport = $derived(
+    device.mode === 'relay' ? device.relayStatus?.at_rest
+      : device.mode === 'serial' ? usbHealth?.at_rest
+        : undefined,
+  )
+  // The firmware's own phone count is available even while locked (before
+  // any PIN/vault secret is entered), unlike the enumerated list below, which
+  // needs an authenticated session. Prefer it when the signer sends it.
+  const unlockPhoneCountReport = $derived(
+    device.mode === 'relay' ? device.relayStatus?.unlock_phone_count
+      : device.mode === 'serial' ? usbHealth?.unlock_phone_count
+        : undefined,
+  )
   let phoneCount = $state<number | null>(null)
+  const effectivePhoneCount = $derived(unlockPhoneCountReport !== undefined ? unlockPhoneCountReport : phoneCount)
   /** Bumped when this page changed encryption: turning it off drops every phone. */
   let phonesRefresh = $state(0)
   /** What this session saw the signer accept; null until then. */
   let encryptionKnown = $state<boolean | null>(null)
-  const currentMode = $derived(inferUnlockMode(phoneCount, !!vaultStored, encryptionKnown))
+  const currentMode = $derived(resolveUnlockMode(atRestReport, effectivePhoneCount, !!vaultStored, encryptionKnown))
   let chosenMode = $state<UnlockMode | null>(null)
   let modesSection = $state<HTMLElement | null>(null)
   let noEncryptionAck = $state(false)
@@ -615,7 +634,7 @@
                     <p class="hint-sm">Add a phone below{overUsb ? '' : ', with the signer on the USB cable'}. Encryption is already on.</p>
                   {/if}
                 {:else if mode.id === 'sapwood'}
-                  {#if (phoneCount ?? 0) > 0}
+                  {#if (effectivePhoneCount ?? 0) > 0}
                     <p class="hint-sm">Revoke each phone below. Encryption stays on.</p>
                   {:else}
                     <p class="hint-sm">Turn on Encrypt at rest (Security{overUsb ? ', below' : ', over the USB cable'}), or set a boot PIN.</p>
@@ -626,7 +645,7 @@
                   {:else}
                     <label class="hint-sm ack">
                       <input type="checkbox" bind:checked={noEncryptionAck} disabled={vaultPending} />
-                      {NO_ENCRYPTION_RISK}{#if (phoneCount ?? 0) > 0}&#32;Every phone stops being able to unlock it.{/if}
+                      {NO_ENCRYPTION_RISK}{#if (effectivePhoneCount ?? 0) > 0}&#32;Every phone stops being able to unlock it.{/if}
                     </label>
                     {#if vaultStored}
                       <button class="btn btn-danger btn-sm" disabled={!noEncryptionAck || vaultPending}
diff --git a/src/lib/device.svelte.test.ts b/src/lib/device.svelte.test.ts
index 20afd33..f547d7e 100644
--- a/src/lib/device.svelte.test.ts
+++ b/src/lib/device.svelte.test.ts
@@ -1534,6 +1534,30 @@ describe('identity card auto-sync on serial master list', () => {
     }
   })
 
+  it('reports a damaged phone blob as null, not zero, over the relay', async () => {
+    const { pubHex } = freshMaster()
+    const activeRelays = ['wss://active.example']
+    relayRequestMock.mockImplementation(async (method: unknown) => {
+      if (method === 'get_status') {
+        return {
+          master_count: 1, master_npub_hex: pubHex, mode: 'wifi-standalone', relay: activeRelays[0],
+          at_rest: 'pin', unlock_phone_count: null,
+        }
+      }
+      if (method === 'get_network_config') return remoteNetworkResponse(activeRelays)
+      if (method === 'list_clients') return { clients: [] }
+      return { ok: true }
+    })
+
+    await connectRelay(pubHex, activeRelays)
+    try {
+      expect(device.relayStatus?.at_rest).toBe('pin')
+      expect(device.relayStatus?.unlock_phone_count).toBeNull()
+    } finally {
+      await disconnect()
+    }
+  })
+
   it('ignores a configured-route completion from an obsolete connection generation', async () => {
     const { pubHex } = freshMaster()
     const relayA = ['wss://country-a.example']
diff --git a/src/lib/device.svelte.ts b/src/lib/device.svelte.ts
index 879c41f..4403f6c 100644
--- a/src/lib/device.svelte.ts
+++ b/src/lib/device.svelte.ts
@@ -96,6 +96,16 @@ export interface RelayStatus {
   nvs?: { used_entries: number; free_entries: number; total_entries: number } | null
   /** Persona registry ceiling for this board (absent on older firmware). */
   max_personas?: number
+  /** How the signer's seeds are protected at rest (plan G2; absent on
+   *  firmware before #192, released beta.17 does not send it). `"encrypted"`
+   *  means sealed, but which secret (PIN or vault) is unknown. Device
+   *  operator only: never sent to a per-identity delegate. */
+  at_rest?: string
+  /** How many phones can unlock this board (plan G2; absent alongside
+   *  `at_rest` on older firmware). `null` means a present phone record is
+   *  damaged, not that there are none — always `0` once `at_rest` is
+   *  `"none"`. Device operator only. */
+  unlock_phone_count?: number | null
 }
 
 /** Network state returned by relay management. Password material is never
@@ -850,6 +860,10 @@ function applyRelayStatus(raw: Record<string, unknown>) {
     ...(raw.truncated === true ? { truncated: true } : {}),
     ...(isNvsStats(raw.nvs) ? { nvs: raw.nvs } : {}),
     ...(typeof raw.max_personas === 'number' ? { max_personas: raw.max_personas } : {}),
+    ...(typeof raw.at_rest === 'string' ? { at_rest: raw.at_rest } : {}),
+    ...('unlock_phone_count' in raw
+      ? { unlock_phone_count: typeof raw.unlock_phone_count === 'number' ? raw.unlock_phone_count : null }
+      : {}),
   }
   device.relayStatus = status
   const masterHex = String(raw.master_npub_hex ?? '')
@@ -2789,6 +2803,16 @@ export interface FirmwareInfo {
   nvs_total_entries?: number
   /** Persona registry ceiling for this board (absent on older firmware). */
   max_personas?: number
+  /** How the signer's seeds are protected at rest (plan G2; absent on
+   *  firmware before #192, released beta.17 does not send it). `"encrypted"`
+   *  means sealed, but which secret (PIN or vault) is unknown. Answered even
+   *  while locked, before any PIN or vault key is entered. */
+  at_rest?: string
+  /** How many phones can unlock this board (plan G2; absent alongside
+   *  `at_rest` on older firmware). `null` means a present phone record is
+   *  damaged, not that there are none — always `0` once `at_rest` is
+   *  `"none"`. */
+  unlock_phone_count?: number | null
 }
 
 /**
@@ -2820,6 +2844,10 @@ export async function getFirmwareVersion(): Promise<FirmwareInfo | null> {
       ...(typeof info.nvs_free_entries === 'number' ? { nvs_free_entries: info.nvs_free_entries } : {}),
       ...(typeof info.nvs_total_entries === 'number' ? { nvs_total_entries: info.nvs_total_entries } : {}),
       ...(typeof info.max_personas === 'number' ? { max_personas: info.max_personas } : {}),
+      ...(typeof info.at_rest === 'string' ? { at_rest: info.at_rest } : {}),
+      ...('unlock_phone_count' in info
+        ? { unlock_phone_count: typeof info.unlock_phone_count === 'number' ? info.unlock_phone_count : null }
+        : {}),
     }
   } catch {
     return null // older firmware, or no response — treat as unknown
diff --git a/src/lib/phone-unlock.test.ts b/src/lib/phone-unlock.test.ts
index e31344a..62dee46 100644
--- a/src/lib/phone-unlock.test.ts
+++ b/src/lib/phone-unlock.test.ts
@@ -3,7 +3,7 @@ import { verifyEvent } from 'nostr-tools/pure'
 import {
   HANDOFF_KIND, HandOffUndelivered, buildHandOffEvent, checkCode, enrolPhone,
   findOrphanedPhoneId, fitLabel, friendlyEnrolRefusal, inferUnlockMode, parseEnrolAnswer,
-  parseEnrolmentCode, parsePhoneList, requestCode, requestWords,
+  parseEnrolmentCode, parsePhoneList, requestCode, requestWords, resolveUnlockMode,
 } from './phone-unlock.js'
 
 const P = 'a1'.repeat(32)
@@ -232,3 +232,49 @@ describe('findOrphanedPhoneId', () => {
     expect(findOrphanedPhoneId([A], [A, B, C])).toBeNull()
   })
 })
+
+describe('resolveUnlockMode', () => {
+  it('reads "none" from the firmware report directly, whatever the phone count', () => {
+    expect(resolveUnlockMode('none', 0, false)).toBe('none')
+    expect(resolveUnlockMode('none', 5, false)).toBe('none')
+    expect(resolveUnlockMode('none', null, true)).toBe('none')
+  })
+
+  it('reads "pin" as sapwood-or-pin unless phones are enrolled', () => {
+    expect(resolveUnlockMode('pin', 0, false)).toBe('sapwood')
+    expect(resolveUnlockMode('pin', 2, false)).toBe('phone')
+  })
+
+  it('reads "vault" as sapwood-or-pin unless phones are enrolled', () => {
+    expect(resolveUnlockMode('vault', 0, false)).toBe('sapwood')
+    expect(resolveUnlockMode('vault', 3, false)).toBe('phone')
+  })
+
+  it('reads "encrypted" (sealed, kind unknown) the same as pin/vault', () => {
+    expect(resolveUnlockMode('encrypted', 0, false)).toBe('sapwood')
+    expect(resolveUnlockMode('encrypted', 1, false)).toBe('phone')
+  })
+
+  it('treats a null phone count (damaged blob) as no known phone, never a guessed phone mode', () => {
+    expect(resolveUnlockMode('vault', null, false)).toBe('sapwood')
+    expect(resolveUnlockMode('pin', null, true)).toBe('sapwood')
+  })
+
+  it('falls back to inferUnlockMode when the firmware sends no at_rest field at all', () => {
+    expect(resolveUnlockMode(undefined, 2, false)).toBe('phone')
+    expect(resolveUnlockMode(undefined, 0, true)).toBe('sapwood')
+    expect(resolveUnlockMode(undefined, 0, false)).toBeNull()
+  })
+
+  it('reports an unrecognised at_rest value as unknown, never a guess', () => {
+    expect(resolveUnlockMode('quantum', 2, true)).toBeNull()
+    expect(resolveUnlockMode('', 0, false)).toBeNull()
+  })
+
+  it('lets a known session action override the firmware report until it resets to null', () => {
+    // The signer just turned encryption off, but the last poll's `at_rest`
+    // has not caught up yet — the session's own action wins.
+    expect(resolveUnlockMode('vault', 2, true, false)).toBe('none')
+    expect(resolveUnlockMode('none', 0, false, true)).toBe('sapwood')
+  })
+})
diff --git a/src/lib/phone-unlock.ts b/src/lib/phone-unlock.ts
index 4ce60af..a328be5 100644
--- a/src/lib/phone-unlock.ts
+++ b/src/lib/phone-unlock.ts
@@ -330,6 +330,10 @@ export type UnlockMode = 'none' | 'phone' | 'sapwood'
  * encryption turned off), and outranks a vault key this browser merely
  * holds. Anything else might be a boot PIN, or nothing: Sapwood cannot tell,
  * returns null, and says so rather than guess.
+ *
+ * Kept as the fallback for firmware that predates the `at_rest` report
+ * (released beta.17) — see `resolveUnlockMode`, which callers should use
+ * instead.
  */
 export function inferUnlockMode(
   phones: number | null,
@@ -342,6 +346,46 @@ export function inferUnlockMode(
   return null
 }
 
+/** Wire values for the firmware's own at-rest report (FIRMWARE_INFO and
+ *  get_status's `at_rest`, plan G2). Any other string is unknown to this
+ *  build and must never be guessed at. */
+const KNOWN_AT_REST_VALUES = ['none', 'pin', 'vault', 'encrypted'] as const
+export type AtRestReport = (typeof KNOWN_AT_REST_VALUES)[number]
+
+function isKnownAtRest(value: string): value is AtRestReport {
+  return (KNOWN_AT_REST_VALUES as readonly string[]).includes(value)
+}
+
+/**
+ * The mode shown in "After a power cut". Firmware ≥ #192 reports `at_rest`
+ * and `unlock_phone_count` directly, on both FIRMWARE_INFO and get_status
+ * (device operator only there — a delegate never sees either field), so this
+ * reads those instead of guessing from side effects.
+ *
+ * `known` — what this page saw the signer accept moments ago (a seal, a PIN
+ * set, or encryption turned off) — still wins when set: it reflects an
+ * action this session just took, ahead of a firmware report that has not
+ * been re-polled since. Once it resets to null, the firmware's own answer
+ * takes over.
+ *
+ * `atRest` absent (`undefined`) means older firmware that never sends the
+ * field (released beta.17): fall back to `inferUnlockMode`'s guess. A
+ * present but unrecognised value is reported as unknown (null) rather than
+ * mapped to whatever meaning looks closest — a future wire value must never
+ * be silently reinterpreted.
+ */
+export function resolveUnlockMode(
+  atRest: string | undefined,
+  phones: number | null,
+  vaultKeyHeld: boolean,
+  known: boolean | null = null,
+): UnlockMode | null {
+  if (known !== null || atRest === undefined) return inferUnlockMode(phones, vaultKeyHeld, known)
+  if (!isKnownAtRest(atRest)) return null
+  if (atRest === 'none') return 'none'
+  return phones !== null && phones > 0 ? 'phone' : 'sapwood'
+}
+
 /** The board kept a record, but no relay took the hand-off to the phone. */
 export class HandOffUndelivered extends Error {
   constructor(readonly id: number) {

From ff8c75f8d70922dc32596b2a226dde582af7884b Mon Sep 17 00:00:00 2001
From: TheCryptoDonkey <TheCryptoDonkey@users.noreply.github.com>
Date: Fri, 25 Sep 2026 08:43:08 +0100
Subject: [PATCH 2/6] fix: keep capabilities and slots across a truncated
 get_status reply

applyRelayStatus overwrote capabilities and slots to empty/zero whenever
a get_status reply set truncated: true (the low-heap fallback that trims
the request log and relay lists), breaking persona pairing until the
next full poll. The truncated reply never carried those two fields to
begin with, so carry the previous poll's values forward instead of
clearing them; at_rest and unlock_phone_count need no such handling,
since the firmware sends both fresh even on a truncated reply.
---
 src/lib/device.svelte.test.ts | 43 +++++++++++++++++++++++++++++++++++
 src/lib/device.svelte.ts      | 16 +++++++++++--
 2 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/src/lib/device.svelte.test.ts b/src/lib/device.svelte.test.ts
index f547d7e..de0cbdd 100644
--- a/src/lib/device.svelte.test.ts
+++ b/src/lib/device.svelte.test.ts
@@ -1534,6 +1534,49 @@ describe('identity card auto-sync on serial master list', () => {
     }
   })
 
+  it('keeps capabilities and slots from the last full poll when a reply is truncated', async () => {
+    const { pubHex } = freshMaster()
+    const activeRelays = ['wss://active.example']
+    let truncated = false
+    relayRequestMock.mockImplementation(async (method: unknown) => {
+      if (method === 'get_status') {
+        if (truncated) {
+          // A trimmed low-heap reply (minimal_status_json in relay.rs): no
+          // capabilities/slots, but at_rest/unlock_phone_count still ride it.
+          return {
+            master_count: 1, master_npub_hex: pubHex, mode: 'wifi-standalone', relay: activeRelays[0],
+            at_rest: 'vault', unlock_phone_count: 2, truncated: true,
+          }
+        }
+        return {
+          master_count: 1, master_npub_hex: pubHex, mode: 'wifi-standalone', relay: activeRelays[0],
+          capabilities: ['phone_unlock_v1'], slots: 3, at_rest: 'vault', unlock_phone_count: 2,
+        }
+      }
+      if (method === 'get_network_config') return remoteNetworkResponse(activeRelays)
+      if (method === 'list_clients') return { clients: [] }
+      return { ok: true }
+    })
+
+    await connectRelay(pubHex, activeRelays)
+    try {
+      expect(device.relayStatus?.truncated).toBeUndefined()
+      expect(device.relayStatus?.capabilities).toEqual(['phone_unlock_v1'])
+      expect(device.relayStatus?.slots).toBe(3)
+
+      truncated = true
+      await refreshRelayAudit()
+
+      expect(device.relayStatus?.truncated).toBe(true)
+      expect(device.relayStatus?.capabilities).toEqual(['phone_unlock_v1'])
+      expect(device.relayStatus?.slots).toBe(3)
+      expect(device.relayStatus?.at_rest).toBe('vault')
+      expect(device.relayStatus?.unlock_phone_count).toBe(2)
+    } finally {
+      await disconnect()
+    }
+  })
+
   it('reports a damaged phone blob as null, not zero, over the relay', async () => {
     const { pubHex } = freshMaster()
     const activeRelays = ['wss://active.example']
diff --git a/src/lib/device.svelte.ts b/src/lib/device.svelte.ts
index 4403f6c..6c785ca 100644
--- a/src/lib/device.svelte.ts
+++ b/src/lib/device.svelte.ts
@@ -840,14 +840,26 @@ function isNvsStats(
 
 function applyRelayStatus(raw: Record<string, unknown>) {
   appendRelayAudit(Array.isArray(raw.audit) ? raw.audit as RelayAuditEntry[] : [])
+  // A truncated reply (low-heap fallback, `minimal_status_json` in
+  // firmware/src/relay.rs) drops `capabilities` and `slots` to save the
+  // allocation their policy-engine calls would cost — it is not saying the
+  // signer has none. Carry the previous poll's values forward instead of
+  // collapsing them to empty/zero, or a manager watching a fragmented-heap
+  // signer sees pairing capability vanish and persona pairing breaks until
+  // the heap recovers and a full poll lands. `at_rest`/`unlock_phone_count`
+  // need no such carry-forward: the truncated reply still sends them fresh.
+  const truncated = raw.truncated === true
+  const previous = device.relayStatus
   const status: RelayStatus = {
     master_count: Number(raw.master_count ?? 0),
-    slots: Number(raw.slots ?? 0),
+    slots: typeof raw.slots === 'number'
+      ? raw.slots
+      : truncated && previous ? previous.slots : Number(raw.slots ?? 0),
     mode: String(raw.mode ?? 'wifi-standalone'),
     relay: String(raw.relay ?? ''),
     capabilities: Array.isArray(raw.capabilities)
       ? raw.capabilities.filter((value): value is string => typeof value === 'string')
-      : [],
+      : truncated && previous ? previous.capabilities : [],
     ...(typeof raw.uptime_s === 'number' ? { uptime_s: raw.uptime_s } : {}),
     ...(typeof raw.last_reset === 'string' ? { last_reset: raw.last_reset } : {}),
     ...(typeof raw.crashed_during === 'string' ? { crashed_during: raw.crashed_during } : {}),

From 9f9a54007720188cdc32664f876c70ceed977577 Mon Sep 17 00:00:00 2001
From: TheCryptoDonkey <TheCryptoDonkey@users.noreply.github.com>
Date: Fri, 25 Sep 2026 08:48:00 +0100
Subject: [PATCH 3/6] style: drop em dashes from the at-rest comments

---
 src/lib/device.svelte.ts     |  6 +++---
 src/lib/phone-unlock.test.ts |  2 +-
 src/lib/phone-unlock.ts      | 10 +++++-----
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/lib/device.svelte.ts b/src/lib/device.svelte.ts
index 6c785ca..73175ad 100644
--- a/src/lib/device.svelte.ts
+++ b/src/lib/device.svelte.ts
@@ -103,7 +103,7 @@ export interface RelayStatus {
   at_rest?: string
   /** How many phones can unlock this board (plan G2; absent alongside
    *  `at_rest` on older firmware). `null` means a present phone record is
-   *  damaged, not that there are none — always `0` once `at_rest` is
+   *  damaged, not that there are none; always `0` once `at_rest` is
    *  `"none"`. Device operator only. */
   unlock_phone_count?: number | null
 }
@@ -842,7 +842,7 @@ function applyRelayStatus(raw: Record<string, unknown>) {
   appendRelayAudit(Array.isArray(raw.audit) ? raw.audit as RelayAuditEntry[] : [])
   // A truncated reply (low-heap fallback, `minimal_status_json` in
   // firmware/src/relay.rs) drops `capabilities` and `slots` to save the
-  // allocation their policy-engine calls would cost — it is not saying the
+  // allocation their policy-engine calls would cost; it is not saying the
   // signer has none. Carry the previous poll's values forward instead of
   // collapsing them to empty/zero, or a manager watching a fragmented-heap
   // signer sees pairing capability vanish and persona pairing breaks until
@@ -2822,7 +2822,7 @@ export interface FirmwareInfo {
   at_rest?: string
   /** How many phones can unlock this board (plan G2; absent alongside
    *  `at_rest` on older firmware). `null` means a present phone record is
-   *  damaged, not that there are none — always `0` once `at_rest` is
+   *  damaged, not that there are none; always `0` once `at_rest` is
    *  `"none"`. */
   unlock_phone_count?: number | null
 }
diff --git a/src/lib/phone-unlock.test.ts b/src/lib/phone-unlock.test.ts
index 62dee46..6e4452d 100644
--- a/src/lib/phone-unlock.test.ts
+++ b/src/lib/phone-unlock.test.ts
@@ -273,7 +273,7 @@ describe('resolveUnlockMode', () => {
 
   it('lets a known session action override the firmware report until it resets to null', () => {
     // The signer just turned encryption off, but the last poll's `at_rest`
-    // has not caught up yet — the session's own action wins.
+    // has not caught up yet; the session's own action wins.
     expect(resolveUnlockMode('vault', 2, true, false)).toBe('none')
     expect(resolveUnlockMode('none', 0, false, true)).toBe('sapwood')
   })
diff --git a/src/lib/phone-unlock.ts b/src/lib/phone-unlock.ts
index a328be5..2a3213b 100644
--- a/src/lib/phone-unlock.ts
+++ b/src/lib/phone-unlock.ts
@@ -332,7 +332,7 @@ export type UnlockMode = 'none' | 'phone' | 'sapwood'
  * returns null, and says so rather than guess.
  *
  * Kept as the fallback for firmware that predates the `at_rest` report
- * (released beta.17) — see `resolveUnlockMode`, which callers should use
+ * (released beta.17); see `resolveUnlockMode`, which callers should use
  * instead.
  */
 export function inferUnlockMode(
@@ -359,11 +359,11 @@ function isKnownAtRest(value: string): value is AtRestReport {
 /**
  * The mode shown in "After a power cut". Firmware ≥ #192 reports `at_rest`
  * and `unlock_phone_count` directly, on both FIRMWARE_INFO and get_status
- * (device operator only there — a delegate never sees either field), so this
+ * (device operator only there; a delegate never sees either field), so this
  * reads those instead of guessing from side effects.
  *
- * `known` — what this page saw the signer accept moments ago (a seal, a PIN
- * set, or encryption turned off) — still wins when set: it reflects an
+ * `known`, what this page saw the signer accept moments ago (a seal, a PIN
+ * set, or encryption turned off), still wins when set: it reflects an
  * action this session just took, ahead of a firmware report that has not
  * been re-polled since. Once it resets to null, the firmware's own answer
  * takes over.
@@ -371,7 +371,7 @@ function isKnownAtRest(value: string): value is AtRestReport {
  * `atRest` absent (`undefined`) means older firmware that never sends the
  * field (released beta.17): fall back to `inferUnlockMode`'s guess. A
  * present but unrecognised value is reported as unknown (null) rather than
- * mapped to whatever meaning looks closest — a future wire value must never
+ * mapped to whatever meaning looks closest; a future wire value must never
  * be silently reinterpreted.
  */
 export function resolveUnlockMode(

From e45df024ce858bf47806bc4678596d40a125b5df Mon Sep 17 00:00:00 2001
From: TheCryptoDonkey <TheCryptoDonkey@users.noreply.github.com>
Date: Sat, 26 Sep 2026 01:51:38 +0100
Subject: [PATCH 4/6] fix: let a fresh at-rest report retire a stale session
 override

resolveUnlockMode's known override was set once by a PIN, seal or
disable action and never reset, so it kept overruling a later
at_rest report for as long as the tab stayed open. Add
shouldRetireEncryptionKnown, comparing the report seen when the
override was set against the latest one, so a differing report
(a relay poll catching up, or a fresh USB read) lets the firmware's
own answer take over again.
---
 src/lib/phone-unlock.test.ts | 20 ++++++++++++++++++++
 src/lib/phone-unlock.ts      | 12 ++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/src/lib/phone-unlock.test.ts b/src/lib/phone-unlock.test.ts
index 6e4452d..48593f1 100644
--- a/src/lib/phone-unlock.test.ts
+++ b/src/lib/phone-unlock.test.ts
@@ -4,6 +4,7 @@ import {
   HANDOFF_KIND, HandOffUndelivered, buildHandOffEvent, checkCode, enrolPhone,
   findOrphanedPhoneId, fitLabel, friendlyEnrolRefusal, inferUnlockMode, parseEnrolAnswer,
   parseEnrolmentCode, parsePhoneList, requestCode, requestWords, resolveUnlockMode,
+  shouldRetireEncryptionKnown,
 } from './phone-unlock.js'
 
 const P = 'a1'.repeat(32)
@@ -278,3 +279,22 @@ describe('resolveUnlockMode', () => {
     expect(resolveUnlockMode('none', 0, false, true)).toBe('sapwood')
   })
 })
+
+describe('shouldRetireEncryptionKnown', () => {
+  it('keeps the override while no fresh report has arrived', () => {
+    expect(shouldRetireEncryptionKnown(undefined, undefined)).toBe(false)
+    expect(shouldRetireEncryptionKnown(undefined, 'none')).toBe(false)
+  })
+
+  it('keeps the override while the report still matches the baseline seen when it was set', () => {
+    expect(shouldRetireEncryptionKnown('none', 'none')).toBe(false)
+  })
+
+  it('retires the override once a report differs from the baseline, whichever way', () => {
+    // A relay poll catching up with an action just taken this session.
+    expect(shouldRetireEncryptionKnown('vault', 'none')).toBe(true)
+    // A report that changed for some other reason entirely (e.g. another
+    // session, or the board itself) also retires a now-stale override.
+    expect(shouldRetireEncryptionKnown('none', 'vault')).toBe(true)
+  })
+})
diff --git a/src/lib/phone-unlock.ts b/src/lib/phone-unlock.ts
index 2a3213b..ad2d9af 100644
--- a/src/lib/phone-unlock.ts
+++ b/src/lib/phone-unlock.ts
@@ -386,6 +386,18 @@ export function resolveUnlockMode(
   return phones !== null && phones > 0 ? 'phone' : 'sapwood'
 }
 
+/**
+ * Whether a session's `known` override (see `resolveUnlockMode`) has done its
+ * job and should stand down. `baseline` is the firmware's `at_rest` value at
+ * the moment the override was set (possibly still undefined, on firmware that
+ * sends none); once a later report differs from that baseline, either a relay
+ * poll caught up or a fresh USB read landed, and the firmware's own answer
+ * should take over again rather than the override blocking it indefinitely.
+ */
+export function shouldRetireEncryptionKnown(atRest: string | undefined, baseline: string | undefined): boolean {
+  return atRest !== undefined && atRest !== baseline
+}
+
 /** The board kept a record, but no relay took the hand-off to the phone. */
 export class HandOffUndelivered extends Error {
   constructor(readonly id: number) {

From cea55df51254b2b2de58cd216642184da63b797b Mon Sep 17 00:00:00 2001
From: TheCryptoDonkey <TheCryptoDonkey@users.noreply.github.com>
Date: Sat, 26 Sep 2026 01:51:44 +0100
Subject: [PATCH 5/6] fix: word an unrecognised at-rest report differently from
 no report

"Unknown: no vault key held here" and "Connect by USB to check" both
blame missing information, but a firmware that sends an at_rest
value this build does not recognise has told Sapwood something, just
not something it understands yet. Add atRestUnrecognised to
DeviceSummaryInput so the power-cut row can say "update Sapwood"
instead, and update the doc comment on unlockMode, which still said
"inferred" now that a firmware report is read directly when sent.
---
 src/lib/device-summary.test.ts | 11 +++++++++++
 src/lib/device-summary.ts      | 16 ++++++++++++----
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/lib/device-summary.test.ts b/src/lib/device-summary.test.ts
index 3053400..906d629 100644
--- a/src/lib/device-summary.test.ts
+++ b/src/lib/device-summary.test.ts
@@ -8,6 +8,7 @@ function base(overrides: Partial<DeviceSummaryInput> = {}): DeviceSummaryInput {
     runningVersion: '0.18.0',
     unlockMode: 'sapwood',
     phoneCount: null,
+    atRestUnrecognised: false,
     overUsb: true,
     needsBackup: false,
     lastExportAt: Date.parse('2026-09-01T00:00:00Z'),
@@ -73,6 +74,16 @@ describe('deviceSummaryRows', () => {
     expect(row.text).toBe('Unknown: no vault key held here')
   })
 
+  it('names an unrecognised firmware report distinctly, over USB or WiFi', () => {
+    const usb = deviceSummaryRows(base({ unlockMode: null, overUsb: true, atRestUnrecognised: true }))
+    const wifi = deviceSummaryRows(base({ unlockMode: null, overUsb: false, modeLabel: 'WiFi', atRestUnrecognised: true }))
+    for (const rows of [usb, wifi]) {
+      const row = rows.find((r) => r.id === 'power-cut')!
+      expect(row.dot).toBe('unknown')
+      expect(row.text).toBe("Your signer reported a setting this version of Sapwood doesn't know. Update Sapwood.")
+    }
+  })
+
   it('reads a fresh backup with its date, green', () => {
     const rows = deviceSummaryRows(base({ lastExportAt: Date.parse('2026-09-01T00:00:00Z') }))
     const row = rows.find((r) => r.id === 'backup')!
diff --git a/src/lib/device-summary.ts b/src/lib/device-summary.ts
index 0a64d4f..b8b87dd 100644
--- a/src/lib/device-summary.ts
+++ b/src/lib/device-summary.ts
@@ -27,9 +27,15 @@ export interface DeviceSummaryInput {
   updateAvailable: boolean
   updateVersion: string | null
   runningVersion: string | null
-  /** The inferred after-a-power-cut mode; null when it cannot be told. */
+  /** The after-a-power-cut mode: read from the firmware's own `at_rest`
+   *  report when it sends one, otherwise inferred from side effects; null
+   *  when it cannot be told either way. */
   unlockMode: UnlockMode | null
   phoneCount: number | null
+  /** The firmware sent an `at_rest` value this build does not recognise, so
+   *  `unlockMode` is null for that reason rather than for lack of any report
+   *  at all. Distinguishes "update Sapwood" from "connect by USB to check". */
+  atRestUnrecognised: boolean
   overUsb: boolean
   needsBackup: boolean
   lastExportAt: number | null
@@ -84,9 +90,11 @@ function powerCutRow(input: DeviceSummaryInput): SummaryRow {
       actionLabel: 'Change',
     }
   }
-  const text = input.overUsb
-    ? 'Unknown: no vault key held here'
-    : `Unknown over ${input.modeLabel}. Connect by USB to check`
+  const text = input.atRestUnrecognised
+    ? "Your signer reported a setting this version of Sapwood doesn't know. Update Sapwood."
+    : input.overUsb
+      ? 'Unknown: no vault key held here'
+      : `Unknown over ${input.modeLabel}. Connect by USB to check`
   return { id: 'power-cut', label, dot: 'unknown', text, actionLabel: 'Change' }
 }
 

From a460cd3d831f45f97e8fce91ec76de4d14c9084d Mon Sep 17 00:00:00 2001
From: TheCryptoDonkey <TheCryptoDonkey@users.noreply.github.com>
Date: Sat, 26 Sep 2026 01:51:54 +0100
Subject: [PATCH 6/6] fix: report the firmware's phone count while locked, not
 the listed one

DevicePanel's summary row fed phoneCount (UnlockPhones' enumerated
list, null until an authenticated session lists it) into
deviceSummaryRows, so a locked signer with phones enrolled read as
"(0 phones)". Pass effectivePhoneCount instead, which prefers the
firmware's own unlock_phone_count, sent even while locked.

Also wires up the two preceding fixes: encryptionKnown now records
the at_rest value it was set against and retires once a later report
disagrees (re-reading FIRMWARE_INFO after a seal or unseal, since it
is otherwise only fetched at connect), and the "After a power cut"
card shows the new unrecognised-report wording alongside the summary
row.
---
 src/components/DevicePanel.svelte  |  46 ++++++++++--
 src/components/DevicePanel.test.ts | 116 +++++++++++++++++++++++++++++
 2 files changed, 156 insertions(+), 6 deletions(-)
 create mode 100644 src/components/DevicePanel.test.ts

diff --git a/src/components/DevicePanel.svelte b/src/components/DevicePanel.svelte
index bb16d5c..256ae51 100644
--- a/src/components/DevicePanel.svelte
+++ b/src/components/DevicePanel.svelte
@@ -23,7 +23,7 @@
   import {
     PAIRING_BACKUP_EVENT, pairingBackupStatus, type PairingBackupStatus,
   } from '../lib/pairing-backup.js'
-  import { resolveUnlockMode, type UnlockMode } from '../lib/phone-unlock.js'
+  import { resolveUnlockMode, shouldRetireEncryptionKnown, type UnlockMode } from '../lib/phone-unlock.js'
   import Connectivity from './Connectivity.svelte'
   import UnlockPhones from './UnlockPhones.svelte'
   import OtaUpdate from './OtaUpdate.svelte'
@@ -197,11 +197,15 @@
         ? (pinValue ? 'PIN set.' : 'PIN cleared. The signer stores its keys in plaintext again, and no phone can unlock it.')
         : 'The device rejected the PIN change.'
       if (frame.type === FrameType.ACK) {
-        encryptionKnown = !!pinValue
+        setEncryptionKnown(!!pinValue)
         // Clearing turns encryption off whichever secret held it, so a vault
         // key this browser kept no longer opens anything.
         if (!pinValue && vaultDeviceKey) { removeVaultKey(vaultDeviceKey); vaultStored = null }
         phonesRefresh++
+        // FIRMWARE_INFO is only fetched at connect, so re-read it now: without
+        // this, usbHealth's at_rest would stay stale until the next reconnect
+        // and the override above would never get to stand down.
+        void getFirmwareVersion().then((info) => { if (info) usbHealth = info })
       }
       pinValue = ''
       clearPinAck = false
@@ -308,7 +312,11 @@
       vaultStored = key
       vaultEscrowKey = null
       vaultShowKey = true
-      encryptionKnown = true
+      setEncryptionKnown(true)
+      // FIRMWARE_INFO is only fetched at connect, so re-read it now: without
+      // this, usbHealth's at_rest would stay stale until the next reconnect
+      // and the override above would never get to stand down.
+      void getFirmwareVersion().then((info) => { if (info) usbHealth = info })
       vaultStatus = 'Encryption at rest is on. The key stays in this browser — keep your off-site copy safe.'
     } catch (e) {
       // The key is already stored (and visible below) whatever happened; a
@@ -334,8 +342,9 @@
       removeVaultKey(vaultDeviceKey)
       vaultStored = null
       vaultShowKey = false
-      encryptionKnown = false
+      setEncryptionKnown(false)
       phonesRefresh++
+      void getFirmwareVersion().then((info) => { if (info) usbHealth = info })
       vaultStatus = 'Encryption at rest is off. The signer stores its keys in plaintext again.'
     } catch (e) {
       vaultStatus = e instanceof Error ? e.message : 'Failed'
@@ -400,7 +409,25 @@
   let phonesRefresh = $state(0)
   /** What this session saw the signer accept; null until then. */
   let encryptionKnown = $state<boolean | null>(null)
+  /** The firmware's `at_rest` value at the moment `encryptionKnown` was set,
+   *  so a later report that differs (a relay poll catching up, or a fresh USB
+   *  read) can retire the override rather than have it block the firmware's
+   *  own answer indefinitely. */
+  let encryptionKnownBaseline = $state<string | undefined>(undefined)
+  function setEncryptionKnown(value: boolean | null) {
+    encryptionKnown = value
+    encryptionKnownBaseline = atRestReport
+  }
+  $effect(() => {
+    if (encryptionKnown !== null && shouldRetireEncryptionKnown(atRestReport, encryptionKnownBaseline)) {
+      encryptionKnown = null
+      encryptionKnownBaseline = undefined
+    }
+  })
   const currentMode = $derived(resolveUnlockMode(atRestReport, effectivePhoneCount, !!vaultStored, encryptionKnown))
+  /** The mode is unknown specifically because the firmware sent an `at_rest`
+   *  value this build does not recognise, not for lack of any report. */
+  const atRestUnrecognised = $derived(currentMode === null && encryptionKnown === null && atRestReport !== undefined)
   let chosenMode = $state<UnlockMode | null>(null)
   let modesSection = $state<HTMLElement | null>(null)
   let noEncryptionAck = $state(false)
@@ -530,7 +557,11 @@
     updateVersion: updateInfo?.latest ?? null,
     runningVersion,
     unlockMode: currentMode,
-    phoneCount,
+    // The firmware's own count (available even while locked) beats the
+    // enumerated list, which needs an authenticated session and is null until
+    // then: a locked signer with phones enrolled must not report "0 phones".
+    phoneCount: effectivePhoneCount,
+    atRestUnrecognised,
     overUsb,
     needsBackup: pairingBackup.needsBackup,
     lastExportAt: pairingBackup.lastExportAt,
@@ -670,7 +701,10 @@
         {/each}
       </div>
       {#if currentMode === null}
-        {#if overUsb}
+        {#if atRestUnrecognised}
+          <p class="hint-sm">Your signer reported a setting this version of Sapwood doesn't know.
+            Update Sapwood.</p>
+        {:else if overUsb}
           <p class="hint-sm">This browser holds no vault key for the signer, and the signer does not
             say whether it has a boot PIN. With neither, it runs without encryption.</p>
         {:else}
diff --git a/src/components/DevicePanel.test.ts b/src/components/DevicePanel.test.ts
new file mode 100644
index 0000000..824cea8
--- /dev/null
+++ b/src/components/DevicePanel.test.ts
@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/svelte'
+import { nip19 } from 'nostr-tools'
+import DevicePanel from './DevicePanel.svelte'
+import { device, serialTransport } from '../lib/device.svelte.js'
+import { FrameType } from '../lib/frame.js'
+
+// device.svelte is mocked (no transport). UnlockPhones only needs
+// listUnlockPhones/PhoneUnlockAuthRequired/supportsPhoneEnrolRelay wired up;
+// a locked signer never calls any of them (it short-circuits to 'locked').
+// Reactive, like Connectivity.test.ts and UnlockPhones.test.ts, so a test can
+// mutate `device` mid-flow and see the component react.
+vi.mock('../lib/device.svelte.js', async () => {
+  const { createSubscriber } = await import('svelte/reactivity')
+  class PhoneUnlockAuthRequired extends Error {}
+  let notify = () => {}
+  const subscribe = createSubscriber((update) => {
+    notify = update
+    return () => { notify = () => {} }
+  })
+  const state: Record<string, unknown> = {
+    connected: true, mode: 'relay', error: null, masters: [], slots: [],
+    relayStatus: null, bridgeAuthed: false, connectionGeneration: 0,
+  }
+  const device = new Proxy(state, {
+    get(target, property, receiver) {
+      subscribe()
+      return Reflect.get(target, property, receiver)
+    },
+    set(target, property, value, receiver) {
+      const changed = Reflect.get(target, property, receiver) !== value
+      const ok = Reflect.set(target, property, value, receiver)
+      if (changed) notify()
+      return ok
+    },
+  })
+  return {
+    device,
+    serialTransport: { sendAndReceive: vi.fn() },
+    httpTransport: { clearClients: vi.fn(), factoryReset: vi.fn() },
+    bridgeRestart: vi.fn(),
+    mgmtRevokeClient: vi.fn(),
+    relaySetLogQuiet: vi.fn(),
+    ensureBridgeAuth: vi.fn().mockResolvedValue(undefined),
+    usbDisplayFlip: vi.fn().mockResolvedValue(null),
+    setDisplayFlip: vi.fn(),
+    getFirmwareVersion: vi.fn().mockResolvedValue(null),
+    listUnlockPhones: vi.fn(),
+    revokeUnlockPhone: vi.fn(),
+    setAnnounceOperator: vi.fn(),
+    enrolUnlockPhone: vi.fn(),
+    supportsPhoneEnrolRelay: vi.fn(() => false),
+    PhoneUnlockAuthRequired,
+  }
+})
+
+const NPUB = nip19.npubEncode('a'.repeat(64))
+
+beforeEach(() => {
+  localStorage.clear()
+  vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('offline in tests')))
+  ;(device as { masters: unknown[] }).masters = []
+  ;(device as { mode: string }).mode = 'relay'
+  ;(device as { relayStatus: unknown }).relayStatus = null
+  vi.mocked(serialTransport.sendAndReceive).mockReset()
+})
+
+describe('DevicePanel summary: locked signer with phones', () => {
+  it('reports the firmware-known phone count, not the (unlisted) enumerated one', async () => {
+    // Locked: UnlockPhones cannot authenticate to list phones, so its own
+    // count binding stays null. The firmware's own unlock_phone_count (sent
+    // even while locked) must still reach the summary row.
+    ;(device as { masters: unknown[] }).masters = [{ slot: 0, locked: true, npub: NPUB }]
+    ;(device as { relayStatus: unknown }).relayStatus = { at_rest: 'encrypted', unlock_phone_count: 2 }
+
+    render(DevicePanel)
+
+    const row = await screen.findByText(/Unlocks from your phone/)
+    expect(row.textContent).toBe('Unlocks from your phone (2 phones)')
+    expect(row.textContent).not.toContain('(0 phones)')
+  })
+})
+
+describe('DevicePanel: the session override on a fresh firmware report', () => {
+  it('stands down once a later FIRMWARE_INFO report disagrees with the value seen when the PIN was set', async () => {
+    ;(device as { mode: string }).mode = 'serial'
+    ;(device as { masters: unknown[] }).masters = [{ slot: 0, npub: NPUB }]
+    // No report yet at mount (older behaviour, or just not fetched): the
+    // firmware's own answer is unknown, so the panel starts on "Unknown".
+    const getFirmwareVersion = (await import('../lib/device.svelte.js')).getFirmwareVersion
+    vi.mocked(getFirmwareVersion).mockResolvedValueOnce(null)
+    vi.mocked(serialTransport.sendAndReceive).mockResolvedValue({ type: FrameType.ACK, payload: new Uint8Array() })
+
+    const { container } = render(DevicePanel)
+    await waitFor(() => expect(screen.getAllByText(/After a power cut/).length).toBeGreaterThan(0))
+
+    const pinInput = container.querySelector('input.field-input[type="password"]') as HTMLInputElement
+    expect(pinInput).toBeTruthy()
+    await fireEvent.input(pinInput, { target: { value: '1234' } })
+
+    // Setting the PIN wins immediately: the session knows encryption just
+    // turned on, well ahead of a re-read of FIRMWARE_INFO.
+    const buttons = Array.from(container.querySelectorAll('button')).filter((b) => b.textContent?.trim() === 'Set PIN')
+    // The re-read of FIRMWARE_INFO that the PIN action triggers reports
+    // `at_rest: 'none'`, deliberately disagreeing with the PIN just set, so a
+    // pass demonstrates the fresh report winning rather than the session's own
+    // snapshot ("PIN set" => 'sapwood') sticking forever.
+    vi.mocked(getFirmwareVersion).mockResolvedValueOnce({ version: '0.18.0', board: 'heltec-v4', at_rest: 'none', unlock_phone_count: 0 })
+    await fireEvent.click(buttons[0])
+
+    // Without the fix, the session's own "PIN set" snapshot would win forever
+    // and this would stay "Waits for Sapwood" even once FIRMWARE_INFO
+    // disagreed; the retired override lets the fresh report show through.
+    await waitFor(() => expect(screen.getByText('Not encrypted: anyone holding it can read the keys')).toBeTruthy())
+  })
+})