@wireai/activation 0.15.0 → 0.16.0

package/src/analytics/wireDoctor.ts

@@ -8,13 +8,18 @@
  * numeric `ts` did exactly that through 0.13.0. This turns that class of loss from something you
  * discover in a funnel report weeks later into something the first run tells you.
  *
- * SHAPE: four independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
+ * SHAPE: five independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
  * without the others. The report is data, never a thrown error and never a side effect on the host:
  *
  *   1. `target`      : is there a server URL and a key, and do they look like a key and a URL?
  *   2. `reachability`: is the server actually there? (`GET /v1/events/contract`, public and cheap)
  *   3. `storage`      : can the offline queue persist? (a write / read / delete probe)
  *   4. `round_trip`   : does a REAL event survive REAL server validation? (a `dry_run` POST)
+ *   5. `join_key`     : will those events be JOINABLE? (read-only; needs `join`)
+ *
+ * Checks 1-4 all answer "does an event leave and get accepted". NONE of them answers "can it be
+ * joined", and an integration with no `user_context.device_key` writes every event, passes every
+ * one of those four, and still reports a permanent ZERO in the activated funnel. That is check 5.
  *
  * NEVER THROWS, under any input, any network condition, or any hostile response object. A doctor
  * that can crash the screen it is diagnosing is worse than no doctor.
@@ -34,6 +39,9 @@
  *   const report = await wireDoctor({
  *     target: { serverUrl: "https://api.example.com", apiKey: DRIVELINE_KEY },
  *     storage: AsyncStorage,
+ *     // The same values you hand <WireOnboarding>. Omit `join` and the join_key check FAILS,
+ *     // because a report that never looked at the join cannot honestly read green.
+ *     join: { appId: WIRE_APP_ID, userContext },
  *   });
  *   console.log(report.ok, report.checks);
  */
@@ -49,6 +57,12 @@ import {
   type ClientEventTarget,
 } from "./reportClientEvent";
 import type { WireOnboardingStorage } from "../session/persistedSession";
+// The SAME key builder the analytics side persists the auto id under, and the SAME predicate
+// `resolveIdentity` gates on — imported rather than re-typed, so the doctor can never drift into
+// answering about a key the kit does not actually use. `isUsableIdentityValue` is the PURE half:
+// calling `resolveIdentity` here would write this reader into the provenance census (see below).
+import { deviceIdStorageKey } from "../context/deviceId";
+import { isUsableIdentityValue } from "../identity/identityRecord";
 
 /** RN sets this global; absent under node/SSR. Read defensively, exactly as `warnOnSkippedEvents` does. */
 declare const __DEV__: boolean | undefined;
@@ -56,7 +70,8 @@ declare const __DEV__: boolean | undefined;
 /** One diagnosis. `name` is stable and machine-readable; `detail` is for a human reading a console. */
 export type WireDoctorCheck = {
   /**
-   * Stable id: `target` | `reachability` | `storage` | `round_trip` | `dev_only` | `internal_error`.
+   * Stable id: `target` | `reachability` | `storage` | `round_trip` | `join_key` | `dev_only` |
+   * `internal_error`.
    *
    * `dev_only` means ONE thing and only that thing: `__DEV__` is unset or false, so nothing ran.
    * `internal_error` is the separate catch-all for a failure that got past every check's own
@@ -75,6 +90,20 @@ export type WireDoctorReport = {
   checks: WireDoctorCheck[];
 };
 
+/**
+ * What the join check needs: the same three values the host hands `<WireOnboarding>`. Pass the very
+ * props you pass the component — anything reconstructed here would diagnose a DIFFERENT integration
+ * than the one that ships.
+ */
+export type WireDoctorJoinTarget = {
+  /** The same `config.appId`. It namespaces the persisted auto key, so the wrong one reads the wrong slot. */
+  appId?: string;
+  /** The same `userContext` prop. Only `device_key` is read; nothing else is inspected or reported. */
+  userContext?: Record<string, string | number | boolean>;
+  /** The same `autoJoinKey` prop. `false` is the documented opt-out from the kit's auto-join. */
+  autoJoinKey?: boolean;
+};
+
 /** Input for {@link wireDoctor}. `storage` is optional: without it the queue runs in-memory only. */
 export type WireDoctorOptions = {
   /** The same `{serverUrl, apiKey}` the kit is configured with. */
@@ -84,6 +113,11 @@ export type WireDoctorOptions = {
    * check reports the DEGRADED in-memory mode rather than failing.
    */
   storage?: WireOnboardingStorage;
+  /**
+   * The join-key inputs. OMITTING THIS FAILS THE `join_key` CHECK — deliberately, and see
+   * {@link checkJoinKey} for why a skipped join check may not read as a pass.
+   */
+  join?: WireDoctorJoinTarget;
 };
 
 /**
@@ -284,6 +318,110 @@ const checkRoundTrip = async (target: ClientEventTarget): Promise<WireDoctorChec
   );
 };
 
+/**
+ * CHECK 5: will an onboarding session carry the JOIN KEY?
+ *
+ * WHY THIS IS NOT COVERED BY THE OTHER FOUR: they prove events LEAVE and are ACCEPTED. None of them
+ * proves the events can be JOINED. `user_context.device_key` is the only thing that stitches an
+ * onboarding session to everything the app reports later, so without it every event is written,
+ * every check is green, and the `activated` funnel still reads a permanent ZERO. Two real consumers
+ * shipped exactly that. A doctor that passes an integration whose funnel can never be non-zero is
+ * reporting on the wrong question.
+ *
+ * ⛔ STRICTLY READ-ONLY, and that constraint shapes the whole check. It would be far easier to call
+ * `hydrateDeviceIdentity` and read `.durable` off the result — but that MINTS, registers on the
+ * process-wide registry, and persists. Two things forbid it: this module's own contract ("mints no
+ * `globalThis` slot", "never a side effect on the host"), and the 0.15.1 defect where a propless
+ * READER wrote into the census it read, so the host's real `appId` registering afterwards made the
+ * census read two and the reader answered `undefined` for the rest of the process. A diagnostic that
+ * causes the defect class it diagnoses is worse than no diagnostic. So this check only ever READS:
+ * one `getItem`, plus pure predicates. Same reason it uses {@link isUsableIdentityValue} and not
+ * `resolveIdentity` — the latter WRITES the provenance registry for a `host`-sourced value.
+ *
+ * The verdicts mirror `WireOnboarding`'s own three auto-join conditions, in its order.
+ */
+const checkJoinKey = async (
+  join: WireDoctorJoinTarget | undefined,
+  storage: WireOnboardingStorage | undefined,
+  storageOk: boolean,
+): Promise<WireDoctorCheck> => {
+  // NOT a pass. The whole module already rules that a check which never ran may not report healthy
+  // (that is why `dev_only` is `ok: false`), and this is the same shape: a green report that never
+  // looked at the join is precisely the outcome this check exists to remove.
+  if (!join) {
+    return check(
+      "join_key",
+      false,
+      "NOT EVALUATED: pass `join: { appId, userContext, autoJoinKey }` — the same values you pass " +
+        "<WireOnboarding> — so the doctor can tell whether this integration's sessions will be joinable. " +
+        "It is reported as a failure rather than skipped because every other check can pass while the " +
+        "funnel reads a permanent zero.",
+    );
+  }
+  // A host-supplied key ALWAYS wins and is never touched by the kit, so nothing else matters.
+  // ⛔ The key's VALUE is never reported, the same discipline the target check applies to the apiKey.
+  if (isUsableIdentityValue(join.userContext?.device_key)) {
+    return check(
+      "join_key",
+      true,
+      "user_context.device_key is supplied by the host, so onboarding sessions join the rest of the funnel.",
+    );
+  }
+  if (join.autoJoinKey === false) {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key AND autoJoinKey is false, so these onboarding sessions are UNLINKED " +
+        "by choice: they join nothing the app reports later and the activated funnel reads zero. " +
+        "Supply user_context.device_key, or drop autoJoinKey:false to let the kit inject its own.",
+    );
+  }
+  if (!storage) {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key, and the kit cannot auto-inject one without storage: an unpersisted key " +
+        "differs every launch, which corrupts the server's session counting rather than just leaving it " +
+        "empty, so the kit declines it. Pass AsyncStorage (or an MMKV wrapper) to <WireOnboarding>.",
+    );
+  }
+  if (!storageOk) {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key, and the storage check above FAILED — the kit refuses a non-durable auto " +
+        "key, so it will inject nothing and these sessions will not join. Fix the storage adapter first.",
+    );
+  }
+  let persisted: string | null = null;
+  try {
+    persisted = await storage.getItem(deviceIdStorageKey(join.appId));
+  } catch {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key, and reading the persisted auto key threw, so it is unknown whether the " +
+        "kit can supply one. Treat this as the storage adapter being unreliable.",
+    );
+  }
+  if (isUsableIdentityValue(persisted)) {
+    return check(
+      "join_key",
+      true,
+      "no host device_key, but a durable auto join key is already persisted for this appId, so sessions join.",
+    );
+  }
+  // First run on this install: nothing persisted YET. That is the normal cold start, not a fault —
+  // the kit mints and persists on first mount, and the storage check above already proved a real
+  // write/read round trip, which is the condition the kit gates that injection on.
+  return check(
+    "join_key",
+    true,
+    "no host device_key and none persisted yet (first run): the kit will mint and persist its own on first " +
+      "mount, and the storage check above proved the write/read round trip that injection is gated on.",
+  );
+};
+
 /**
  * Run the full diagnosis. Resolves a report; NEVER throws and NEVER rejects.
  *
@@ -307,16 +445,23 @@ export const wireDoctor = async (options: WireDoctorOptions): Promise<WireDoctor
   }
   try {
     const target = options?.target;
-    const checks: WireDoctorCheck[] = [checkTarget(target)];
+    const targetCheck = checkTarget(target);
+    const checks: WireDoctorCheck[] = [targetCheck];
     // Reachability and the round trip both need a usable target; running them against a broken one
     // would report a network failure and bury the real cause, which check 1 already named.
-    if (checks[0]!.ok && target) {
+    const targetUsable = targetCheck.ok && !!target;
+    if (targetUsable && target) {
       checks.push(await checkReachability(target.serverUrl));
-      checks.push(await checkStorage(options?.storage));
+    }
+    const storageCheck = await checkStorage(options?.storage);
+    checks.push(storageCheck);
+    if (targetUsable && target) {
       checks.push(await checkRoundTrip(target));
-    } else {
-      checks.push(await checkStorage(options?.storage));
     }
+    // Last, and it runs in BOTH branches: the join question is independent of the target entirely.
+    // An integration can have a perfect server and a permanently unjoinable funnel, which is the
+    // whole reason this check exists — so a broken target must not hide it.
+    checks.push(await checkJoinKey(options?.join, options?.storage, storageCheck.ok));
     return { ok: checks.every((c) => c.ok), checks };
   } catch {
     // Belt and braces: every check above already swallows its own failures, so reaching here means

package/src/coachmarks/CoachmarkProvider.tsx

@@ -1,12 +1,13 @@
 import React, { useEffect } from "react";
 
-import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { useResolvedFeaturesState } from "../features/WireFeaturesProvider";
 import type { WireFeatures, WireFeaturesConfig } from "../features/types";
 import { CoachmarkOverlayHost } from "./CoachmarkOverlayHost";
 import {
   getCoachmarkStorage,
   setCoachmarkStorage,
   setCoachmarksEnabled,
+  setCoachmarksResolved,
   setCoachmarkTesting,
 } from "./runtime";
 import type { CoachmarkStorage } from "./types";
@@ -36,6 +37,11 @@ export interface CoachmarkProviderProps {
    * pre-resolved `features`, OR a `featuresConfig` (serverUrl + apiKey) to lazily fetch once, OR
    * mount a `WireFeaturesProvider` above (context is read automatically). Omit all three and
    * coachmarks stay on (fail-open) — zero behavior change for hosts that never adopt flags.
+   *
+   * While a fetch is still in flight, a NEW tour does not arm (so a tenant who switched the module
+   * off gets no first impression), and a tour already in flight is never torn down. Nothing is
+   * spent by that wait: no once-gate is consumed, so an ON answer plays the tour in full. A failed
+   * fetch is an answer — fail-open is unchanged.
    */
   features?: WireFeatures;
   /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
@@ -69,17 +75,30 @@ export const CoachmarkProvider: React.FC<CoachmarkProviderProps> = ({
   children,
 }) => {
   // Resolve the coachmarks kill switch: explicit `features` → context → lazy fetch → all-on.
-  const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
-  const coachmarksOn = flags.coachmarks.enabled;
+  // `settled` is what separates "on because the tenant says so" from "on because nobody has asked
+  // yet" — the flags alone cannot tell those apart, and the second one is a guess.
+  const { flags, settled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig,
+  });
+  // NEVER publish a `false` verdict on a guess. The kill switch is TERMINAL for a tour in flight
+  // (`useCoachmarkTour` subscribes and exits on a flip to false), so holding the surface by writing
+  // it false while the fetch is in flight would end the tour of every ENABLED tenant on every cold
+  // start — a worse defect than the one this fixes. The wait is published separately below, where
+  // it blocks only the ARM of a NEW tour. (While unsettled the resolved flags ARE the all-on
+  // defaults, so this `true` is not overriding a tenant answer; it is naming the guess as one.)
+  const coachmarksOn = settled ? flags.coachmarks.enabled : true;
 
   // Apply during render so gates + the kill switch are readable before any child effect fires.
   setCoachmarkStorage(storage);
   setCoachmarkTesting(isTestingCoachmark);
+  setCoachmarksResolved(settled);
   setCoachmarksEnabled(coachmarksOn);
 
   useEffect(() => {
     setCoachmarkStorage(storage);
     setCoachmarkTesting(isTestingCoachmark);
+    setCoachmarksResolved(settled);
     setCoachmarksEnabled(coachmarksOn);
     return () => {
       // Only clear if THIS provider's storage is still the live singleton — a
@@ -87,10 +106,12 @@ export const CoachmarkProvider: React.FC<CoachmarkProviderProps> = ({
       if (getCoachmarkStorage() === storage) {
         setCoachmarkStorage(null);
       }
-      // Restore the fail-open default so a torn-down provider never leaves coachmarks dark.
+      // Restore the fail-open defaults so a torn-down provider never leaves coachmarks dark, nor
+      // leaves a tour that outlives it unable to arm.
       setCoachmarksEnabled(true);
+      setCoachmarksResolved(true);
     };
-  }, [storage, isTestingCoachmark, coachmarksOn]);
+  }, [storage, isTestingCoachmark, coachmarksOn, settled]);
 
   return (
     <>

package/src/coachmarks/runtime.ts

@@ -51,6 +51,12 @@ type CoachmarkRuntime = {
   // 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;
+  // Whether `coachmarksEnabled` is an ANSWER from the tenant, or still the optimistic all-on
+  // default nobody has confirmed. Default true = fail-open, and OPTIONAL on the type for the same
+  // reason as `listeners` below: a record left by an inlined copy from an OLDER kit version has no
+  // such field, and reading that absence as `false` would stop every tour under it from arming.
+  // See setCoachmarksResolved for why this is a SECOND flag and not a third state on the first.
+  coachmarksResolved?: boolean;
   // Subscribers to the kill switch. OPTIONAL on the type (never on the behaviour) so a record left
   // in the registry by an inlined copy from an OLDER kit version — which had no listener set — is
   // upgraded in place rather than read as corrupt.
@@ -118,6 +124,50 @@ export const setCoachmarksEnabled = (value: boolean): void => {
 /** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */
 export const areCoachmarksEnabled = (): boolean => coachmarkRuntime().coachmarksEnabled;
 
+/**
+ * Mark whether the value in `coachmarksEnabled` is the tenant's ANSWER or still the optimistic
+ * default nobody has confirmed. Written by CoachmarkProvider from the resolved features' `settled`;
+ * read (subscribed) by `useCoachmarkTour`'s ARM effect, and by nothing else.
+ *
+ * ── WHY A SECOND FLAG AND NOT A THIRD STATE ON `coachmarksEnabled` ──────────────────────────────
+ * The features fetch seeds the all-on defaults and swaps when `GET /v1/features` resolves, so on
+ * every cold start there is a window where "coachmarks: on" only means "nobody has asked yet". A
+ * tenant who switched the module OFF still gets the first tour of every launch out of that window.
+ *
+ * The obvious repair — hold the surface by writing `setCoachmarksEnabled(false)` until the answer
+ * lands — CANNOT be used here, and would ship a strictly worse defect. That flag is TERMINAL: the
+ * tour subscribes to it and a flip to false calls `exit()`, ending the tour. Writing it `false`
+ * during the wait would end the tour of every ENABLED tenant on every cold start. So the two facts
+ * are kept apart, and only one of them is terminal:
+ *   • `coachmarksEnabled`  — the verdict. `false` tears a tour down. Stays `true` while the answer
+ *     is unknown, so nothing is ever torn down on a guess.
+ *   • `coachmarksResolved` — "is that verdict an answer?". `false` only blocks ARMING a NEW tour.
+ *     No timer starts, no overlay shows, and no once-gate is consumed, so the tour plays in full
+ *     the moment an ON answer lands.
+ *
+ * "Resolved" means the fetch ANSWERED, not that it SUCCEEDED — `fetchWireFeatures` swallows a
+ * timeout / 401 / 5xx into the all-on defaults and that fallback IS the answer, so an unreachable
+ * control plane arms the tour rather than darking it (fail-open, unchanged).
+ *
+ * Shares the kill switch's listener set: a subscriber has to wake on either fact changing, and one
+ * set is one thing to keep correct rather than two.
+ */
+export const setCoachmarksResolved = (value: boolean): void => {
+  const runtime = coachmarkRuntime();
+  if ((runtime.coachmarksResolved ?? true) === value) return;
+  runtime.coachmarksResolved = value;
+  notifyCoachmarksEnabled();
+};
+
+/**
+ * Whether the coachmarks verdict is an ANSWER yet. False → a NEW tour must not arm (a tour already
+ * in flight is untouched). Absent field → true: no provider, or an older inlined copy's record,
+ * means nothing is going to answer this, which is the same fail-open default the features
+ * `settled` context takes.
+ */
+export const areCoachmarksResolved = (): boolean =>
+  coachmarkRuntime().coachmarksResolved ?? true;
+
 /**
  * Subscribe to kill-switch flips. Returns the unsubscribe function — the `useSyncExternalStore`
  * contract, and deliberately the SAME shape as `coachmarkOverlay.subscribe` next door rather than
@@ -129,6 +179,9 @@ export const areCoachmarksEnabled = (): boolean => coachmarkRuntime().coachmarks
  * nothing can be tapped to advance, and no terminal path is reachable. `useCoachmarkTour`
  * subscribes instead. The listener set lives in the SAME `globalThis` record as the flag, so every
  * inlined copy of this module shares one subscriber list.
+ *
+ * It also carries `coachmarksResolved` (see `setCoachmarksResolved`): both facts wake the same
+ * listeners, so a `useSyncExternalStore` over either one uses this same subscribe function.
  */
 export const subscribeCoachmarksEnabled = (listener: () => void): (() => void) => {
   const listeners = enabledListeners();

package/src/coachmarks/useCoachmarkTour.ts

@@ -4,6 +4,7 @@ import { coachmarkAnchors } from "./coachmarkAnchorRegistry";
 import { coachmarkOverlay } from "./coachmarkOverlayStore";
 import {
   areCoachmarksEnabled,
+  areCoachmarksResolved,
   coachmarkGateKey,
   hasSeenGate,
   markSeenGate,
@@ -76,6 +77,15 @@ const DEFAULT_START_DELAY_MS = 3000;
  * `show()` is a no-op while the flag is off, so a tour that carried on would paint nothing, could
  * not be tapped to advance, and would never reach a terminal state.
  *
+ * ARM vs TERMINAL — the third gate, and why it is not the second one. Until the tenant's flags
+ * land, that kill switch reads ON because nobody has asked yet, so a tenant who turned coachmarks
+ * OFF still got the first tour of every cold start. The wait CANNOT be expressed by writing the
+ * kill switch false, precisely because that flag is terminal: it would end the tour of every
+ * ENABLED tenant on every cold start, a worse defect than the one being fixed. So an UNANSWERED
+ * verdict (`areCoachmarksResolved`, written by CoachmarkProvider from the features' `settled`)
+ * blocks only the ARM below — a tour already in flight is never touched by it — and costs nothing
+ * while it waits: no timer, no overlay, no once-gate spent.
+ *
  * IMPORTANT: `steps` MUST be a stable (memoized) array. If a new array identity
  * is passed on every render the drive effect re-runs and re-shows the current
  * step (wasteful anchor re-resolves / overlay churn), and analytics can
@@ -120,6 +130,15 @@ export const useCoachmarkTour = (
     areCoachmarksEnabled,
   );
 
+  // Whether that kill switch is an ANSWER yet, or still the optimistic all-on default. Gates the
+  // ARM effect only — see the ARM vs TERMINAL note above. Same subscribe function: both facts live
+  // in one runtime record and wake one listener set.
+  const coachmarksResolved = useSyncExternalStore(
+    subscribeCoachmarksEnabled,
+    areCoachmarksResolved,
+    areCoachmarksResolved,
+  );
+
   /**
    * The single terminal exit. `writeGate` is what separates the two ways a tour can end:
    *   • the user reached the end (or dismissed the last step) → the once-gate IS written, so a
@@ -147,18 +166,40 @@ export const useCoachmarkTour = (
   // Arm once, after the delay, when enabled and the gate is unseen.
   useEffect(() => {
     if (!enabled || startedRef.current) return undefined;
+    // AN EMPTY TOUR IS NOT A TOUR — never arm on one. With no steps the arm timer still fired, the
+    // drive effect below immediately hit `activeIndex >= steps.length`, and `finish()` wrote the
+    // once-gate for a tour the user never saw a single frame of. The gate is persisted and
+    // `finishedRef` blocks recovery in this mount, so the tour was dead for good — even after the
+    // catalog that produced the empty list was fixed. It is not a hypothetical list either: on the
+    // documented AI path `selectTourSteps(catalog, selection)` returns `[]` whenever the server
+    // sends ids that match nothing in the SHIPPED catalog (an app that cannot be force-updated),
+    // and any host whose steps arrive async passes `[]` on the first render.
+    //
+    // Keyed on `steps.length`, deliberately NOT on the array itself: the drive effect below already
+    // requires a memoized `steps`, and listing the identity here would restart the arm timer on
+    // every render of a host that passes an inline array (frequent_rules #11) — a tour that never
+    // arms, swapping one silent failure for another. The length is a value, so late-arriving steps
+    // still re-run this effect and arm the tour properly.
+    if (steps.length === 0) return undefined;
     // Feature kill switch: never arm while coachmarks are disabled, so no timer starts, no
     // overlay shows, and the once-gate is NOT consumed — re-enabling replays the tour. Reading
     // the SUBSCRIBED value (and listing it in the deps) is what makes that last clause true
     // without a remount: flipping it off clears a pending arm timer, flipping it back on re-arms.
     if (!coachmarksOn) return undefined;
+    // …and never arm on an UNANSWERED one. `coachmarksOn` is all-on until the tenant's flags land,
+    // so without this a tenant who switched coachmarks off still got the first tour of every cold
+    // start — the kill switch working everywhere except the one moment it is read. Blocking the
+    // ARM (rather than writing the kill switch false, which is terminal — see the note above) is
+    // what makes the wait free: no timer, no overlay, no once-gate spent, so an ON answer plays
+    // the tour in full. A FAILED fetch is an answer too, so a dead control plane still arms.
+    if (!coachmarksResolved) return undefined;
     if (showOnce && hasSeenGate(coachmarkGateKey(tourId))) return undefined;
     const timer = setTimeout(() => {
       startedRef.current = true;
       setActiveIndex(0);
     }, startDelayMs);
     return () => clearTimeout(timer);
-  }, [enabled, coachmarksOn, startDelayMs, showOnce, tourId]);
+  }, [enabled, coachmarksOn, coachmarksResolved, startDelayMs, showOnce, tourId, steps.length]);
 
   // Drive the active step. Keyed on `enabled` too, so a mid-tour focus loss
   // pauses (hide, keep position) and a return to focus resumes the same step.
@@ -182,6 +223,15 @@ export const useCoachmarkTour = (
       return undefined;
     }
 
+    // The other half of the empty-tour rule, for a list that goes empty AFTER the tour armed (a
+    // re-selection, a catalog swap): end it, but take the kill-switch exit — `exit(false)` — so the
+    // once-gate is not written. `finish()` here would spend it on a tour with nothing to show, which
+    // is exactly the burn the arm guard above refuses at the other end.
+    if (steps.length === 0) {
+      exit(false);
+      return undefined;
+    }
+
     if (activeIndex >= steps.length) {
       finish();
       return undefined;

package/src/context/deviceId.ts

@@ -73,8 +73,8 @@ export const mintDeviceId = (): string => {
  * Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle.
  *
  * @globalSlot LATCH — the REGISTRY OBJECT is created once and its identity is then stable. A second
- * write empties `keys`/`hydrating`/`pending`, so the next surface mints a SECOND auto id for one
- * install and the `device_key` the server joins sessions on splits in two — the halved-counter
+ * write empties `keys`/`hydrating`/`pending`/`ambient`, so the next surface mints a SECOND auto id
+ * for one install and the `device_key` the server joins sessions on splits in two — the halved-counter
  * defect this registry exists to close. Its CONTENTS are live (the id per `appId` is replaced when
  * an async hydration adopts a persisted value), so callers must re-read through
  * `resolveAutoDeviceKey()` rather than hold the string a mount happened to see first.
@@ -91,11 +91,17 @@ const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoD
 type HydrationOutcome = { value: string; durable: boolean };
 
 /** 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. */
+ *  and the in-flight (or settled) hydration promise per `appId` so a waiter can join it.
+ *
+ *  `ambient` is deliberately NOT an entry in `keys`: it is the last-resort id
+ *  {@link ambientAutoDeviceKey} mints for a process that has registered no id space at all, and
+ *  `keys` is the TENANT CENSUS that same function counts to decide whether it may answer. Putting
+ *  the fallback in the census made the fallback look like a tenant — see the note on that function. */
 type AutoDeviceKeyRegistry = {
   keys: Map<string, string>;
   hydrating: Set<string>;
   pending?: Map<string, Promise<HydrationOutcome>>;
+  ambient?: string;
 };
 
 type GlobalWithDeviceKeys = typeof globalThis & {
@@ -237,8 +243,19 @@ export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): st
  * 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).
+ * Never throws or rejects: a missing or rejecting adapter resolves to the in-memory id, and with no
+ * `storage` it resolves immediately (there is nothing to hydrate from).
+ *
+ * ⛔ A HUNG ADAPTER IS THE ONE CASE IT DOES NOT COVER, and this line used to claim it did. The read
+ * underneath is a bare `storage.getItem` with no ceiling of its own, so an adapter that neither
+ * resolves nor rejects (a locked keychain, a wedged native bridge) leaves THIS PROMISE PENDING
+ * FOREVER — it does not fall back to the in-memory id, it simply never answers. Anything that gates
+ * a user-visible or metric-bearing action on the result must therefore race it against a ceiling of
+ * its own: `<WireOnboarding>` does (`AUTO_JOIN_HYDRATION_TIMEOUT_MS`), and so do the two lifecycle
+ * hooks (`session-analytics/useLifecycleEvents` + `useSessionStart`, through the shared
+ * `withTimeout` + `READ_TIMEOUT_MS` in `session/persistedSession`) — a hung read there had silently
+ * killed `app.session_started` and `app.first_open` for the whole process. Use the SYNC
+ * {@link resolveAutoDeviceKey} when you cannot afford to wait at all.
  *
  * ⚠️ IT RETURNS A BARE STRING, so it CANNOT say whether the id survives the launch — a degraded
  * adapter resolves to the in-memory mint and reads identically to a persisted one. No kit surface
@@ -263,7 +280,9 @@ export const hydrateAutoDeviceKey = async (
  *
  * Resolves `undefined` only when there is no usable id at all. With no `storage` it resolves
  * immediately with `durable: false` — a process-scoped id is exactly what "no persistence" means.
- * Never throws or rejects.
+ * Never throws or rejects — but, exactly like {@link hydrateAutoDeviceKey} above, it can also never
+ * SETTLE on a hung adapter (the underlying `getItem` carries no ceiling), so every caller races it
+ * against one of its own. See the note there.
  */
 export const hydrateDeviceIdentity = async (
   opts: ResolveAutoDeviceKeyOptions = {},
@@ -290,6 +309,7 @@ export const resetAutoDeviceKeys = (): void => {
   registry.keys.clear();
   registry.hydrating.clear();
   registry.pending?.clear();
+  registry.ambient = undefined;
 };
 
 /**
@@ -303,23 +323,37 @@ export const resetAutoDeviceKeys = (): void => {
  * the halved-counter defect this registry exists to close (see the registry note above), arrived at
  * from the other direction.
  *
- * So this READS and does not address:
+ * So this READS the TENANT CENSUS (`registry.keys`) and does not address it:
  *   • exactly one id space in the process → that id, whoever registered it. This is every
  *     single-tenant app, i.e. every real app, and it is how the gate joins the analytics surfaces.
- *   • none at all → mint one through {@link resolveAutoDeviceKey}. Nothing exists to collide with,
- *     so `"default"` is not a second space, it is the first. PROCESS-scoped (there is no storage to
- *     persist through), which is honest and still resolvable: a review row is written once per user,
- *     so a per-launch value here cannot corrupt a counter the way it corrupts `min_sessions`.
+ *   • none at all → the registry's `ambient` fallback, minted here on first ask. Nothing exists to
+ *     collide with, so it is not a second space, it is the only one. PROCESS-scoped (there is no
+ *     storage to persist through), which is honest and still resolvable: a review row is written
+ *     once per user, so a per-launch value here cannot corrupt a counter the way it corrupts
+ *     `min_sessions` — and without SOME unit the server discards the impression's
+ *     `idempotency_key` outright, so refusing to answer costs a re-post its upsert.
  *   • two or more → `undefined`. Two tenants in one process must never share an id, and a caller
  *     with no `appId` cannot say which one it belongs to. Refusing is the only safe answer;
  *     guessing would stamp one tenant's device onto the other's row.
  *
- * Never throws, never mints a SECOND id, and never overrides anything a host supplied — the caller
- * checks for a host value first.
+ * ⛔ THE FALLBACK IS NOT A TENANT, AND THAT IS THE WHOLE REASON IT LIVES IN ITS OWN FIELD (0.15.1).
+ * It used to be minted through `resolveAutoDeviceKey()`, which registered it in `keys` under
+ * `"default"`. The three states above are only exhaustive at ONE INSTANT, and this one wrote into
+ * the very map the next instant is judged by: a gate that fired before any Wire surface had
+ * initialised (the review gate lives on the home feed, so a cold start can reach it first) left a
+ * `"default"` entry behind, and the moment the host's real `appId` registered the census read TWO —
+ * so every later call returned `undefined` and the injected `device_key` was silently dead for the
+ * rest of the process. Holding the fallback OUTSIDE the census makes it yield instead: a real id
+ * space appearing later simply wins, which is the answer the middle bullet wanted all along.
+ *
+ * Never throws, never mints a SECOND id into the census, and never overrides anything a host
+ * supplied — the caller checks for a host value first.
  */
 export const ambientAutoDeviceKey = (): string | undefined => {
   const registry = autoDeviceKeyRegistry();
-  if (registry.keys.size === 0) return resolveAutoDeviceKey();
   if (registry.keys.size > 1) return undefined;
-  return [...registry.keys.values()][0];
+  const sole = [...registry.keys.values()][0];
+  if (sole) return sole;
+  if (!registry.ambient) registry.ambient = mintDeviceId();
+  return registry.ambient;
 };