@wireai/activation 0.14.0 → 0.14.2

package/metro/index.js

@@ -71,7 +71,7 @@ const SINGLE_INSTANCE_DEPS = ['react', 'react-native', 'wireai-rn', 'zod'];
  * only thing holding it up.
  *
  * ONLY modules read through a guarded require/import belong here. A module the kit imports
- * STATICALLY at module scope (react-native-reanimated, expo-blur,
+ * STATICALLY at module scope (react-native-reanimated,
  * @blazejkustra/react-native-onboarding) must NOT be stubbed: an empty module would turn a loud
  * build-time "Unable to resolve module" into a silent `undefined` component that crashes at
  * render, which is strictly worse. `test/canary/metroResolution.test.tsx` keeps this list in sync
@@ -89,6 +89,8 @@ const OPTIONAL_MODULES = [
   'expo-store-review',
   // src/haptics/haptics.ts — haptic feedback; absent → silent no-op.
   'expo-haptics',
+  // src/coachmarks/expoBlur.ts — the coachmark spotlight frost; absent → plain dimmed scrim.
+  'expo-blur',
 ];
 
 function withWireOnboarding(config, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",

package/src/WireOnboarding.tsx

@@ -36,7 +36,7 @@ import {
 } from "./session/persistedSession";
 import {
   clearSettledPermissions,
-  loadSettledPermissions,
+  loadSettledPermissionsOutcome,
   permissionStorageKey,
   saveSettledPermissions,
 } from "./permissions/permissionMemory";
@@ -384,18 +384,57 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // a late arrival cannot recreate the A2A adapter. The flow simply suppresses permission screens
   // while `permissionsPending` is true, and that window closes long before the first card arrives
   // (one timeout-capped storage read against a backend round trip).
+  //
+  // ── AN UNREADABLE RECORD IS NOT AN EMPTY ONE (ruled 2026-08-18: skip, never re-ask) ──────────
+  //
+  // A read that timed out or threw used to arrive here as `[]`, i.e. "this session has settled
+  // nothing", and that guess is wrong in the expensive direction TWICE. The flow re-asks a
+  // permission the OS grants exactly once, AND the first answer then persists a set grown from
+  // that `[]`, overwriting a stored record that may have held several ids with a single one. A
+  // slow adapter could therefore permanently shrink the memory it exists to keep.
+  //
+  // So `unknown` is now its own outcome and it means: leave the memory UNRESOLVED. Because
+  // `permissionsPending` below is exactly `settledPermissions === undefined`, an unresolved memory
+  // suppresses every permission screen for this mount — which is the ruling, and it also closes
+  // the write path for free (no screen renders → nothing settles → `saveSettledPermissions` is
+  // never called → the stored record is left exactly as it was).
+  //
+  // The cost is stated rather than hidden: on a host whose adapter never answers, configured
+  // permission screens silently never show. That is the failure `placement.ts` calls out as the
+  // one a host cannot see, so it warns in dev naming the adapter.
   const wantsPermissionMemory = Boolean(storage) && (permissionScreens?.length ?? 0) > 0;
   const [settledPermissions, setSettledPermissions] = useState<string[] | undefined>(undefined);
+  // LATCHED: without it, a hung or throwing adapter is re-read on every single render — an
+  // unbounded read loop against the storage that is already failing.
+  const [permissionMemoryUnreadable, setPermissionMemoryUnreadable] = useState(false);
   useEffect(() => {
-    if (!wantsPermissionMemory || !storage || !sessionId || settledPermissions !== undefined) return;
+    if (!wantsPermissionMemory || !storage || !sessionId) return;
+    if (settledPermissions !== undefined || permissionMemoryUnreadable) return;
     let cancelled = false;
-    void loadSettledPermissions(storage, permissionsKey, sessionId).then((ids) => {
-      if (!cancelled) setSettledPermissions(ids);
+    void loadSettledPermissionsOutcome(storage, permissionsKey, sessionId).then((outcome) => {
+      if (cancelled) return;
+      if (outcome.status === "read") {
+        setSettledPermissions(outcome.ids);
+        return;
+      }
+      setPermissionMemoryUnreadable(true);
+      warnInDev(
+        "[wireai] the permission-screen memory could not be read (the storage adapter timed out " +
+          "or threw), so permission screens are suppressed for this session rather than re-asking " +
+          "a permission the OS grants once. Check the `storage` adapter passed to WireOnboarding.",
+      );
     });
     return () => {
       cancelled = true;
     };
-  }, [wantsPermissionMemory, storage, permissionsKey, sessionId, settledPermissions]);
+  }, [
+    wantsPermissionMemory,
+    storage,
+    permissionsKey,
+    sessionId,
+    settledPermissions,
+    permissionMemoryUnreadable,
+  ]);
 
   // Persist the settled set as it grows. Fire-and-forget: a failed write only costs a re-ask on a
   // resume, never a broken flow. Without `storage` there is nothing to write to and the

package/src/analytics/currentSession.ts

@@ -63,8 +63,9 @@ import { warnInDev } from "../utils/warnInDev";
  * @globalSlot LIVE — every app-open overwrites this with that open's id, so a reader that captures
  * it into a module-local (or a `const` taken once at mount) posts the PREVIOUS open's session to a
  * server that has already moved on. Read it at the moment of use, through `getCurrentSessionId()` /
- * `ensureCurrentSessionId()`. `reviews/runtime`'s `currentOpenId()` deliberately pins one sample of
- * it for the launch; that is a documented latch DERIVED from this slot, not a cache of it.
+ * `ensureCurrentSessionId()`. `reviews/runtime`'s `currentOpenId()` derives its own pinned value
+ * from this slot: it holds one sample for the duration of an app-open and re-pins when a genuinely
+ * NEW open is registered here, so it follows this slot deliberately and late, never eagerly.
  */
 const CURRENT_SESSION_ID_SLOT: unique symbol = Symbol.for(
   "@wireai/activation:currentSessionId",

package/src/coachmarks/SpotlightOverlay.tsx

@@ -1,4 +1,3 @@
-import { BlurView } from "expo-blur";
 import React, { useEffect, useMemo } from "react";
 import {
   Pressable,
@@ -20,11 +19,10 @@ import Animated, {
 } from "react-native-reanimated";
 
 import { useOnboardingTheme } from "../theme/ThemeContext";
+import { resolveBlurView } from "./expoBlur";
 import { GestureHint } from "./GestureHint";
 import type { GestureKind, Placement, TargetRect } from "./types";
 
-const AnimatedBlurView = Animated.createAnimatedComponent(BlurView);
-
 const BLUR_INTENSITY = 26;
 const FADE_MS = 280;
 /** Breathing room between the highlighted element and the glowing ring. */
@@ -51,13 +49,20 @@ export interface SpotlightOverlayProps {
 }
 
 /**
- * A single coachmark step: the whole screen is frosted with an animated blur,
- * and a bright pulsing ring + tooltip point at one measured target. Mounted at
- * the app root (above the tab bar) via CoachmarkOverlayHost.
+ * A single coachmark step: the whole screen is frosted with an animated blur
+ * (or a plain dimmed scrim when the optional `expo-blur` peer is absent), and a
+ * bright pulsing ring + tooltip point at one measured target. Mounted at the app
+ * root (above the tab bar) via CoachmarkOverlayHost.
  *
  * Performance: one BlurView (mounted only while a step is visible), the ring
  * glow is a single reanimated view, and all animation runs on the UI thread.
  * Reduce Motion drops the pulse.
+ *
+ * `expo-blur` is OPTIONAL. It is resolved through a guarded lazy require (see
+ * `expoBlur.ts`) and the animated component is built once on first use, so the
+ * subpath never carries a static top-level import of the peer. When it is not
+ * installed the frost drops to an equivalent dimmed scrim — a decorative frost
+ * missing must never blank a tour, so the ring, copy and gestures are unchanged.
  */
 const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
   message,
@@ -76,6 +81,14 @@ const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
   const accent = accentColor ?? theme.colors.primary;
   const accentText = accentTextColor ?? theme.colors.onPrimary;
 
+  // Resolve the optional `expo-blur` peer and build its animated component ONCE, on first render,
+  // instead of at module scope — so merely importing this file (and thus the coachmarks subpath)
+  // never needs the peer. `null` = the peer is absent → the scrim path renders instead.
+  const AnimatedBlurView = useMemo(() => {
+    const BlurView = resolveBlurView();
+    return BlurView ? Animated.createAnimatedComponent(BlurView) : null;
+  }, []);
+
   // Tap / double-tap steps show ONLY the ring + tooltip — no gesture glyph. The
   // pulsing highlight ring already reads as "tap here", so an extra glyph is
   // noise. Every app inherits this centrally, with no config change.
@@ -138,11 +151,20 @@ const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
       entering={FadeIn.duration(FADE_MS)}
       exiting={FadeOut.duration(FADE_MS)}
     >
-      <AnimatedBlurView
-        tint="dark"
-        animatedProps={blurAnimatedProps}
-        style={StyleSheet.absoluteFill}
-      />
+      {AnimatedBlurView ? (
+        <AnimatedBlurView
+          tint="dark"
+          animatedProps={blurAnimatedProps}
+          style={StyleSheet.absoluteFill}
+        />
+      ) : (
+        // `expo-blur` absent → a plain dimmed scrim stands in for the frost. Same dark backdrop
+        // the tour reads against, so the ring, tooltip and gestures behave identically.
+        <Animated.View
+          style={[StyleSheet.absoluteFill, styles.scrim]}
+          pointerEvents="none"
+        />
+      )}
 
       {/* Tap-the-backdrop to move on (dismisses the tour on the last step). */}
       <Pressable
@@ -210,6 +232,11 @@ const styles = StyleSheet.create({
     zIndex: 9999,
     elevation: 9999,
   },
+  // Fallback backdrop when `expo-blur` is absent. A structural dim (not a brand token), tuned to
+  // read like the dark blur at BLUR_INTENSITY so the ring + tooltip keep the same contrast.
+  scrim: {
+    backgroundColor: "rgba(0, 0, 0, 0.55)",
+  },
   ring: {
     position: "absolute",
     borderWidth: 2.5,

package/src/coachmarks/expoBlur.ts

@@ -0,0 +1,135 @@
+/**
+ * expoBlur — resolve `expo-blur`'s `BlurView`, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * `expo-blur` is an OPTIONAL peer of the coachmarks subpath. The spotlight overlay frosts the
+ * screen with it WHEN it is installed, and degrades to a plain dimmed scrim when it is not — the
+ * ring, tooltip and gestures behave identically either way (see SpotlightOverlay). So a host that
+ * never installs `expo-blur` can still run the guided tour, and the free tier that must load under
+ * Expo Go is not forced into a native module it cannot take.
+ *
+ * Before this file, `SpotlightOverlay` did `import { BlurView } from "expo-blur"` at module scope,
+ * and `coachmarks/index.ts` re-exports the overlay with no wildcard escape — so importing ANYTHING
+ * from `@wireai/activation/coachmarks`, even `setCoachmarkStorage`, dragged the peer in and a host
+ * without it hit a Metro resolution failure. This resolver removes that static edge.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL, INSIDE A TRY/CATCH ───────────────────────────
+ *
+ * This follows `icons/expoIcons.ts` exactly, and its header carries the full autopsy. In short:
+ *
+ *   • Metro collects dependencies STATICALLY, matching a call whose callee is literally the
+ *     identifier `require` and whose argument is a STRING LITERAL. A variable specifier
+ *     (`const req = require; req(name)`) is collected NOWHERE, so the module never enters the
+ *     bundle — and the aliased `require` is Metro's own numeric-id-keyed `metroRequire`, which can
+ *     never resolve a package-name string. That shape shipped broken once; do not restore it.
+ *   • The call sitting inside a TRY/CATCH is literally how Metro marks the dependency `isOptional`:
+ *     when the peer is absent Metro puts `null` in the dependencyMap and the require throws "Cannot
+ *     find module" straight into the catch below. Do NOT "simplify" the try/catch away — it is what
+ *     keeps the peer optional, not just tidy. (`withWireOnboarding` in metro/index.js adds a
+ *     stub-to-empty-module safety net for hosts that disable Metro's `allowOptionalDependencies`.)
+ */
+import type { ComponentType } from "react";
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime (the kit's own
+// tests run under `node --test` as ESM). Declared locally so this type-checks without ambient
+// Node types; the `typeof` guard keeps the reference ESM-safe.
+declare const require: ((id: string) => unknown) | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded literal require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/** The minimal prop shape the overlay uses from `expo-blur`'s `BlurView`. */
+export type BlurViewComponent = ComponentType<{
+  intensity?: number;
+  tint?: "light" | "dark" | "default";
+  style?: unknown;
+  children?: unknown;
+}>;
+
+/**
+ * The production resolver. The specifier is a LITERAL so Metro collects it (see the header); the
+ * `moduleName` parameter exists only to keep the `OptionalRequire` seam shape, so anything other
+ * than the one module this file owns resolves to undefined.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (moduleName !== "expo-blur") return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("expo-blur");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * TEST-ONLY seam. `SpotlightOverlay`'s public props are frozen, so it cannot take a `requireModule`
+ * the way `WireIcon` does — this lets a component render exercise the PRESENT path without the
+ * native peer installed. Production never sets it; `runtimeRequire` is the only resolver.
+ */
+let testRequire: OptionalRequire | undefined;
+export const __setBlurRequireForTests = (fn: OptionalRequire | undefined): void => {
+  testRequire = fn;
+  cached = undefined;
+};
+
+/** Read a module's `default` (Expo modules are consumed as default exports) or the namespace. */
+const interop = (mod: unknown): Record<string, unknown> | undefined => {
+  if (!mod || typeof mod !== "object") return undefined;
+  const ns = mod as Record<string, unknown>;
+  // `expo-blur` exposes `BlurView` as a NAMED export; prefer the namespace when it already carries
+  // it, and only fall back to `default` for a CJS-interop wrapper.
+  if (ns.BlurView) return ns;
+  const def = (mod as { default?: unknown }).default;
+  if (def && typeof def === "object") return def as Record<string, unknown>;
+  return ns;
+};
+
+/**
+ * Narrow an unknown export to something mountable. `BlurView` is a real React component (function
+ * or class across versions), and React.memo / forwardRef wrappers are objects carrying `$$typeof`.
+ * Reject anything else rather than handing the reconciler a non-component.
+ */
+const asComponent = (value: unknown): BlurViewComponent | undefined => {
+  if (typeof value === "function") return value as BlurViewComponent;
+  if (value && typeof value === "object" && "$$typeof" in (value as object)) {
+    return value as BlurViewComponent;
+  }
+  return undefined;
+};
+
+/**
+ * Module-level memo. `null` = "we looked and it is not there" (distinct from "not looked yet"),
+ * so an absent peer costs exactly one failed require per process, not one per overlay mount.
+ */
+let cached: BlurViewComponent | null | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetBlurModuleCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve the `BlurView` component, or undefined when the peer is absent/unresolvable.
+ * Never throws: an absent blur must degrade to a plain scrim, never break the tour.
+ *
+ * `requireModule` is injectable so tests can exercise BOTH the found and absent paths without
+ * installing the native peer (same convention as `resolveIconFamily` / `detectAppVersion`).
+ */
+export const resolveBlurView = (
+  requireModule: OptionalRequire = testRequire ?? runtimeRequire,
+): BlurViewComponent | undefined => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const resolved = interop(requireModule("expo-blur"));
+      const component = resolved ? asComponent(resolved.BlurView) : undefined;
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = component ?? null;
+      return component;
+    }
+    if (cached === null) return undefined;
+    return cached;
+  } catch {
+    return undefined;
+  }
+};

package/src/permissions/permissionMemory.ts

@@ -48,29 +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 {
     const raw = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
-    // A timed-out read degrades to "nothing settled yet", the same answer as before this sentinel
-    // existed (the symbol used to fall through `readSettledPermissions`'s JSON.parse and be caught).
-    // Stated explicitly rather than left to an accident.
-    //
-    // ⚠️ KNOWN, NOT FIXED HERE: the CALLER (`WireOnboarding`) then persists the set it grows from
-    // this `[]`, so a timed-out read can shrink the stored set to one id. It is the same class as
-    // the two sites above, but the fix is a UX ruling, not a mechanical one — on an unknown set,
-    // does a resumed flow re-ask a permission or skip it? Reported, deliberately not guessed at.
-    if (raw === READ_TIMED_OUT) return [];
-    return readSettledPermissions(raw, sessionId);
+    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;
 };