@wireai/activation 0.12.0 → 0.12.2

package/src/activation/wireActivation.ts

@@ -30,6 +30,7 @@ import {
 } from "../analytics/reportClientEvent";
 import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
 import { resolveUserContext, type WireUserContext } from "../context/userContext";
+import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import {
   bumpActivationRevalidation,
@@ -117,6 +118,12 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   // as it used to be. The return value is deliberately discarded — every event re-resolves.
   if (!explicitDeviceKey) resolveAutoDeviceKey(autoDeviceKeyOptions);
 
+  // The auto-detected host app version, read ONCE (cheap, sync, never throws) — same as the facade.
+  // Without it this path had NO `app_version` fallback at all, so every `wire.track` event from a host
+  // that passed no `config.appVersion` (which `wireConfigFromEnv` could not even carry) shipped
+  // without one, while the facade and lifecycle families both had theirs.
+  const detectedAppVersion = detectAppVersion();
+
   // Stamp the resolved rich context onto the event: `user_context` bucket (device_key always, plus any
   // app_version / opt-in user_email / namespaced extra) and the top-level opaque `user_id`.
   const applyContext = (event: ClientEvent): void => {
@@ -126,7 +133,7 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
         ...(config.userContext ?? {}),
         deviceKey: explicitDeviceKey ?? resolveAutoDeviceKey(autoDeviceKeyOptions),
       },
-      { autoAppVersion: config.appVersion },
+      { autoAppVersion: config.appVersion ?? detectedAppVersion },
     );
     if (resolved.userContext) {
       event.user_context = { ...resolved.userContext, ...(event.user_context ?? {}) };

package/src/analytics/analyticsFacade.ts

@@ -27,9 +27,9 @@
  * FIRE-AND-FORGET: no method throws into the UI or blocks — the queue already guarantees that.
  */
 import { buildContextEnvelope, type ContextEnvelope } from "./contextEnvelope";
-import { getCurrentSessionId } from "./currentSession";
+import { ensureCurrentSessionId } from "./currentSession";
 import { createEventQueue, type EventQueue, type EventQueueOptions } from "./eventQueue";
-import { makeSessionId, type ClientEvent } from "./reportClientEvent";
+import type { ClientEvent } from "./reportClientEvent";
 import {
   analyticsUserIdStorageKey,
   clearPiiFromContext,
@@ -70,8 +70,9 @@ export type CreateAnalyticsConfig = {
    * analytics then collapse onto a single device-scoped session — one "first open", forever.
    *
    * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
-   * falls back to a stable per-instance id only until an open has been registered. Pass one ONLY if
-   * your host runs its own session lifecycle and owns the id the server should correlate on.
+   * when no open has been registered yet it mints one AND registers it, so every later surface joins
+   * the same session instead of each inventing its own. Pass one ONLY if your host runs its own
+   * session lifecycle and owns the id the server should correlate on.
    */
   sessionId?: string;
   /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */
@@ -158,16 +159,19 @@ export const createAnalytics = (
   config: CreateAnalyticsConfig,
   options: AnalyticsOptions = {},
 ): Analytics => {
-  // A STABLE per-instance fallback id, used only when no explicit `config.sessionId` was given AND
-  // no per-open session has been registered yet (see `resolveSessionId`).
-  const instanceSessionId = config.sessionId ?? makeSessionId();
-
   // The session id every event correlates to. Precedence: an explicit `config.sessionId` freezes the
   // id (opt-out of the reuse); otherwise reuse the LIVE per-open session the server saw (via
   // `app.session_started`) so `identify`/app-events don't mint a fresh id the server back-fills into a
-  // phantom session; finally fall back to the stable per-instance id when no open is registered yet.
-  const resolveSessionId = (): string =>
-    config.sessionId ?? getCurrentSessionId() ?? instanceSessionId;
+  // phantom session.
+  //
+  // `ensureCurrentSessionId` (not the bare `getCurrentSessionId`) is what closes the facade-first
+  // ordering hole: a `track` that runs BEFORE the root lifecycle effect used to fall back to a
+  // per-instance id this facade never REGISTERED, so the server saw a session it had no
+  // `session_started` for and back-filled a phantom one. The two paths that already mint on the wire
+  // (`wire.track`, `reportAppEvent`) both register; this one only read. Registering makes the
+  // fallback id the id every LATER surface joins on, and when an open IS registered this is exactly
+  // `getCurrentSessionId()` — so nothing changes for a host that mounts lifecycle first.
+  const resolveSessionId = (): string => config.sessionId ?? ensureCurrentSessionId();
 
   // A frozen id is almost always a mistake (it silently flattens every open into ONE session), so
   // name it once at construction — same dev-only channel as the email-shape guard below.

package/src/analytics/reportClientEvent.ts

@@ -141,8 +141,14 @@ declare const __DEV__: boolean | undefined;
  *
  * LOG ONLY: returns immediately, never throws, and never influences retry / dequeue / return values.
  * A response with no usable `.json` (an old server, a test mock) is silently ignored.
+ *
+ * DEV-GATED FIRST: the `__DEV__` check is the FIRST statement, before the body is even looked at.
+ * The check used to sit inside the `.then`, so a release build parsed the JSON of every
+ * persistent-path POST to build a warning no one would ever read. Nothing here runs in production.
  */
 export const warnOnSkippedEvents = (res: unknown): void => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
   try {
     const json = (res as { json?: () => Promise<unknown> } | null | undefined)?.json;
     if (typeof json !== "function") return;
@@ -150,13 +156,11 @@ export const warnOnSkippedEvents = (res: unknown): void => {
       .then((body) => {
         const skipped = (body as { skipped?: unknown } | null | undefined)?.skipped;
         if (typeof skipped !== "number" || skipped <= 0) return;
-        if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-          console.warn(
-            `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) ` +
-              "(skipped in the response body) — they are gone, not retried. The usual cause is an " +
-              "event with a missing or empty session_id.",
-          );
-        }
+        console.warn(
+          `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) ` +
+            "(skipped in the response body) — they are gone, not retried. The usual cause is an " +
+            "event with a missing or empty session_id.",
+        );
       })
       .catch(() => {
         // Unreadable / already-consumed body — best-effort logging, swallow.

package/src/coachmarks/runtime.ts

@@ -8,35 +8,71 @@
  * the root by `CoachmarkProvider`. Singletons let a hook read the gate without
  * every call site threading the storage through props. The provider is still the
  * single writer — it calls `setCoachmarkStorage` / `setCoachmarkTesting` on mount.
+ *
+ * ── WHY A globalThis SLOT, NOT PLAIN MODULE VARIABLES ─────────────────────────────────────────
+ * These three values used to be plain module `let`s, and this module is inlined by tsup into FOUR
+ * dist bundles (`./coachmarks`, `./reviews`, `./questionnaire`, `./showcase`). Under `dist`
+ * resolution — node `import`/`require`, SSR, jest, RN-web, anything that is not Metro — a host that
+ * mounts `CoachmarkProvider` from `@wireai/activation/coachmarks` wrote the COACHMARKS copy, while
+ * `useReviewGate` from `@wireai/activation/reviews` read the REVIEWS copy, which was still `null`.
+ * Everything downstream then failed silently: `readInt(null, …)` returns 0, so `bumpSessionCount`
+ * returns 1 forever and the fail-closed `minSessions: 2` default is unsatisfiable (the gate NEVER
+ * fires); the `seen` once-gate never persists; and a tenant's coachmarks kill switch never reaches
+ * the reviews bundle. Metro masked it by collapsing every subpath back to one `src/` file through
+ * the `react-native` export condition, which is a bundler accident, not a guarantee.
+ *
+ * Same remedy this repo already applies to `currentSession`, the auto device-key registry and the
+ * activation revalidation counter: ONE record in a `globalThis` slot keyed by `Symbol.for(...)`, so
+ * every inlined copy of this module addresses the SAME state.
  */
 import type { CoachmarkStorage } from "./types";
 
-let storageSingleton: CoachmarkStorage | null = null;
-let testing = false;
-// The coachmarks feature kill switch (from GET /v1/features). Default true = fail-open: with no
-// flags fetched, coachmarks behave exactly as before. CoachmarkProvider writes it from the
-// resolved flags. Disabled → the tour never ARMS and the overlay `show()` is a no-op, so nothing
-// paints and — critically — no once-gate is written, so re-enabling replays the tour correctly.
-let coachmarksEnabled = true;
+/** Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles. */
+const COACHMARK_RUNTIME_SLOT: unique symbol = Symbol.for("@wireai/activation:coachmarkRuntime");
+
+/** The shared runtime: the provider-injected storage, the QA replay flag, and the kill switch. */
+type CoachmarkRuntime = {
+  storage: CoachmarkStorage | null;
+  testing: boolean;
+  // The coachmarks feature kill switch (from GET /v1/features). Default true = fail-open: with no
+  // flags fetched, coachmarks behave exactly as before. CoachmarkProvider writes it from the
+  // resolved flags. Disabled → the tour never ARMS and the overlay `show()` is a no-op, so nothing
+  // paints and — critically — no once-gate is written, so re-enabling replays the tour correctly.
+  coachmarksEnabled: boolean;
+};
+
+type GlobalWithCoachmarkRuntime = typeof globalThis & {
+  [COACHMARK_RUNTIME_SLOT]?: CoachmarkRuntime;
+};
+
+const runtimeGlobal = globalThis as GlobalWithCoachmarkRuntime;
+
+const coachmarkRuntime = (): CoachmarkRuntime => {
+  const existing = runtimeGlobal[COACHMARK_RUNTIME_SLOT];
+  if (existing) return existing;
+  const created: CoachmarkRuntime = { storage: null, testing: false, coachmarksEnabled: true };
+  runtimeGlobal[COACHMARK_RUNTIME_SLOT] = created;
+  return created;
+};
 
 /**
  * Set the coachmarks master switch (from the resolved feature flags). Default true (fail-open).
  * Written by CoachmarkProvider; read imperatively by the tour arm + the overlay store.
  */
 export const setCoachmarksEnabled = (value: boolean): void => {
-  coachmarksEnabled = value;
+  coachmarkRuntime().coachmarksEnabled = value;
 };
 
 /** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */
-export const areCoachmarksEnabled = (): boolean => coachmarksEnabled;
+export const areCoachmarksEnabled = (): boolean => coachmarkRuntime().coachmarksEnabled;
 
 /** Set (or clear) the injected sync gate storage. Called by CoachmarkProvider. */
 export const setCoachmarkStorage = (storage: CoachmarkStorage | null): void => {
-  storageSingleton = storage;
+  coachmarkRuntime().storage = storage;
 };
 
 /** The currently-injected gate storage, or null if no provider is mounted. */
-export const getCoachmarkStorage = (): CoachmarkStorage | null => storageSingleton;
+export const getCoachmarkStorage = (): CoachmarkStorage | null => coachmarkRuntime().storage;
 
 /**
  * Toggle the global QA replay flag. When true, EVERY seen-gate reads as unseen
@@ -44,11 +80,11 @@ export const getCoachmarkStorage = (): CoachmarkStorage | null => storageSinglet
  * mount. The app flips ONE boolean to QA the whole coachmark surface.
  */
 export const setCoachmarkTesting = (value: boolean): void => {
-  testing = value;
+  coachmarkRuntime().testing = value;
 };
 
 /** Whether replay-everything QA mode is on. */
-export const isCoachmarkTesting = (): boolean => testing;
+export const isCoachmarkTesting = (): boolean => coachmarkRuntime().testing;
 
 /** Gate key for a tour: `wire_coachmark_<tourId>_seen`. */
 export const coachmarkGateKey = (tourId: string): string =>
@@ -73,8 +109,8 @@ export const hasSeenGate = (
   storageOverride?: CoachmarkStorage | null,
   testingOverride?: boolean,
 ): boolean => {
-  if (testingOverride ?? testing) return false;
-  const storage = storageOverride ?? storageSingleton;
+  if (testingOverride ?? isCoachmarkTesting()) return false;
+  const storage = storageOverride ?? getCoachmarkStorage();
   if (!storage) return false;
   try {
     return storage.getItem(key) === SEEN_VALUE;
@@ -92,8 +128,8 @@ export const markSeenGate = (
   storageOverride?: CoachmarkStorage | null,
   testingOverride?: boolean,
 ): void => {
-  if (testingOverride ?? testing) return;
-  const storage = storageOverride ?? storageSingleton;
+  if (testingOverride ?? isCoachmarkTesting()) return;
+  const storage = storageOverride ?? getCoachmarkStorage();
   if (!storage) return;
   try {
     storage.setItem(key, SEEN_VALUE);

package/src/config/wireConfigFromEnv.ts

@@ -12,12 +12,31 @@
  *   return <WireOnboarding config={config} ... />;
  *
  * `appId` defaults to `EXPO_PUBLIC_WIREAI_APP_ID` (or "default"); pass overrides to
- * set `appId`/`metadata` or to substitute the key/URL programmatically.
+ * set `appId`/`metadata` or to substitute the key/URL programmatically. `appVersion`
+ * defaults to `detectAppVersion()` so every surface built from this config carries it.
  */
+import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingConfig } from "../types";
 
 export type WireConfigOverrides = Partial<WireOnboardingConfig>;
 
+/** The env vars this helper reads. Exported so a host preflight can assert them itself. */
+export const WIRE_ENV_VARS = [
+  "EXPO_PUBLIC_WIREAI_API_KEY",
+  "EXPO_PUBLIC_WIREAI_SERVER_URL",
+  "EXPO_PUBLIC_WIREAI_APP_ID",
+] as const;
+
+/** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
+declare const __DEV__: boolean | undefined;
+
+/** Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests. */
+const warnInDev = (message: string): void => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+  }
+};
+
 /**
  * Minimal `process.env` declaration so the kit stays RN-pure (no `@types/node`).
  * In RN/Expo, `process.env.EXPO_PUBLIC_*` is provided/inlined by Metro at build
@@ -41,12 +60,37 @@ export const wireConfigFromEnv = (
     overrides?.appId ?? process.env.EXPO_PUBLIC_WIREAI_APP_ID ?? "default";
 
   // Missing transport → null, so the host gates on one falsy check.
-  if (!apiKey || !serverUrl) return null;
+  //
+  // The `null` return is the CORRECT contract and hosts rely on it — but it is also the quietest
+  // failure the kit has: a missing EAS env var makes this return null, and then the facade never
+  // constructs, `useLifecycleEvents` no-ops on `!cfg?.serverUrl`, and every gate returns null. Wire
+  // is 100% off, with no error anywhere. Name it once in dev, and name WHICH var is missing.
+  if (!apiKey || !serverUrl) {
+    const missing = [
+      apiKey ? undefined : "EXPO_PUBLIC_WIREAI_API_KEY",
+      serverUrl ? undefined : "EXPO_PUBLIC_WIREAI_SERVER_URL",
+    ].filter(Boolean);
+    warnInDev(
+      `[wireai] wireConfigFromEnv() returned null: ${missing.join(" and ")} ${
+        missing.length > 1 ? "are" : "is"
+      } missing. The kit is now FULLY DISABLED (no onboarding, no analytics, no gates) and nothing ` +
+        "else will report an error. Set the var(s) in your env / EAS secrets.",
+    );
+    return null;
+  }
+
+  // `appVersion` is part of `WireOnboardingConfig`, but this helper could not carry it — so a host
+  // that built its config here forwarded `config.appVersion === undefined` to every surface. The
+  // facade and the lifecycle path each auto-detect their own fallback; `createWireActivation` does
+  // not, so every `wire.track` event shipped with no `app_version` at all. Detect once here (an
+  // explicit override still wins) and the whole config carries it.
+  const appVersion = overrides?.appVersion ?? detectAppVersion();
 
   return {
     apiKey,
     serverUrl,
     appId,
+    ...(appVersion ? { appVersion } : {}),
     ...(overrides?.metadata ? { metadata: overrides.metadata } : {}),
   };
 };

package/src/context/deviceId.ts

@@ -59,15 +59,23 @@ export const mintDeviceId = (): string => {
 // (tsup duplicates modules across the `.` / `./analytics` bundles) addresses the SAME registry.
 // Keyed by `appId` so two tenants in one process never share an id.
 //
-// RESIDUAL WINDOW (documented, not fixed here): the storage read is async, so events emitted in the
-// milliseconds before hydration completes still carry the freshly minted id rather than the persisted
-// one. The registry makes every surface agree on WHICH id that is; it does not make the read sync.
+// RESIDUAL WINDOW: the storage read is async, so an event emitted in the milliseconds before
+// hydration completes carries the freshly minted id rather than the persisted one. The registry makes
+// every surface agree on WHICH id that is; it does not make the read sync. A caller that can afford to
+// wait (the lifecycle hook's mount effect — see `hydrateAutoDeviceKey`) should await instead: its two
+// events are the ONLY ones the server counts `min_sessions` from, so a per-launch id there is not a
+// millisecond of noise, it is a counter that can never exceed 1.
 
 /** Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle. */
 const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoDeviceKeys");
 
-/** The shared registry: the live id per `appId`, plus the set of appIds whose hydration already ran. */
-type AutoDeviceKeyRegistry = { keys: Map<string, string>; hydrating: Set<string> };
+/** The shared registry: the live id per `appId`, the set of appIds whose hydration already started,
+ *  and the in-flight (or settled) hydration promise per `appId` so a waiter can join it. */
+type AutoDeviceKeyRegistry = {
+  keys: Map<string, string>;
+  hydrating: Set<string>;
+  pending?: Map<string, Promise<string>>;
+};
 
 type GlobalWithDeviceKeys = typeof globalThis & {
   [AUTO_DEVICE_KEY_SLOT]?: AutoDeviceKeyRegistry;
@@ -99,6 +107,44 @@ export interface ResolveAutoDeviceKeyOptions {
   storage?: DeviceKeyStorage;
 }
 
+/**
+ * Start (or join) the SINGLE-FLIGHT storage read for `appId` and resolve to the id it settles on.
+ * The promise is parked on the registry so a later `hydrateAutoDeviceKey` awaits the SAME read
+ * instead of starting a second one. Never rejects: any storage failure resolves to the live id.
+ */
+const startHydration = (
+  registry: AutoDeviceKeyRegistry,
+  appId: string,
+  storage: DeviceKeyStorage,
+  minted: string,
+): Promise<string> => {
+  if (!registry.pending) registry.pending = new Map();
+  const existing = registry.pending.get(appId);
+  if (existing) return existing;
+
+  const slot = deviceIdStorageKey(appId);
+  const settled = (): string => registry.keys.get(appId) ?? minted;
+  let run: Promise<string>;
+  try {
+    run = Promise.resolve(storage.getItem(slot))
+      .then((saved) => {
+        const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
+        if (persisted) {
+          registry.keys.set(appId, persisted);
+          return persisted;
+        }
+        // First run on this install: persist the id we just minted so the next launch adopts it.
+        return Promise.resolve(storage.setItem(slot, minted)).then(settled, settled);
+      })
+      .catch(settled);
+  } catch {
+    // A storage adapter that throws synchronously — degrade to the in-memory id.
+    run = Promise.resolve(settled());
+  }
+  registry.pending.set(appId, run);
+  return run;
+};
+
 /**
  * The ONE auto-minted `device_key` for an install, shared by every kit surface.
  *
@@ -126,27 +172,45 @@ export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): st
   // read whatever the registry currently holds.
   if (storage && !registry.hydrating.has(appId)) {
     registry.hydrating.add(appId);
-    const slot = deviceIdStorageKey(appId);
-    const minted = id;
-    try {
-      void Promise.resolve(storage.getItem(slot))
-        .then((saved) => {
-          const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
-          if (persisted) registry.keys.set(appId, persisted);
-          else void Promise.resolve(storage.setItem(slot, minted)).catch(() => {});
-        })
-        .catch(() => {});
-    } catch {
-      // A storage adapter that throws synchronously — degrade to the in-memory id.
-    }
+    void startHydration(registry, appId, storage, id);
   }
 
   return registry.keys.get(appId) ?? id;
 };
 
+/**
+ * The AWAITABLE sibling of {@link resolveAutoDeviceKey}: resolve to the auto `device_key` AFTER the
+ * persisted id has been read back (or written, on a first run), so the caller stamps the id this
+ * install will keep rather than the one that was minted a millisecond ago.
+ *
+ * WHY IT EXISTS: `resolveAutoDeviceKey` is synchronous by contract, so a caller firing at mount got
+ * the freshly minted id and the persisted one landed milliseconds later. For most events that is
+ * noise. For `app.session_started` it is the whole metric: the server computes `min_sessions` by
+ * counting distinct opens grouped by `device_key`, so a per-launch key there makes the counter
+ * structurally incapable of exceeding 1, and it splits `first_open` off from every event that
+ * follows it. Only a caller that can afford one storage read should use this; the fire-and-forget
+ * event paths must stay on the sync function.
+ *
+ * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
+ * with no `storage` it resolves immediately (there is nothing to hydrate from).
+ */
+export const hydrateAutoDeviceKey = async (
+  opts: ResolveAutoDeviceKeyOptions = {},
+): Promise<string> => {
+  // Mint + register synchronously first, so a waiter and a concurrent sync caller share ONE id.
+  const id = resolveAutoDeviceKey(opts);
+  if (!opts.storage) return id;
+  const registry = autoDeviceKeyRegistry();
+  const appId = opts.appId ?? "default";
+  const pending = registry.pending?.get(appId);
+  if (pending) await pending;
+  return registry.keys.get(appId) ?? id;
+};
+
 /** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
 export const resetAutoDeviceKeys = (): void => {
   const registry = autoDeviceKeyRegistry();
   registry.keys.clear();
   registry.hydrating.clear();
+  registry.pending?.clear();
 };

package/src/index.ts

@@ -109,7 +109,12 @@ export type {
 } from "./features";
 
 // ─── Config + env helpers ─────────────────────────────────────────────────────
-export { wireConfigFromEnv } from "./config/wireConfigFromEnv";
+export {
+  wireConfigFromEnv,
+  // The three `EXPO_PUBLIC_WIREAI_*` names, so a host preflight can assert its own env instead of
+  // discovering a missing var as a silently disabled kit (`wireConfigFromEnv` returns null).
+  WIRE_ENV_VARS,
+} from "./config/wireConfigFromEnv";
 export type { WireConfigOverrides } from "./config/wireConfigFromEnv";
 export { isOnboardingEnabled } from "./config/onboardingFlag";
 export type { OnboardingFlagOptions } from "./config/onboardingFlag";
@@ -174,6 +179,9 @@ export {
   // purchase events carried `wdev_*` while its onboarding session carried no `device_key` at all, and
   // the join returned the silent zero the README warns about.
   resolveAutoDeviceKey,
+  // The awaitable sibling: resolves AFTER the persisted id has been read back, for a caller that can
+  // afford one storage read and must not stamp a key minted a millisecond ago (the lifecycle mount).
+  hydrateAutoDeviceKey,
   resetAutoDeviceKeys,
 } from "./context/deviceId";
 export type { DeviceKeyStorage, ResolveAutoDeviceKeyOptions } from "./context/deviceId";

package/src/questionnaire/runtime.ts

@@ -11,6 +11,7 @@ export {
   writeInt,
   bumpSessionCount,
   currentOpenId,
+  warnMissingGateStorage,
 } from "../reviews/runtime";
 
 /** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */

package/src/questionnaire/useQuestionnaireGate.ts

@@ -27,6 +27,7 @@ import {
   questionnaireSessionsKey,
   readInt,
   resolveStorage,
+  warnMissingGateStorage,
   writeInt,
 } from "./runtime";
 import type {
@@ -78,9 +79,13 @@ export const useQuestionnaireGate = ({
   // Read (and bump) the app-open counter. IDEMPOTENT per app-open, NOT per mount — see the same note
   // in `useReviewGate`; `bumpSessionCount` keys off the live per-open session id, so a remount or a
   // StrictMode double-invoke of this initializer reads the same number back instead of inflating it.
-  const sessions = useState(() =>
-    bumpSessionCount(resolveStorage(storage), sessionsKey, sessionOpenKey),
-  )[0];
+  const sessions = useState(() => {
+    const store = resolveStorage(storage);
+    // Same as `useReviewGate`: no storage means the counter never leaves 1, so the fail-closed
+    // minSessions rule is unsatisfiable and the gate silently never fires. Dev-only, once per process.
+    warnMissingGateStorage(store, "questionnaire");
+    return bumpSessionCount(store, sessionsKey, sessionOpenKey);
+  })[0];
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server gets a
   // window to answer first. A present `decision` bypasses the wait entirely.

package/src/reviews/runtime.ts

@@ -27,6 +27,48 @@ export const resolveStorage = (
   override?: CoachmarkStorage | null,
 ): CoachmarkStorage | null => override ?? getCoachmarkStorage();
 
+/** RN sets this global; absent under node/SSR. Read defensively via {@link warnMissingGateStorage}. */
+declare const __DEV__: boolean | undefined;
+
+/** Once-per-process latch on its own `Symbol.for` slot: a plain `let` would warn once per inlined
+ *  bundle copy, and the gates live in three of them. */
+const NO_STORAGE_WARNED_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:gateStorageWarned",
+);
+
+type GlobalWithGateWarn = typeof globalThis & { [NO_STORAGE_WARNED_SLOT]?: boolean };
+
+const gateWarnGlobal = globalThis as GlobalWithGateWarn;
+
+/**
+ * Warn once, in dev builds only, when a gate has NO sync storage to count with.
+ *
+ * With no storage `readInt` returns 0, so `bumpSessionCount` answers `1` on every call forever and
+ * the fail-closed `minSessions: 2` default can never be met: the gate is pinned shut for the life of
+ * the app and nothing anywhere says so. The fix is one line at the app root (mount `CoachmarkProvider`
+ * with a sync storage, or pass `storage` to the gate), so name it.
+ */
+export const warnMissingGateStorage = (
+  storage: CoachmarkStorage | null,
+  gate: "review" | "questionnaire",
+): void => {
+  if (storage) return;
+  if (gateWarnGlobal[NO_STORAGE_WARNED_SLOT]) return;
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
+  gateWarnGlobal[NO_STORAGE_WARNED_SLOT] = true;
+  console.warn(
+    `[wireai] the ${gate} gate has no sync storage, so its app-open counter is stuck at 1 and the ` +
+      "fail-closed minSessions rule can never be satisfied — the gate will never fire. Mount " +
+      "CoachmarkProvider with a sync storage adapter at your app root, or pass `storage` to the gate.",
+  );
+};
+
+/** Test-only: forget the once-per-process no-storage warn latch. */
+export const resetGateStorageWarning = (): void => {
+  gateWarnGlobal[NO_STORAGE_WARNED_SLOT] = undefined;
+};
+
 /** Read an integer from sync storage (0 on a missing/unparseable/throwing read). */
 export const readInt = (storage: CoachmarkStorage | null, key: string): number => {
   if (!storage) return 0;
@@ -78,6 +120,24 @@ const readStr = (storage: CoachmarkStorage | null, key: string): string | undefi
 // closer to a session than a mount is. It lives in a `globalThis` slot keyed by `Symbol.for(...)`
 // 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 ──────────────────────────────────────────────
+// 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,
+// which runs during render; `useLifecycleEvents` registers the session id from a root EFFECT; and
+// React runs every render before any effect. So a cold start went:
+//
+//   render:  gate initializer → no session registered yet → PROCESS id  → count = 1, open = <process>
+//   effect:  root lifecycle   → setCurrentSessionId(<session id>)
+//   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.
 const PROCESS_OPEN_ID_SLOT: unique symbol = Symbol.for("@wireai/activation:processOpenId");
 
 type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };
@@ -85,17 +145,18 @@ type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };
 const openIdGlobal = globalThis as GlobalWithOpenId;
 
 /**
- * The id identifying THIS app-open for gate counting: the live per-open `session_id` when a host
- * wired the lifecycle events, else a stable per-process id. Never empty.
+ * 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.
  */
 export const currentOpenId = (): string => {
-  const live = getCurrentSessionId();
-  if (live) return live;
   const existing = openIdGlobal[PROCESS_OPEN_ID_SLOT];
   if (existing) return existing;
-  const created = makeSessionId();
-  openIdGlobal[PROCESS_OPEN_ID_SLOT] = created;
-  return created;
+  // 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;
 };
 
 /** Test-only: forget the process open id so a unit test starts from a clean launch. */

package/src/reviews/useReviewGate.ts

@@ -26,6 +26,7 @@ import {
   reviewSeenKey,
   reviewSessionOpenKey,
   reviewSessionsKey,
+  warnMissingGateStorage,
   writeInt,
 } from "./runtime";
 import type {
@@ -80,9 +81,13 @@ export const useReviewGate = ({
   // initializer all read the same number back instead of inflating it. Before this, `sessions`
   // counted mounts, so the fail-closed `minSessions: 2` default could be satisfied inside the user's
   // very first app open — the exact scenario it was added to prevent.
-  const sessions = useState(() =>
-    bumpSessionCount(resolveStorage(storage), sessionsKey, sessionOpenKey),
-  )[0];
+  const sessions = useState(() => {
+    const store = resolveStorage(storage);
+    // No storage pins the counter at 1 forever, so the fail-closed minSessions rule can never be
+    // met and the gate silently never fires. Dev-only, once per process.
+    warnMissingGateStorage(store, "review");
+    return bumpSessionCount(store, sessionsKey, sessionOpenKey);
+  })[0];
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server
   // gets a window to answer first. A present `decision` bypasses the wait entirely.