@wireai/activation 0.13.6 → 0.14.1

package/src/permissions/permissionMemory.ts

@@ -15,6 +15,7 @@
  * error. A broken storage adapter must never gate or break onboarding.
  */
 import {
+  READ_TIMED_OUT,
   READ_TIMEOUT_MS,
   withTimeout,
   type WireOnboardingStorage,
@@ -47,19 +48,54 @@ export const readSettledPermissions = (
   }
 };
 
-/** Read the settled ids for `sessionId`. Never throws, never hangs past the shared read ceiling. */
-export const loadSettledPermissions = async (
+/**
+ * Did the store ANSWER, or did it not? A read that timed out or threw is `unknown` — which is NOT
+ * the same fact as "this session has settled nothing", even though both used to arrive as `[]`.
+ *
+ * The distinction is load-bearing in two directions. A caller that treats `unknown` as empty
+ * (a) re-asks a permission the OS grants exactly once, and (b) persists a set it grew from that
+ * `[]`, SHRINKING the stored record to a single id. A successful read of a corrupt, absent, or
+ * other-session entry is a genuine `[]`: the store answered, and there is nothing here for us.
+ */
+export type SettledPermissionsOutcome =
+  | { status: "read"; ids: string[] }
+  | { status: "unknown" };
+
+/**
+ * Read the settled ids for `sessionId`, reporting WHETHER the store answered. Never throws, never
+ * hangs past the shared read ceiling.
+ */
+export const loadSettledPermissionsOutcome = async (
   storage: WireOnboardingStorage,
   key: string,
   sessionId: string,
-): Promise<string[]> => {
+): Promise<SettledPermissionsOutcome> => {
   try {
-    return readSettledPermissions(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS), sessionId);
+    const raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+    if (raw === READ_TIMED_OUT) return { status: "unknown" };
+    return { status: "read", ids: readSettledPermissions(raw, sessionId) };
   } catch {
-    return [];
+    // The adapter threw or rejected: the store did not answer, so we know nothing either way.
+    return { status: "unknown" };
   }
 };
 
+/**
+ * Read the settled ids for `sessionId`, collapsing "the store did not answer" to `[]`.
+ *
+ * Kept as the module's simple reader for callers that have no way to act on the difference. The
+ * one caller that CAN — `WireOnboarding`, which would otherwise re-ask and then overwrite the
+ * stored record — uses {@link loadSettledPermissionsOutcome} instead.
+ */
+export const loadSettledPermissions = async (
+  storage: WireOnboardingStorage,
+  key: string,
+  sessionId: string,
+): Promise<string[]> => {
+  const outcome = await loadSettledPermissionsOutcome(storage, key, sessionId);
+  return outcome.status === "read" ? outcome.ids : [];
+};
+
 /** Persist the settled ids for `sessionId` - fire-and-forget, all errors swallowed. */
 export const saveSettledPermissions = (
   storage: WireOnboardingStorage,

package/src/reviews/runtime.ts

@@ -125,7 +125,7 @@ const readStr = (storage: CoachmarkStorage | null, key: string): string | undefi
 // for the same reason `currentSession` does: tsup inlines this module into several bundles and a
 // plain module-local `let` would give each bundle its own "process".
 //
-// ── WHY THE UNIT IS PINNED FOR THE WHOLE LAUNCH ──────────────────────────────────────────────
+// ── WHY THE UNIT IS PINNED, AND WHEN IT IS ALLOWED TO MOVE ───────────────────────────────────
 // The first shape of this function read the two tiers LIVE on every call: the registered session id
 // when there was one, else the process id. That let the UNIT change mid-launch, and React's own
 // ordering guarantees it does. The gates call `bumpSessionCount` from a `useState` INITIALIZER,
@@ -137,39 +137,91 @@ const readStr = (storage: CoachmarkStorage | null, key: string): string | undefi
 //   remount: gate initializer → SESSION id ≠ the stored open           → count = 2
 //
 // Two "sessions" inside one app open, which makes the fail-closed `minSessions: 2` default (added
-// after the 2026-07-16 one-star incident) satisfiable in the very launch it exists to guard. So the
-// FIRST read pins whatever it resolved into the process slot and every later read returns that,
-// regardless of what the session registry does afterwards. The client counter only has to be
-// monotone and per-launch; the server's own `min_sessions` still counts real `app.session_started`
-// events, so nothing downstream needs the two ids to be identical.
+// after the 2026-07-16 one-star incident) satisfiable in the very launch it exists to guard.
 //
-// @globalSlot LATCH — pinned by the FIRST read and stable for the whole launch. This is the one
-// slot whose latch is the fix: it samples the LIVE `currentSessionId` once, on purpose, so that
-// registry changing underneath it (render before effect, on every cold start) cannot change the
-// unit mid-launch and hand `minSessions: 2` a second "session" inside one app open. A second
-// differing write is therefore not a stale-cache bug, it IS the defect — see the block above.
+// THE FIRST FIX PINNED THE WHOLE LAUNCH — one sample, never revisited. That closed the cold start
+// and opened the opposite defect. `useLifecycleEvents` defines an app-open as a foreground after 30
+// minutes
+// in the background and fires a fresh `app.session_started` for it, but on iOS an app is SUSPENDED,
+// not killed, so ONE JS process outlives many opens. A user who opens the app daily for a week
+// produces seven server-side opens while `wire_review_<id>_sessions` stays at 1, and the local
+// `minSessions: 2` rule is unsatisfiable on a phone that is never force-quit — which is most
+// phones. It failed in the SAFE direction (a prompt that never shows, not one that shows too
+// early), but the counter's own docstring promised "once per APP-OPEN" and did not deliver it.
+//
+// THE DISTINCTION THAT RESOLVES BOTH. The two ids in the cold-start trace name the SAME open; a
+// LATER registration names a DIFFERENT one. Nothing else has to change: remember the registered id
+// that was live when the pin was taken, and read it lazily.
+//
+//   • pin unset              → pin = the registered id ?? a freshly minted one, and remember which
+//                              registered id that was (`undefined` when we had to mint).
+//   • remembered `undefined` → the FIRST registration merely NAMES the open the gate already
+//                              counted under a minted id. Adopt it, leave the PIN alone. This is
+//                              the cold-start case, and it stays shut.
+//   • live id ≠ remembered   → a genuinely new app-open. Re-pin to it; the counter bumps once.
+//
+// ⚠️ ONE ACCEPTED MISS, deliberately in the safe direction: if the mount open never registers (a
+// refused non-durable device key over a broken store) and a LATER foreground is the first
+// registration the launch ever sees, that registration is ADOPTED rather than counted, costing one
+// open on an already storage-degraded device. Under-counting is the only direction a fail-closed
+// gate may err in, so this is accepted rather than chased.
+//
+// The client counter only has to be monotone and to move once per real open; the server's own
+// `min_sessions` still counts real `app.session_started` events, so nothing downstream needs the
+// two ids to be identical.
+//
+// @globalSlot LIVE — it re-pins on a genuinely new app-open, so a reader that caches the returned
+// string across opens re-freezes the counter at 1, and the local minSessions rule stops advancing
+// forever on a suspended-not-killed app. The slot holds a PAIR rather than a bare id, because "is this a new
+// open?" is only answerable against the registered id that was live when the pin was taken.
 const PROCESS_OPEN_ID_SLOT: unique symbol = Symbol.for("@wireai/activation:processOpenId");
 
-type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };
+/** The pinned open id plus the registered session id that was live at the moment it was pinned. */
+type OpenPin = {
+  /** The id gate counting treats as THIS app-open. Never empty. */
+  openId: string;
+  /** The registered session id observed at pin time; `undefined` when `openId` was minted. */
+  observed: string | undefined;
+};
+
+type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: OpenPin };
 
 const openIdGlobal = globalThis as GlobalWithOpenId;
 
 /**
- * The id identifying THIS app-open for gate counting, PINNED on first read for the whole launch:
- * the live per-open `session_id` if one was already registered when the first gate asked, else a
- * minted per-process id. Stable from the first render to the last. Never empty.
+ * The id identifying THIS app-open for gate counting: the live per-open `session_id` once one has
+ * been registered, else a minted per-process id. Stable for the whole of an app-open and across
+ * every remount inside it, and it moves exactly once when a genuinely new open is registered.
+ * Never empty.
  */
 export const currentOpenId = (): string => {
-  const existing = openIdGlobal[PROCESS_OPEN_ID_SLOT];
-  if (existing) return existing;
-  // Adopt the registered session id when the host wired lifecycle BEFORE any gate rendered; that is
-  // the same unit the server counts. Otherwise mint one. Either way it is pinned from here on.
-  const resolved = getCurrentSessionId() ?? makeSessionId();
-  openIdGlobal[PROCESS_OPEN_ID_SLOT] = resolved;
-  return resolved;
+  const live = getCurrentSessionId();
+  const pin = openIdGlobal[PROCESS_OPEN_ID_SLOT];
+
+  // First read of the launch. Adopt the registered id when the host wired lifecycle BEFORE any gate
+  // rendered — that is the same unit the server counts — otherwise mint one and record that we did.
+  if (!pin) {
+    const openId = live ?? makeSessionId();
+    openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId, observed: live };
+    return openId;
+  }
+
+  // Nothing registered yet, or still the same registered open: the pin stands.
+  if (!live || live === pin.observed) return pin.openId;
+
+  // The first registration of the launch NAMES the open we already pinned under a minted id, so it
+  // is adopted, not counted. Re-pinning here is exactly the cold-start double-count described above.
+  if (pin.observed === undefined) {
+    openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId: pin.openId, observed: live };
+    return pin.openId;
+  }
+
+  // A second, DIFFERENT registration is a genuinely new app-open.
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = { openId: live, observed: live };
+  return live;
 };
 
-/** Test-only: forget the process open id so a unit test starts from a clean launch. */
+/** Test-only: forget the pinned open so a unit test starts from a clean launch. */
 export const resetProcessOpenId = (): void => {
   openIdGlobal[PROCESS_OPEN_ID_SLOT] = undefined;
 };

package/src/session/persistedSession.ts

@@ -52,16 +52,29 @@ export type LoadedSession = {
 };
 
 /**
- * Race a storage read against a ceiling, resolving `undefined` when the adapter did not answer.
+ * The verdict of a read that RAN OUT OF TIME. A distinct value, and deliberately never `undefined`:
+ * an `undefined` here is byte-identical to "the adapter answered, there is nothing stored", and that
+ * conflation is what let a timed-out read mint a fresh session id and WRITE IT OVER the still-valid
+ * one it had not managed to read yet. The event queue reached the same conclusion independently
+ * (`analytics/eventQueue.ts`); this is the same sentinel for the same reason.
+ *
+ * "Did not answer in time" is not "there is nothing there", and the difference is the difference
+ * between starting clean and destroying a session mid-onboarding.
+ */
+export const READ_TIMED_OUT: unique symbol = Symbol("wireai:storage-read-timeout");
+
+/**
+ * Race a storage read against a ceiling, resolving {@link READ_TIMED_OUT} when the adapter did not
+ * answer in time.
  * Exported so the permission memory reads through the same ceiling as the session seed rather than
  * carrying a second copy of it. NOT the kit's only such helper: `features/cache.ts`,
  * `session-analytics/lifecycle.ts` and `analytics/eventQueue.ts` each keep their own local timeout
  * for their own transports. Consolidating those is a separate change, not this one.
  */
-export const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+export const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | typeof READ_TIMED_OUT> => {
   let timer: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<undefined>((resolve) => {
-    timer = setTimeout(() => resolve(undefined), ms);
+  const timeout = new Promise<typeof READ_TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(READ_TIMED_OUT), ms);
   });
   // Clear the timer once the race settles, so a won read doesn't leave a ≤ms no-op
   // timer holding the closure alive.
@@ -96,12 +109,19 @@ export const loadPersistedSession = async (
   key: string,
   ttlMs: number = DEFAULT_SESSION_TTL_MS,
 ): Promise<LoadedSession> => {
-  let stored: PersistedSession | undefined;
+  let raw: string | null | typeof READ_TIMED_OUT;
   try {
-    stored = parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
+    raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
   } catch {
-    stored = undefined;
+    raw = null;
   }
+  // TIMED OUT: the mount cannot wait, so it still gets an id and starts clean — but it must NOT
+  // persist it. Writing here overwrites a session the read was still fetching, and a valid
+  // mid-onboarding session id is exactly the thing whose loss the server reads as a phantom drop.
+  // Losing persistence for ONE launch is recoverable; overwriting the blob is not.
+  if (raw === READ_TIMED_OUT) return { id: makeSessionId(), resumed: false };
+
+  const stored = parsePersisted(raw);
   if (stored && Date.now() - stored.ts < ttlMs) {
     return { id: stored.id, resumed: true };
   }
@@ -121,7 +141,11 @@ export const peekPersistedSession = async (
   key: string,
 ): Promise<{ id: string; ts: number } | undefined> => {
   try {
-    return parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
+    const raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+    // A timed-out read is `undefined` here exactly as before: this function only READS, so
+    // "unknown" and "absent" lead to the same caller behaviour and nothing destructive follows.
+    if (raw === READ_TIMED_OUT) return undefined;
+    return parsePersisted(raw);
   } catch {
     return undefined;
   }

package/src/session-analytics/lifecycle.ts

@@ -51,10 +51,18 @@ export const firstOpenStorageKey = (appId: string): string => `wireai:first_open
 /** Ceiling on the flag read — a hung adapter degrades to the in-memory latch, never a stuck gate. */
 const READ_TIMEOUT_MS = 1_500;
 
-const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+/**
+ * The verdict of a flag read that ran out of time. DISTINCT from `null`/`undefined`, because on this
+ * particular read those mean "this install has never fired its first open" — and acting on that
+ * belief is an irreversible emit. Same sentinel, same reasoning, as `session/persistedSession.ts`
+ * and `analytics/eventQueue.ts`.
+ */
+const READ_TIMED_OUT: unique symbol = Symbol("wireai:first-open-read-timeout");
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | typeof READ_TIMED_OUT> => {
   let timer: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<undefined>((resolve) => {
-    timer = setTimeout(() => resolve(undefined), ms);
+  const timeout = new Promise<typeof READ_TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(READ_TIMED_OUT), ms);
   });
   return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
 };
@@ -185,6 +193,12 @@ export const reportFirstOpen = (opts: ReportFirstOpenOptions): void => {
   void (async () => {
     try {
       const seen = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+      // TIMED OUT: the flag may well say "already fired" — the read is still in flight, it just blew
+      // the ceiling. Emitting on that guess turns once-EVER into once-per-slow-launch, and the
+      // top-of-funnel count inflates on exactly the devices (cold start, slow storage) that are
+      // slowest. Declining costs at most one launch's first_open on a genuinely first install, and
+      // the next launch retries with a read that lands. See the sentinel above.
+      if (seen === READ_TIMED_OUT) return;
       // A prior launch already fired + wrote the flag → once-ever satisfied, no-op.
       if (seen) return;
       emitFirstOpen(opts);
@@ -195,8 +209,15 @@ export const reportFirstOpen = (opts: ReportFirstOpenOptions): void => {
         // Missing/broken storage write — swallow.
       }
     } catch {
-      // Unreadable flag → the in-memory latch still caps us at one fire this process.
-      emitFirstOpen(opts);
+      // UNREADABLE (a locked / full / permission-denied adapter): the same question with a worse
+      // answer, because it fails on every launch. This used to emit, which meant `app.first_open`
+      // fired on EVERY launch of that install for as long as the adapter stayed broken — the top of
+      // the funnel counting one device as an unbounded number of installs. The kit's standing rule
+      // for an unverifiable persistence answer (0.13.0 `autoJoinKey`, 0.14.0 lifecycle device keys)
+      // is to decline rather than to emit something that corrupts the metric. Same verdict here.
+      //
+      // A host that wants a first_open on a device with no working storage should pass no `storage`
+      // at all: that is the documented degraded mode and it still fires once per process.
     }
   })();
 };

package/src/session-analytics/reportSessionStart.ts

@@ -33,6 +33,7 @@
  */
 import { setCurrentSessionId } from "../analytics/currentSession";
 import {
+  buildEventsRequest,
   makeSessionId,
   warnOnSkippedEvents,
   type ClientEvent,
@@ -158,16 +159,19 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
       return;
     }
 
-    // Fallback: this emitter's own direct POST when no sink is wired.
-    if (!target?.serverUrl) return;
-    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
-    const headers: Record<string, string> = { "Content-Type": "application/json" };
-    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    void fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ events: [event] }),
-    })
+    // Fallback: this emitter's own direct POST when no sink is wired — routed through the ONE
+    // canonical `/v1/events` builder (url + headers + body + the epoch-ms → ISO8601 `ts`
+    // conversion), exactly as `lifecycle.ts` already does with its own fallback.
+    //
+    // It used to hand-build the request here. That was harmless as long as this event carried no
+    // field needing wire conversion, but it made this the ONE send path of five that skipped the
+    // converter — on the event `min_sessions` is counted from, where the failure shape is a 200 with
+    // `{written: 0, skipped: N}` and no client-visible error at all (the 0.13.0 `ts` defect). The
+    // choke-point comment in `reportClientEvent.ts` claimed five paths and delivered four;
+    // `sendPathChokePoint.test.ts` now holds the claim to the code.
+    const req = buildEventsRequest(target, [event as unknown as ClientEvent]);
+    if (!req) return;
+    void fetch(req.url, req.init)
       .then((res) => {
         // A 200 can still carry `skipped:N` — the server took the request and threw the event away.
         // Log-only; this path has nothing to retry either way.

package/src/session-analytics/useLifecycleEvents.ts

@@ -11,9 +11,10 @@
  * Firing moments mirror {@link useSessionStart} exactly:
  *   • ON MOUNT — the app opened (cold start / provider first render). `app.first_open` fires here
  *     too (once ever, gated by the persisted flag in `reportFirstOpen`). When the kit's AUTO device
- *     key is the one in play (no host `deviceKey`, `config.storage` present) the mount fire waits on
- *     one storage read so both events carry the PERSISTED key, not a freshly minted one — see the
- *     `hydrateAutoDeviceKey` note below.
+ *     key is the one in play (no host `deviceKey`, `config.storage` present) the fire waits on one
+ *     storage read so both events carry the PERSISTED key, not a freshly minted one — and if that
+ *     read settles NON-DURABLE the key is refused outright rather than degraded to the per-launch
+ *     mint. See the `hydrateDeviceIdentity` note below.
  *   • ON FOREGROUND after a real background of at least {@link BACKGROUND_SESSION_MS} (30 min) — a
  *     new app-open, so a fresh `app.session_started` fires. A quick app-switch does NOT count.
  *
@@ -32,7 +33,7 @@ import { AppState, Platform, type AppStateStatus } from "react-native";
 
 import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
 import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
-import { hydrateAutoDeviceKey, resolveAutoDeviceKey } from "../context/deviceId";
+import { hydrateDeviceIdentity } from "../context/deviceId";
 import { resolveIdentity } from "../identity/identityRecord";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
@@ -50,8 +51,10 @@ export interface LifecycleConfig {
   appVersion?: string;
   /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
   appId?: string;
-  /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
-   *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+  /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag, the
+   *  offline durability of the hook's internal queue, AND the auto `device_key` fallback — the last
+   *  one only when the adapter actually persists (one that throws or rejects gets no fallback, the
+   *  same verdict as no storage at all). Omit it and all three degrade to in-memory. */
   storage?: WireOnboardingStorage;
 }
 
@@ -98,6 +101,10 @@ export const useLifecycleEvents = (
   const queueRef = useRef<EventQueue | undefined>(undefined);
 
   useEffect(() => {
+    // Set by the cleanup below: an in-flight storage read must not fire an app-open for a mount
+    // that is already gone. Declared first because every async fire path closes over it.
+    let cancelled = false;
+
     const resolveSink = (): ((event: ClientEvent) => void) | undefined => {
       const { config: cfg, options: opts } = latest.current;
       // Host-owned shared queue wins — one queue across the whole kit.
@@ -130,13 +137,17 @@ export const useLifecycleEvents = (
      * one. Two disjoint identity spaces again: the counter the rule reads could never increase, so
      * `min_sessions` was structurally unsatisfiable and the gate never fired from the server side.
      *
-     * ONLY WITH `storage`: the auto id is per-INSTALL only when it can be persisted. With no
-     * storage it would be per-LAUNCH, which would make every open look like a brand-new device and
-     * corrupt `min_sessions` in the other direction. So no storage → no fallback, same as before.
+     * ONLY WITH `storage` THAT ACTUALLY WORKED: the auto id is per-INSTALL only when it can be
+     * persisted. With no storage — or with an adapter that threw / rejected — it is per-LAUNCH,
+     * which makes every open look like a brand-new device and corrupts `min_sessions` in the other
+     * direction (while inflating distinct-device counts on top). So no storage → no fallback, and a
+     * non-durable read → no fallback either: `openAutoDeviceKey` below hands this function
+     * `undefined` in both cases, and it never reaches for the synchronous mint itself.
      */
     const resolveDeviceKey = (
       cfg: LifecycleConfig | undefined,
       opts: UseLifecycleEventsOptions,
+      autoDeviceKey: string | undefined,
     ): string | undefined => {
       // A HOST-supplied key is recorded on the process provenance registry, so a `<WireOnboarding>`
       // mount that was not given one can tell "this app owns no device id" from "this app owns one
@@ -148,8 +159,33 @@ export const useLifecycleEvents = (
         scope: cfg?.appId,
       })?.value;
       if (host) return host;
-      if (!cfg?.storage) return undefined;
-      return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });
+      return autoDeviceKey;
+    };
+
+    /**
+     * Resolve the auto `device_key` for ONE app-open and then fire it, so EVERY fire path (mount and
+     * foreground re-fire alike) goes through the same vetting.
+     *
+     * A host-supplied key or a config with no `storage` fires SYNCHRONOUSLY — there is nothing to
+     * read. Otherwise the fire waits on `hydrateDeviceIdentity`, the provenance-carrying read, and
+     * honours the rule `context/deviceId.ts` states for exactly these callers: *"Callers that write a
+     * key onto the wire as a cross-launch join must read `durable` and refuse a `false`."* A refusal
+     * emits the event with NO auto key — the same verdict `<WireOnboarding>` reaches on a broken
+     * adapter, and strictly better than a key that differs on every launch. Never rejects: the read
+     * resolves to a record or `undefined`, never a throw.
+     */
+    const openAutoDeviceKey = (fire: (autoDeviceKey: string | undefined) => void): void => {
+      const { config: cfg, options: opts } = latest.current;
+      const hostKey =
+        typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (hostKey || !cfg?.storage) {
+        fire(undefined);
+        return;
+      }
+      void hydrateDeviceIdentity({ appId: cfg.appId, storage: cfg.storage }).then((identity) => {
+        if (cancelled) return;
+        fire(identity?.durable ? identity.value : undefined);
+      });
     };
 
     // ONE per-open session id for the MOUNT open, shared by first_open AND session_started below.
@@ -164,7 +200,7 @@ export const useLifecycleEvents = (
     // session_start — the EXISTING emitter routed through the sink (offline-buffered, one guard).
     // Accepts the per-open id so the mount open reuses `mountOpenSessionId`; omit it and the emitter
     // mints a fresh id (a genuinely new open). Either way the once-guard dedupes within the open.
-    const fireSession = (sessionId?: string) => {
+    const fireSession = (sessionId: string | undefined, autoDeviceKey: string | undefined) => {
       const { config: cfg, options: opts } = latest.current;
       if (opts.enabled === false) return;
       if (!cfg?.serverUrl && !opts.sink) return;
@@ -176,7 +212,7 @@ export const useLifecycleEvents = (
         sink: resolveSink(),
         sessionId,
         userId: opts.userId,
-        deviceKey: resolveDeviceKey(cfg, opts),
+        deviceKey: resolveDeviceKey(cfg, opts, autoDeviceKey),
         sessionCount: opts.sessionCount,
         appVersion: cfg?.appVersion ?? device.appVersion,
         platform: Platform.OS,
@@ -189,8 +225,8 @@ export const useLifecycleEvents = (
     // `session_started` for `mountOpenSessionId` before first_open references the same id; then
     // first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen), pinned to the
     // SAME per-open id so it is never a phantom session.
-    const fireMountOpen = () => {
-      fireSession(mountOpenSessionId);
+    const fireMountOpen = (autoDeviceKey: string | undefined) => {
+      fireSession(mountOpenSessionId, autoDeviceKey);
 
       const { config: cfg, options: opts } = latest.current;
       if (opts.enabled === false) return;
@@ -204,7 +240,7 @@ export const useLifecycleEvents = (
         storage: cfg?.storage,
         appId: cfg?.appId,
         userId: opts.userId,
-        deviceKey: resolveDeviceKey(cfg, opts),
+        deviceKey: resolveDeviceKey(cfg, opts, autoDeviceKey),
         sessionCount: opts.sessionCount,
         appVersion: cfg?.appVersion ?? device.appVersion,
         platform: Platform.OS,
@@ -223,21 +259,12 @@ export const useLifecycleEvents = (
     // 1 — and `first_open`, fired once ever, ended up under a key no later event shares, which breaks
     // `first_open` → `activated` cohorting too. One storage read at mount buys both back.
     //
-    // A host-supplied `deviceKey` needs no read, and with no `storage` there is nothing to read (and
-    // `resolveDeviceKey` deliberately does not fall back), so both keep firing synchronously at mount.
-    let cancelled = false;
-    const { config: mountCfg, options: mountOpts } = latest.current;
-    const hostKey =
-      typeof mountOpts.deviceKey === "string" && mountOpts.deviceKey.trim()
-        ? mountOpts.deviceKey
-        : undefined;
-    if (!hostKey && mountCfg?.storage) {
-      void hydrateAutoDeviceKey({ appId: mountCfg.appId, storage: mountCfg.storage }).then(() => {
-        if (!cancelled) fireMountOpen();
-      });
-    } else {
-      fireMountOpen();
-    }
+    // 0.14.0: awaiting the read was only half of it. The read can settle NON-DURABLE (a locked /
+    // full / permission-denied adapter — it throws or rejects and the id stays process-scoped), and
+    // the `.then` fired regardless, so a degraded store walked the per-launch key straight back onto
+    // the counted events: two launches over a throwing MMKV produced four distinct `wdev_*`. The
+    // outcome is now read through `openAutoDeviceKey`, which refuses a `durable: false` id.
+    openAutoDeviceKey(fireMountOpen);
 
     // Foreground after a real background = a new app-open.
     let backgroundedAt: number | null = null;
@@ -249,7 +276,11 @@ export const useLifecycleEvents = (
       if (state === "active") {
         const since = backgroundedAt;
         backgroundedAt = null;
-        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) fireSession();
+        // A new open re-runs the same vetting: the auto key must still be a durable one, and a
+        // degraded read that released its latches gets a fresh attempt rather than a cached verdict.
+        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) {
+          openAutoDeviceKey((autoDeviceKey) => fireSession(undefined, autoDeviceKey));
+        }
       }
     };
     const sub = AppState.addEventListener("change", onChange);
@@ -258,6 +289,13 @@ export const useLifecycleEvents = (
       cancelled = true;
       // RN >= 0.65 returns a subscription with remove(); guard for older shims.
       if (sub && typeof (sub as { remove?: () => void }).remove === "function") sub.remove();
+      // Tear the hook's OWN queue down. This hook re-creates it on every remount against a fixed
+      // explicit storage key, so without a teardown the dead queue keeps a live backoff timer over
+      // the same slot the replacement now owns: it wakes up, drains, empties, and `removeItem`s the
+      // replacement's persisted `app.session_started`. A host-supplied `sink` is NOT touched — that
+      // queue belongs to the host and outlives this mount by design.
+      queueRef.current?.dispose();
+      queueRef.current = undefined;
     };
     // Mount-only effect: firing reads fresh values via `latest`, so no reactive deps.
     // eslint-disable-next-line react-hooks/exhaustive-deps