@wireai/activation 0.15.0 → 0.16.0

package/src/features/WireFeaturesProvider.tsx

@@ -15,7 +15,7 @@
 import React, { createContext, useContext, useMemo } from "react";
 
 import { defaultWireFeatures } from "./defaults";
-import { useWireFeatures } from "./useWireFeatures";
+import { useWireFeaturesState, type WireFeaturesState } from "./useWireFeatures";
 import type { WireFeatures, WireFeaturesConfig } from "./types";
 
 /**
@@ -26,16 +26,49 @@ import type { WireFeatures, WireFeaturesConfig } from "./types";
  * the all-on defaults with no crash and no warning. Because it is a latch, and only because of
  * that, the module-local `const WireFeaturesContext` below may cache it.
  */
-const CONTEXT_SYMBOL = Symbol.for("wireai.features.context");
+const CONTEXT_SYMBOL: unique symbol = Symbol.for("wireai.features.context");
 // `globalThis`, not `global`: the other nine `Symbol.for` slots in this kit all use it, and `global`
 // simply does not exist in a plain browser (RN-web / SSR-in-the-browser), where this line would
 // throw a ReferenceError before the provider could render anything.
-const globalObj = globalThis as any;
+//
+// The slot is TYPED rather than cast through `any` (which is banned, `ai_rules/rules/core.md`). The
+// cast was not cosmetic: with `any` on both sides, BOTH contexts below were inferred `any`, so every
+// `<X.Provider value={...}>` in this file and every `useContext` read of them was type-unchecked —
+// a provider publishing the wrong shape into either one would have compiled. Declaring each key
+// `unique symbol` is what lets it appear as a property key in a type at all.
+type GlobalWithFeaturesContext = typeof globalThis & {
+  [CONTEXT_SYMBOL]?: React.Context<WireFeatures | null>;
+};
+const featuresContextGlobal = globalThis as GlobalWithFeaturesContext;
 
-if (!globalObj[CONTEXT_SYMBOL]) {
-  globalObj[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);
+if (!featuresContextGlobal[CONTEXT_SYMBOL]) {
+  featuresContextGlobal[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);
 }
-const WireFeaturesContext = globalObj[CONTEXT_SYMBOL];
+const WireFeaturesContext = featuresContextGlobal[CONTEXT_SYMBOL];
+
+/**
+ * @globalSlot LATCH — the SECOND context, carrying only "has the provider's fetch answered yet?".
+ *
+ * WHY A SECOND CONTEXT AND NOT A WIDER VALUE: the value published above is a `WireFeatures`, and
+ * tsup inlines a copy of this module per subpath bundle. Changing the published SHAPE would mean a
+ * provider from one copy publishing an object a consumer from another copy reads as flags —
+ * silently wrong flags rather than a crash. An extra context is additive: a consumer that reads it
+ * without a provider (or under an OLDER copy's provider that publishes nothing here) gets the
+ * default below.
+ *
+ * THE DEFAULT IS `true`, AND FAIL-OPEN DEPENDS ON IT: "settled" gates a surface's first render, so
+ * defaulting to `false` would let a missing provider suppress a gate forever. `true` means "nothing
+ * above is going to answer this for you", which is the truth when there is no provider at all.
+ */
+const SETTLED_SYMBOL: unique symbol = Symbol.for("wireai.features.settled.context");
+type GlobalWithSettledContext = typeof globalThis & {
+  [SETTLED_SYMBOL]?: React.Context<boolean>;
+};
+const settledContextGlobal = globalThis as GlobalWithSettledContext;
+if (!settledContextGlobal[SETTLED_SYMBOL]) {
+  settledContextGlobal[SETTLED_SYMBOL] = createContext<boolean>(true);
+}
+const WireFeaturesSettledContext = settledContextGlobal[SETTLED_SYMBOL];
 
 export interface WireFeaturesProviderProps {
   /** Tenant creds (+ optional storage) to fetch the flags once for the whole tree. */
@@ -59,10 +92,16 @@ export const WireFeaturesProvider: React.FC<WireFeaturesProviderProps> = ({
 }) => {
   // Always call the hook (rules of hooks); when `flags` is supplied we pass no config so it
   // never fetches and the explicit flags win below.
-  const fetched = useWireFeatures(flags ? undefined : config);
-  const value = flags ?? fetched;
+  const fetched = useWireFeaturesState(flags ? undefined : config);
+  const value = flags ?? fetched.flags;
+  // Explicit `flags` are an answer by definition; otherwise the fetch decides.
+  const settled = flags ? true : fetched.settled;
   const stable = useMemo(() => value, [value]);
-  return <WireFeaturesContext.Provider value={stable}>{children}</WireFeaturesContext.Provider>;
+  return (
+    <WireFeaturesSettledContext.Provider value={settled}>
+      <WireFeaturesContext.Provider value={stable}>{children}</WireFeaturesContext.Provider>
+    </WireFeaturesSettledContext.Provider>
+  );
 };
 
 WireFeaturesProvider.displayName = "WireFeaturesProvider";
@@ -87,11 +126,32 @@ export interface ResolveFeaturesOptions {
  *   4. the all-on defaults.
  * Always fail-open, always a stable reference for a given value (so it's safe in effect deps).
  */
-export const useResolvedFeatures = (options?: ResolveFeaturesOptions): WireFeatures => {
+export const useResolvedFeatures = (options?: ResolveFeaturesOptions): WireFeatures =>
+  useResolvedFeaturesState(options).flags;
+
+/**
+ * The same resolution, plus whether the value is an ANSWER or still the optimistic default —
+ * `useResolvedFeatures` is the flags-only wrapper over this.
+ *
+ * A gated surface whose first render is irreversible (the review gate fires `review_prompt_shown`
+ * and can take a review row the moment it appears) must hold that first render until `settled`,
+ * or a tenant that turned the module OFF still gets one impression per launch while the fetch is
+ * in flight — the kill switch working everywhere except the one moment it is read.
+ *
+ * `settled` follows the same precedence as the flags: explicit `flags` are an answer; under a
+ * provider it is the PROVIDER's fetch that has to answer; otherwise it is this surface's own lazy
+ * fetch, which is already `true` when there is nothing to fetch. Deliberately INTERNAL (not in the
+ * root barrel): it exists for the kit's own gated surfaces, and the public flags-only contract is
+ * unchanged.
+ */
+export const useResolvedFeaturesState = (options?: ResolveFeaturesOptions): WireFeaturesState => {
   const ctx = useWireFeaturesContext();
+  const ctxSettled: boolean = useContext(WireFeaturesSettledContext);
   // Only lazily fetch when nothing else provides the flags — otherwise pass no config so the
   // hook stays inert (defaults, no network). The hook is always called (rules of hooks).
   const shouldFetch = !options?.flags && ctx == null;
-  const fetched = useWireFeatures(shouldFetch ? options?.config : undefined);
-  return options?.flags ?? ctx ?? fetched ?? defaultWireFeatures;
+  const fetched = useWireFeaturesState(shouldFetch ? options?.config : undefined);
+  const flags = options?.flags ?? ctx ?? fetched.flags ?? defaultWireFeatures;
+  const settled = options?.flags ? true : ctx != null ? ctxSettled : fetched.settled;
+  return useMemo(() => ({ flags, settled }), [flags, settled]);
 };

package/src/features/fetchWireFeatures.ts

@@ -30,23 +30,62 @@ const failOpen = async (
   return cached?.features ?? defaultWireFeatures;
 };
 
-/** GET with a hard timeout via AbortController (falls back to no-abort where unsupported). */
-const fetchWithTimeout = async (
+/** "The exchange produced nothing usable" — a non-2xx, or a deadline the body never met. Both mean
+ *  the caller must fail OPEN, and neither is distinguishable to it. A symbol so it can never
+ *  collide with a JSON body the server actually sent. */
+const NO_ANSWER: unique symbol = Symbol("wire-features-no-answer");
+
+/**
+ * GET **and read the body** under ONE deadline. Never pends longer than `timeoutMs`.
+ *
+ * ── THE DEFECT THIS CLOSES ─────────────────────────────────────────────────────────────────────
+ * The timer used to be cleared in a `finally` around the `fetch` alone, so it died the moment the
+ * HEADERS landed and `await res.json()` ran with NO ceiling at all. A 200 whose body then stalls —
+ * a half-open connection, a proxy that flushes headers and hangs, a captive portal — left this
+ * function pending forever. `settled` never flips, so `useReviewGate` and `useQuestionnaireGate`
+ * never become ready and BOTH gates stay dark for the life of the process, silently. That INVERTS
+ * this module's own stated contract at the top of the file: fail-open, never fail-dark.
+ *
+ * SCOPE, honestly: on native RN `fetch` is the XHR polyfill and the body is already buffered by the
+ * time the promise resolves, so this was effectively unreachable there. On RN-Web / Expo web — which
+ * the kit explicitly supports (`WireFeaturesProvider`) — it is real.
+ *
+ * TWO mechanisms, deliberately, because they fail differently. The abort tears the socket DOWN
+ * (a stalled stream is not just un-awaited, it is cancelled); the race guarantees this promise
+ * SETTLES even on a runtime that ignores `signal` once the body has started. A ceiling that depends
+ * on the host honouring abort is not a ceiling on a surface whose whole contract is "never dark".
+ */
+const fetchFeaturesJson = async (
   url: string,
   apiKey: string,
   timeoutMs: number,
-): Promise<Response> => {
+): Promise<unknown> => {
   const controller =
     typeof AbortController !== "undefined" ? new AbortController() : undefined;
-  const timer = setTimeout(() => controller?.abort(), timeoutMs);
-  try {
-    return await fetch(url, {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<typeof NO_ANSWER>((resolve) => {
+    timer = setTimeout(() => {
+      controller?.abort();
+      resolve(NO_ANSWER);
+    }, timeoutMs);
+  });
+  const exchange = (async (): Promise<unknown> => {
+    const res = await fetch(url, {
       method: "GET",
       headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
       signal: controller?.signal,
     });
+    // 401 (bad/rotated key), 5xx, any non-2xx → last-known, never dark.
+    if (!res || !res.ok) return NO_ANSWER;
+    return (await res.json()) as unknown; // throws on malformed body → caught by the caller
+  })();
+  try {
+    return await Promise.race([exchange, expired]);
   } finally {
     clearTimeout(timer);
+    // The loser can still settle after the race is decided and nothing is awaiting it. An
+    // unobserved rejection is a hard crash on some hosts, so it gets a handler either way.
+    void exchange.catch(() => {});
   }
 };
 
@@ -72,15 +111,14 @@ export const fetchWireFeatures = async (
   const timeoutMs = config.timeoutMs && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
 
   try {
-    const res = await fetchWithTimeout(url, config.apiKey, timeoutMs);
-    // 401 (bad/rotated key), 5xx, any non-2xx → last-known, never dark.
-    if (!res || !res.ok) return failOpen(storage, key);
-    const json: unknown = await res.json(); // throws on malformed body → caught below
+    const json: unknown = await fetchFeaturesJson(url, config.apiKey, timeoutMs);
+    // A non-2xx, or a headers-then-stall body that never met the deadline → last-known, never dark.
+    if (json === NO_ANSWER) return failOpen(storage, key);
     const features = parseWireFeatures(json);
     if (storage) writeCachedFeatures(storage, key, features);
     return features;
   } catch {
-    // Timeout/abort, network error, missing fetch, or malformed JSON — all fail open.
+    // Abort, network error, missing fetch, or malformed JSON — all fail open.
     return failOpen(storage, key);
   }
 };

package/src/features/useWireFeatures.ts

@@ -5,13 +5,21 @@
  * network resolves. When no `serverUrl`+`apiKey` is supplied it never fetches and just returns
  * defaults, so a host that never adopts flags sees ZERO behavior change and ZERO network calls.
  *
+ * ⚠️ THE OPTIMISTIC DEFAULT IS A GUESS, AND SOME CONSUMERS CANNOT ACT ON A GUESS. Fail-open is the
+ * right resting state, but "all on because we have not asked yet" and "all on because the tenant
+ * says so" are different answers and the returned flags cannot tell them apart. A surface whose
+ * first render is IRREVERSIBLE — the review gate posts a `review_prompt_shown` and can take a row
+ * the moment it appears — needs the difference, or a tenant with `review.enabled: false` still gets
+ * one impression on every launch before the answer lands. {@link useWireFeaturesState} exposes it as
+ * `settled`; `useWireFeatures` is the flags-only wrapper and is unchanged.
+ *
  * frequent_rules #11 (unstable inline props): the config is idiomatically passed inline
  * (`config={{ serverUrl, apiKey }}`), a fresh identity every render. We stabilize the fetch key
  * by VALUE so the effect fires once per real credential change, and we only swap the returned
  * flags object when its VALUES change — so a host that lists the returned flags in an effect dep
  * array settles in a bounded number of commits instead of looping (enforced by the canary suite).
  */
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 
 import { defaultWireFeatures, featuresEqual } from "./defaults";
 import { fetchWireFeatures } from "./fetchWireFeatures";
@@ -28,16 +36,35 @@ const useStableValue = <T,>(value: T, isEqual: (a: T, b: T) => boolean): T => {
 const sameFetchKey = (a: WireFeaturesConfig | undefined, b: WireFeaturesConfig | undefined): boolean =>
   a?.serverUrl === b?.serverUrl && a?.apiKey === b?.apiKey && a?.appId === b?.appId;
 
-export const useWireFeatures = (config?: WireFeaturesConfig): WireFeatures => {
+/**
+ * The flags PLUS whether they are an answer yet — the shape `useWireFeatures` returns half of.
+ *
+ * `settled: false` means "nobody has answered; these are the optimistic defaults". It becomes
+ * `true` the moment the fetch resolves (fail-open included: an unreachable control plane resolves
+ * to the defaults and that IS a settled answer, because it is the answer we are keeping), and it
+ * starts `true` whenever there is nothing to wait for — no creds, so no flag can ever arrive.
+ */
+export interface WireFeaturesState {
+  flags: WireFeatures;
+  /** `false` only while a fetch that could still change the answer is in flight. */
+  settled: boolean;
+}
+
+export const useWireFeaturesState = (config?: WireFeaturesConfig): WireFeaturesState => {
   const stableConfig = useStableValue(config, sameFetchKey);
   const [flags, setFlags] = useState<WireFeatures>(defaultWireFeatures);
 
   const canFetch = !!stableConfig?.serverUrl && !!stableConfig?.apiKey;
+  // Nothing to fetch → the defaults are already the final answer, so a consumer that waits for an
+  // answer must not wait forever. Only ever moves to `true`: a later credential change refreshes a
+  // KNOWN answer, and un-answering it would re-hide a surface the user is already looking at.
+  const [settled, setSettled] = useState<boolean>(!canFetch);
 
   useEffect(() => {
     if (!canFetch) {
       // No creds → stay on the all-on defaults (and reset if creds were removed).
       setFlags((prev) => (featuresEqual(prev, defaultWireFeatures) ? prev : defaultWireFeatures));
+      setSettled(true);
       return;
     }
     let alive = true;
@@ -47,11 +74,20 @@ export const useWireFeatures = (config?: WireFeaturesConfig): WireFeatures => {
       // Only adopt a NEW reference on a real value change, so a host effect keyed on the
       // returned flags doesn't loop (frequent_rules #11).
       setFlags((prev) => (featuresEqual(prev, next) ? prev : next));
+      // Settled on EVERY resolution, including the fail-open one: `fetchWireFeatures` swallows a
+      // timeout / 401 / 5xx into the defaults, and that fallback is the final answer, not a
+      // pending one. This is what keeps fail-open intact — a broken control plane resolves fast
+      // and permissive, it does not leave a gated surface waiting.
+      setSettled(true);
     });
     return () => {
       alive = false;
     };
   }, [canFetch, stableConfig]);
 
-  return flags;
+  return useMemo(() => ({ flags, settled }), [flags, settled]);
 };
+
+/** The flags alone — the original hook, unchanged for every consumer that cannot act on `settled`. */
+export const useWireFeatures = (config?: WireFeaturesConfig): WireFeatures =>
+  useWireFeaturesState(config).flags;

package/src/identity/identityRecord.ts

@@ -96,6 +96,20 @@ const provenanceRegistry = (): ProvenanceRegistry => {
 const provenanceKey = (space: IdentitySpace, scope?: string): string =>
   `${space}:${scope ?? "default"}`;
 
+/**
+ * Is this candidate a usable identity value? A string with at least one non-whitespace character.
+ *
+ * ⛔ PURE, and that is the whole point of it existing separately from {@link resolveIdentity}: it is
+ * the predicate a READ-ONLY caller needs. `resolveIdentity` cannot serve that caller, because for a
+ * `host`-sourced input it WRITES to the process provenance registry — so merely asking it "is this a
+ * usable key?" would enrol the asker in the census it was only trying to read. That is the exact
+ * defect 0.15.1 fixed (a propless reader minting into `registry.keys` made the census read two, and
+ * the reader answered `undefined` forever), so the predicate is shared rather than re-typed:
+ * `resolveIdentity` below is its only other caller, so the two can never drift.
+ */
+export const isUsableIdentityValue = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
 /**
  * Build an {@link IdentityRecord} from a candidate value, or `undefined` when there is nothing usable
  * (a non-string, or blank after trimming) — so a caller can `if (record)`-gate instead of guessing
@@ -107,9 +121,8 @@ const provenanceKey = (space: IdentitySpace, scope?: string): string =>
  * key" from a silent third id space into a warnable condition. Never throws.
  */
 export const resolveIdentity = (input: ResolveIdentityInput): IdentityRecord | undefined => {
-  if (typeof input.value !== "string") return undefined;
+  if (!isUsableIdentityValue(input.value)) return undefined;
   const value = input.value.trim();
-  if (!value) return undefined;
   const durable = input.durable ?? input.source === "host";
   if (input.source === "host") {
     provenanceRegistry().host.set(provenanceKey(input.space, input.scope), value);

package/src/questionnaire/QuestionnaireGate.tsx

@@ -236,6 +236,31 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
   const postedRef = useRef(false);
   /** The last submission fired with no answer yet. Non-null after an UNSENT post = still owed. */
   const unackedRef = useRef<QuestionnaireSubmission | null>(null);
+  /**
+   * THE NET WAS INERT WHILE THE POST WAS IN FLIGHT, which is precisely when it is needed.
+   *
+   * This is the review-gate defect on its second copy: 0.15.1 closed it in `reviews/ReviewGate.tsx`
+   * and left the twin here open. The latch is taken OPTIMISTICALLY and only released in the `.then`
+   * below, while `finish` auto-closes the modal 1500ms after the post. So on any network slower than
+   * that — the offline answerer, a stalled radio, a captive portal — the unmount ran with the latch
+   * still CLOSED: `recoverRef`'s only branch requires `!postedRef.current`, so it no-opped, and the
+   * post later resolved `"unsent"` with nothing mounted to notice. The host's `onResolved` →
+   * `markResolved` has ALREADY written the permanent `wire_questionnaire_<id>_<ver>_seen` key, so
+   * that user is never asked again and their answers are gone. Silent. The existing canary missed it
+   * because every case awaits the submit BEFORE unmounting — the fast path, where the latch has
+   * already reopened.
+   *
+   * So the unmount hands the recovery to the promise: when it finds a post STILL IN FLIGHT — the one
+   * state its branch cannot serve — it arms `recoverOnSettleRef`, and the `.then` below does the
+   * re-post if nothing reached the server. It is armed ONLY in that state, so the fast path is
+   * untouched and still recovers exactly once, in the net. `recoveredRef` bounds this to exactly ONE
+   * extra post — the same in-process ceiling the net always had, never a retry loop.
+   */
+  const recoverOnSettleRef = useRef(false);
+  const recoveredRef = useRef(false);
+  /** Latest `postOnce`, so the recovery above can call it from inside its own promise chain
+   *  (the same ref convention `recoverRef` below uses) without a self-referencing callback. */
+  const postOnceRef = useRef<(body: QuestionnaireSubmission) => void>(() => {});
   const postOnce = useCallback(
     (body: QuestionnaireSubmission) => {
       if (postedRef.current) return;
@@ -245,6 +270,12 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
         if (result === "unsent") {
           // Nothing reached the server → un-latch, so these answers can still go out.
           postedRef.current = false;
+          // The gate is already gone: the unmount net ran while this post was still in flight and
+          // found the latch closed, so nothing else will ever recover this row. Do it here, once.
+          if (recoverOnSettleRef.current && !recoveredRef.current) {
+            recoveredRef.current = true;
+            postOnceRef.current(body);
+          }
           return;
         }
         // `accepted` OR `rejected`: the server answered, so it owns this row. Never re-post it.
@@ -253,6 +284,7 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
     },
     [target, id],
   );
+  postOnceRef.current = postOnce;
 
   /**
    * The recovery point for a submission the server never ANSWERED — never for one it answered
@@ -268,7 +300,14 @@ const _QuestionnaireGate: React.FC<QuestionnaireGateProps> = ({
   const recoverRef = useRef<() => void>(() => {});
   recoverRef.current = () => {
     const undelivered = unackedRef.current;
-    if (undelivered && !postedRef.current) postOnce(undelivered);
+    if (undelivered && !postedRef.current) {
+      postOnce(undelivered);
+      return;
+    }
+    // STILL IN FLIGHT (latch closed, row unanswered) — the state that made this net inert. The
+    // branch above cannot act from here, so the pending post is asked to recover itself when it
+    // settles unsent. Nothing else is scheduled to look at this row again.
+    if (postedRef.current && undelivered) recoverOnSettleRef.current = true;
   };
   React.useEffect(() => () => recoverRef.current(), []);
 

package/src/questionnaire/transport.ts

@@ -10,6 +10,7 @@
  * non-2xx (incl. 404), a missing `fetch`, or bad JSON all resolve to null, so a host wiring
  * pure server-directed firing simply shows nothing - exactly the reviews decision seam.
  */
+import { DEADLINE_EXPIRED, withDeadline } from "../utils/withDeadline";
 import type { SubmitResult } from "../utils/submitResult";
 import type {
   QuestionnaireDecisionResponse,
@@ -63,11 +64,19 @@ export const submitQuestionnaireResponse = async (
     const url = `${base}/v1/questionnaires/${encodeURIComponent(id)}/responses`;
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(submission),
-    });
+    // Under a deadline (see `utils/withDeadline`): a hung POST used to hold `QuestionnaireGate`'s
+    // `postOnce` latch closed for the ~60s platform default, which is exactly the window the
+    // unmount recovery net cannot re-post inside.
+    const res = await withDeadline((signal) =>
+      fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(submission),
+        signal,
+      }),
+    );
+    // A deadline that expired is not a rejection: nothing reached the server, so it stays re-postable.
+    if (res === DEADLINE_EXPIRED) return "unsent";
     // No response object at all is not an answer — treat it as nothing having reached the server
     // rather than as a rejection, or a stubbed-out `fetch` would silently latch the answers away.
     if (!res) return "unsent";
@@ -107,9 +116,14 @@ export const fetchQuestionnaireDecision = async (
     const url = `${base}/v1/questionnaires/decision${qs ? `?${qs}` : ""}`;
     const headers: Record<string, string> = {};
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    const res = await fetch(url, { headers });
-    if (!res || !res.ok) return null;
-    const json = (await res.json()) as QuestionnaireDecisionResponse | null;
+    // The BODY read is inside the deadline too: a ceiling cleared when the headers land is not a
+    // ceiling (the `fetchWireFeatures` lesson — see `utils/withDeadline`).
+    const json = await withDeadline(async (signal): Promise<QuestionnaireDecisionResponse | null> => {
+      const res = await fetch(url, { headers, signal });
+      if (!res || !res.ok) return null;
+      return (await res.json()) as QuestionnaireDecisionResponse | null;
+    });
+    if (json === DEADLINE_EXPIRED) return null;
     // A body without a boolean `fire` is not a decision. Guard it explicitly (mirrors
     // `fetchReviewDecision`) rather than letting `{}` through as a truthy object a gate would treat
     // as a verdict (`{}.fire === undefined` is falsy, so it would silently read as "never fire").

package/src/questionnaire/useQuestionnaireGate.ts

@@ -13,10 +13,11 @@
  * the popup. The global `isTestingCoachmark` flag force-shows the gate for QA replay, and the
  * `questionnaire` master switch (a disabled tenant) wins over everything.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 
+import { getCurrentSessionId, subscribeCurrentSessionId } from "../analytics/currentSession";
 import { hasSeenGate, isCoachmarkTesting, markSeenGate } from "../coachmarks/runtime";
-import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { useResolvedFeaturesState } from "../features/WireFeaturesProvider";
 import { sameDecision, shallowEqual } from "../reviews/equality";
 import { decideQuestionnaire, evaluateGate, resolveRules } from "./decision";
 import {
@@ -64,8 +65,20 @@ export const useQuestionnaireGate = ({
 
   // The questionnaire MASTER switch. Disabled → the gate never fires, composing as an extra
   // AND over the local rules + the server decision seam below (fail-open: defaults to enabled).
-  const featureEnabled = useResolvedFeatures({ flags: features, config: featuresConfig })
-    .questionnaire.enabled;
+  //
+  // `settled` is read too, and it is the half that makes the switch real — the same asymmetry
+  // `useReviewGate` closed, on the same seam. The flags start on the all-on defaults and swap only
+  // when the fetch resolves, so `featureEnabled` is `true` on the FIRST render of every mount,
+  // including a tenant with `questionnaire.enabled: false`. With no `timeoutFallbackMs` the local
+  // wait is skipped as well (`elapsed` starts `true`), so the gate could become visible, fire
+  // `questionnaire_prompt_shown`, and POST a response from a user the tenant had switched off. The
+  // comment below ("must never see it") was falsified by its own async default. Holding the FIRST
+  // impression until an answer exists is what honours the switch.
+  const { flags: resolvedFeatures, settled: featuresSettled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig,
+  });
+  const featureEnabled = resolvedFeatures.questionnaire.enabled;
 
   const testing = isTesting ?? isCoachmarkTesting();
   const seenKey = questionnaireSeenKey(
@@ -76,16 +89,48 @@ export const useQuestionnaireGate = ({
   const sessionsKey = questionnaireSessionsKey(config.id);
   const sessionOpenKey = questionnaireSessionOpenKey(config.id);
 
+  // ── FOLLOW real app-opens, do not sample one ────────────────────────────────────────────────
+  //
+  // `bumpSessionCount` is IDEMPOTENT per app-open and moves once per open — but it used to be reached
+  // ONLY from the `useState` initializer below, which runs once per component INSTANCE. On a screen
+  // that never unmounts (a home feed, a tab that stays alive) that meant once per PROCESS, and iOS
+  // suspends rather than kills: `useLifecycleEvents` fires a fresh `app.session_started` on every
+  // foreground past its threshold and the SERVER's `min_sessions` advances, while `wire_questionnaire_<id>_sessions`
+  // stayed at its launch value and the LOCAL `minSessions` rule was unsatisfiable for the life of the
+  // app. Silent, and in the safe direction (a prompt that never shows), which is why it survived —
+  // `sessionCountAcrossOpens.test.ts` proved the FUNCTION advances and could not see that the HOOK
+  // never asked it again.
+  //
+  // So subscribe to the registry that knows. A notification naming the same open is a no-op by
+  // construction (`bumpSessionCount` reads its stored count back), so the cold-start ordering this
+  // pin exists for is untouched.
+  const openSessionId = useSyncExternalStore(
+    subscribeCurrentSessionId,
+    getCurrentSessionId,
+    getCurrentSessionId,
+  );
+  // Read through a ref: a host that passes `storage={{ … }}` inline (idiomatic React, and what
+  // `frequent_rules` #11 requires this hook to tolerate) mints a fresh identity every render, and
+  // listing it in the deps below would re-run the effect on every one of them.
+  const storageRef = useRef(storage);
+  storageRef.current = storage;
+
   // 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(() => {
+  const [sessions, setSessions] = 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];
+  });
+  useEffect(() => {
+    const next = bumpSessionCount(resolveStorage(storageRef.current), sessionsKey, sessionOpenKey);
+    // A bail-out when the count is unchanged, so a notification for an open already counted costs
+    // nothing: React skips the re-render when the state is identical.
+    setSessions((prev) => (prev === next ? prev : next));
+  }, [openSessionId, sessionsKey, sessionOpenKey]);
 
   // 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.
@@ -129,11 +174,17 @@ export const useQuestionnaireGate = ({
     const resolved = decideQuestionnaire(local, decision);
     // (3) the once-gate always wins locally, even over a server "fire".
     const alreadySeen = hasSeenGate(seenKey, storage, isTesting);
-    const ready = hasServerDecision || elapsed;
+    // FAIL-OPEN IS NOT WEAKENED BY THIS. `featuresSettled` is `false` only while a fetch that could
+    // still change the answer is in flight; it is `true` with no `featuresConfig` (nothing to ask),
+    // with explicit `features`, and — the case that matters — the moment a FAILED fetch resolves,
+    // because `fetchWireFeatures` swallows a timeout / 401 / 5xx into the all-on defaults. So an
+    // unreachable control plane still allows the gate; only an unanswered one holds it.
+    const ready = (hasServerDecision || elapsed) && featuresSettled;
     return { visible: ready && resolved.fire && !alreadySeen, verdict: resolved };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     featureEnabled,
+    featuresSettled,
     testing,
     config,
     decision,

package/src/reviews/ReviewGate.tsx

@@ -214,6 +214,31 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
   const postedRef = React.useRef(false);
   /** The last submission fired with no answer yet. Non-null after an UNSENT post = still owed. */
   const unackedRef = React.useRef<ReviewSubmission | null>(null);
+  /**
+   * THE NET WAS INERT WHILE THE POST WAS IN FLIGHT, which is precisely when it is needed.
+   *
+   * The latch is taken OPTIMISTICALLY and only released in `submitReview`'s `.then`, while the gate
+   * auto-closes 1500ms after the post (`resolveWithDelay`). So on any network slower than that —
+   * the offline detractor, a stalled radio, a captive portal — the unmount ran with the latch still
+   * CLOSED: the recovery branch below requires `!postedRef.current`, and the abandonment branch
+   * returns on `postedRef.current`, so BOTH no-opped and a 1-4 rating plus its mandatory text was
+   * dropped in silence. The once-gate means that user is never asked again. The existing canary
+   * missed it because it awaits the submit BEFORE unmounting — the fast path, where the latch has
+   * already reopened.
+   *
+   * So the unmount hands the recovery to the promise: when it finds a post STILL IN FLIGHT — the
+   * one state neither of its branches can serve — it arms `recoverOnSettleRef`, and the `.then`
+   * below does the re-post if nothing reached the server. It is armed ONLY in that state, so the
+   * fast path (settled before unmount) is untouched and still recovers exactly once, in the net.
+   * `recoveredRef` bounds this to exactly ONE extra post — the same in-process ceiling the net
+   * always had, never a retry loop — and the re-post carries this impression's `idempotency_key`
+   * plus its unit, so a row that did land is upserted rather than duplicated.
+   */
+  const recoverOnSettleRef = React.useRef(false);
+  const recoveredRef = React.useRef(false);
+  /** Latest `postOnce`, so the recovery above can call it from inside its own promise chain
+   *  (the same ref convention `abandonRef` below uses) without a self-referencing callback. */
+  const postOnceRef = React.useRef<(body: ReviewSubmission) => void>(() => {});
   const postOnce = useCallback(
     (body: ReviewSubmission) => {
       if (postedRef.current) return;
@@ -223,6 +248,12 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
         if (result === "unsent") {
           // Nothing reached the server → un-latch, so this row can still go out.
           postedRef.current = false;
+          // The gate is already gone: the unmount net ran while this post was still in flight and
+          // found the latch closed, so nothing else will ever recover this row. Do it here, once.
+          if (recoverOnSettleRef.current && !recoveredRef.current) {
+            recoveredRef.current = true;
+            postOnceRef.current(body);
+          }
           return;
         }
         // `accepted` OR `rejected`: the server answered, so it owns this row. Not re-posted here —
@@ -233,6 +264,7 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     },
     [target],
   );
+  postOnceRef.current = postOnce;
 
   /**
    * The abandonment safety net, and the reason forcing feedback does not COST us detractor data.
@@ -257,6 +289,13 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
       postOnce(undelivered);
       return;
     }
+    // STILL IN FLIGHT (latch closed, row unanswered) — the state that made this net inert. Neither
+    // branch can act from here, so the pending post is asked to recover itself when it settles
+    // unsent. Nothing else is scheduled to look at this row again.
+    if (postedRef.current && undelivered) {
+      recoverOnSettleRef.current = true;
+      return;
+    }
     if (postedRef.current || stars < 1) return;
     postOnce(
       buildBody({