@wireai/activation 0.12.2 → 0.13.2

package/package.json

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

package/src/OnboardingFlow.tsx

@@ -36,6 +36,17 @@ import { deriveAnswers } from "./utils/deriveAnswers";
 import { readProgress } from "./utils/readProgress";
 import { reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
 import { sendPreview } from "./analytics/sendPreview";
+import { PermissionCardView, PERMISSION_CARD_NAME } from "./cards/PermissionCard";
+import { permissionEventName, permissionEventProps } from "./permissions/permissionEvents";
+import { selectDuePermissionScreen } from "./permissions/placement";
+import { resolvePermissionCopy } from "./permissions/permissionCopy";
+import type {
+  PermissionScreenConfig,
+  PermissionStage,
+  WirePermissionKind,
+  WirePermissionOutcome,
+  WirePermissionStatus,
+} from "./permissions/types";
 import type { DeviceContext } from "./device/deviceContext";
 import type { OnboardingCopy, OnboardingEvent, OnboardingResult, StepValidator } from "./types";
 
@@ -75,6 +86,25 @@ type OnboardingFlowProps = {
    * `started` so host funnels don't double-count the session.
    */
   resumed?: boolean;
+  /**
+   * Host-declared permission screens injected into this server-driven stream. See
+   * `permissions/types.ts`: the OS dialog is only ever reached from the primary tap.
+   */
+  permissionScreens?: PermissionScreenConfig[];
+  /**
+   * Screen ids already settled in THIS session, restored from `storage` by WireOnboarding so an
+   * app kill mid-flow does not re-ask. Empty (the default) means "nothing settled yet".
+   */
+  settledPermissions?: readonly string[];
+  /**
+   * True while that restore is still in flight. Permission screens are suppressed until it lands,
+   * because showing one before the record is read is exactly the re-ask the record prevents. The
+   * read is short (one storage get, timeout-capped) and cannot outlive the first card's round trip
+   * in practice, so this normally never shows up as a delay.
+   */
+  permissionsPending?: boolean;
+  /** Persist one settled screen id (fire-and-forget; WireOnboarding owns the storage). */
+  onPermissionSettled?: (id: string, outcome: WirePermissionOutcome) => void;
 };
 
 // The kit's per-question Skip sends this sentinel; the backend skips ONE question
@@ -112,6 +142,10 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   sessionId,
   resumed = false,
   clientContext,
+  permissionScreens,
+  settledPermissions,
+  permissionsPending = false,
+  onPermissionSettled,
 }) => {
   const { messages, error, isLoading, sendMessage, reset } = useWireAIThread();
   const makeActions = useWireAIAction(sendMessage);
@@ -156,6 +190,11 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const [timedOut, setTimedOut] = useState(false);
   const [validationError, setValidationError] = useState<string | undefined>();
   const [validating, setValidating] = useState(false);
+  // Permission screens settled during THIS mount, on top of whatever was restored from storage.
+  // A settled screen never comes back, which is the "shown exactly once" half of the contract.
+  const [locallySettledPermissions, setLocallySettledPermissions] = useState<string[]>([]);
+  const onPermissionSettledRef = useRef(onPermissionSettled);
+  onPermissionSettledRef.current = onPermissionSettled;
 
   const lastCard = useMemo<Message | undefined>(
     () => [...messages].reverse().find((m) => m.role === "assistant" && m.response?.action === "render"),
@@ -324,6 +363,51 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
     sendMessage(SKIP_ONE_SENTINEL);
   }, [isLoading, sendMessage]);
 
+  // ── Permission screens (host-injected, never server-driven in this release) ─────────────────
+  //
+  // Analytics for one moment of a permission screen. It rides the SAME plumbing as the rest of the
+  // funnel: an `app_event` on `/v1/events` whose `question_key` is the canonical `wire_permission_*`
+  // name (exactly how `WIRE_PURCHASE_EVENTS` reach the wire), carrying the same device snapshot and
+  // `user_context`, so the `device_key` join that makes every other number real covers these too.
+  // It is ALSO surfaced on `onEvent`, so a host keeps its own analytics without a second wiring.
+  //
+  // `screen_index` is the last card index shown, NOT a new one: a permission screen is not a
+  // question, so it must never introduce a screen index the server never emitted a `screen_shown`
+  // for. Nothing here can throw into the UI (reportClientEvent is fire-and-forget by contract).
+  const emitPermissionStage = useCallback(
+    (permission: WirePermissionKind, stage: PermissionStage, status?: WirePermissionStatus) => {
+      onEventRef.current?.({ type: "permission", permission, stage, status });
+      reportClientEvent(reportTargetRef.current, {
+        event_type: "app_event",
+        session_id: sessionIdRef.current,
+        question_key: permissionEventName(stage),
+        component: PERMISSION_CARD_NAME,
+        screen_index: lastScreenIndexRef.current >= 0 ? lastScreenIndexRef.current : undefined,
+        meta: JSON.stringify(permissionEventProps(permission, status)),
+        device: clientContextRef.current?.device,
+        user_context: clientContextRef.current?.userContext,
+        user_id: clientContextRef.current?.userId,
+      });
+    },
+    [],
+  );
+
+  // A screen is DONE: remember it (so it never returns), let the host persist that across a kill,
+  // and hand the outcome to `onResult`, the seam a host schedules its first local notification
+  // from. A throwing host callback is swallowed: the flow continues on every path, always.
+  const settlePermission = useCallback(
+    (id: string, screen: PermissionScreenConfig, outcome: WirePermissionOutcome) => {
+      setLocallySettledPermissions((prev) => (prev.includes(id) ? prev : [...prev, id]));
+      onPermissionSettledRef.current?.(id, outcome);
+      try {
+        screen.onResult?.(screen.permission, outcome);
+      } catch {
+        // A host's post-grant work (scheduling a reminder) must never break onboarding.
+      }
+    },
+    [],
+  );
+
   // Prefetch on SELECT — the fix for "the first AI question is always the slowest". Q1 is a
   // deterministic base card (instant); Q2 is the first LLM turn, and neither cache protects it
   // (flow-cache misses a novel answer combo, the provider prompt-cache is cold on the first
@@ -356,8 +440,15 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const wrappedActions = useCallback(
     (messageId: string) => {
       const base = makeActions(messageId);
-      const key = progress.key;
-      const validator = key ? validatorsRef.current?.[key] : undefined;
+      // ⚠️ HOST VALIDATORS LIVE IN THE SAME KEY NAMESPACE `deriveAnswers` files answers under, so
+      // moving the answer key to `slot_id` without moving this lookup would silently UNBIND every
+      // host validator — no error, no warning, values just stop being checked. Try the slot first
+      // (matching the answer key), then fall back to the question key, so a host that has not yet
+      // renamed its validator map keeps working while a server rolls slots out.
+      const validators = validatorsRef.current;
+      const validator =
+        (progress.slot_id ? validators?.[progress.slot_id] : undefined) ??
+        (progress.key ? validators?.[progress.key] : undefined);
       if (!validator) return base;
 
       const out: Record<string, (...args: unknown[]) => void> = { ...base };
@@ -387,7 +478,7 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
       }
       return out;
     },
-    [makeActions, progress.key],
+    [makeActions, progress.key, progress.slot_id],
   );
 
   // ── Render ────────────────────────────────────────────────────────────────
@@ -431,6 +522,53 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const total = progress.total ?? approxScreens;
   const isTerminal = response.action === "render" && response.component === "StatusCard";
 
+  // A permission screen sits IN FRONT of the card the flow was about to render (including the
+  // terminal recap, which is what `"beforeEnd"` means), and hands that card straight back once it
+  // settles. Nothing is sent to the backend, nothing is appended to the thread, and `step` is
+  // untouched, so the progress bar, the funnel, and `deriveAnswers` cannot tell it happened.
+  // Placement is resolved against the card ABOUT to render, because the stream length is
+  // server-driven; an `afterCard` the stream never reaches clamps to the terminal position.
+  const duePermission = permissionsPending
+    ? undefined
+    : selectDuePermissionScreen(
+        permissionScreens,
+        settledPermissions
+          ? [...settledPermissions, ...locallySettledPermissions]
+          : locallySettledPermissions,
+        { cardIndex: renderedCount - 1, isTerminal },
+      );
+
+  if (duePermission) {
+    const { screen, id } = duePermission;
+    const copy = resolvePermissionCopy(screen.permission, screen.copy);
+    return (
+      <OnboardingScaffold step={step} approxScreens={total}>
+        {/* The same shell + handoff every card uses; "spring" is the value-beat register the
+            InterstitialCard already wears, which is what this screen is. */}
+        <CardHandoff transitionKey={`permission:${id}`} variant="spring">
+          <PermissionCardView
+            key={id}
+            permission={screen.permission}
+            title={copy.title}
+            message={copy.message}
+            primaryLabel={copy.primaryLabel}
+            secondaryLabel={copy.secondaryLabel}
+            blockedTitle={copy.blockedTitle}
+            blockedMessage={copy.blockedMessage}
+            settingsLabel={copy.settingsLabel}
+            continueLabel={copy.continueLabel}
+            illustration={screen.illustration}
+            request={screen.request}
+            getStatus={screen.getStatus}
+            openSettings={screen.openSettings}
+            onStage={(stage, status) => emitPermissionStage(screen.permission, stage, status)}
+            onSettled={(outcome) => settlePermission(id, screen, outcome)}
+          />
+        </CardHandoff>
+      </OnboardingScaffold>
+    );
+  }
+
   // Terminal recap: show what the app will now do for the user (backend-authored),
   // and finish only when they tap the CTA.
   if (isTerminal) {

package/src/WireOnboarding.tsx

@@ -22,8 +22,9 @@ import { OnboardingFlow, DEFAULT_COPY } from "./OnboardingFlow";
 import { onboardingComponents } from "./cards";
 import { makeSessionId, reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
 import { collectDeviceContext, type DeviceContext } from "./device/deviceContext";
-import { hydrateAutoDeviceKey } from "./context/deviceId";
+import { hydrateDeviceIdentity } from "./context/deviceId";
 import { activationJoinContext } from "./context/userContext";
+import { hostIdentity, resolveIdentity } from "./identity/identityRecord";
 import { sanitizeUserId } from "./identity/userIdentity";
 import {
   clearPersistedSession,
@@ -33,23 +34,24 @@ import {
   DEFAULT_SESSION_TTL_MS,
   type LoadedSession,
 } from "./session/persistedSession";
+import {
+  clearSettledPermissions,
+  loadSettledPermissions,
+  permissionStorageKey,
+  saveSettledPermissions,
+} from "./permissions/permissionMemory";
 import type { OnboardingResult, WireOnboardingProps } from "./types";
-
-/** 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.
- *  Same idiom as `analytics/analyticsFacade.warnInDev`. */
-const warnInDev = (message: string): void => {
-  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-    console.warn(message);
-  }
-};
+import { warnInDev } from "./utils/warnInDev";
 
 /** Ceiling on the auto-join-key storage read — a hung adapter degrades to no key, never a stuck
  *  loader. Matches the persisted-session read's own ceiling. */
 const AUTO_JOIN_HYDRATION_TIMEOUT_MS = 1_500;
 
+/** The settled result of the auto-join read: a key to inject, or `null` plus WHY the kit declined.
+ *  `timeout` = the adapter never answered; `not-durable` = it answered but did not persist the id,
+ *  so injecting it would mean a different key on every launch. */
+type AutoJoinOutcome = { key: string } | { key: null; reason: "timeout" | "not-durable" };
+
 export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   config,
   theme,
@@ -74,6 +76,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   userContext,
   userId,
   autoJoinKey = true,
+  permissionScreens,
 }) => {
   // The host's own opaque user id (trimmed + capped, NO PII) so onboarding sessions can be
   // reconciled to real users later. `sanitizeUserId` is a pure string transform → the memoized
@@ -109,8 +112,23 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // onboarding session to everything the app reports later, and the prop that carries it is optional
   // and named `userContext` — so forgetting it is the default, and the failure is a silent zero in the
   // `activated` funnel rather than an error. Two real consumers shipped without it.
-  const missingJoinKey =
-    typeof userContextStable?.device_key !== "string" || !userContextStable.device_key.trim();
+  //
+  // A host-supplied key is also RECORDED on the process-wide provenance registry, so a sibling
+  // surface can later ask "does this app own a device id?" — see the K9 warning below. The registry
+  // write is idempotent (same key, same value), so running it from a memo is safe under StrictMode's
+  // double-invoke; it lives here rather than in an effect so the answer is already true for any
+  // surface constructed later in the same tick.
+  const hostJoinIdentity = useMemo(
+    () =>
+      resolveIdentity({
+        value: userContextStable?.device_key,
+        space: "device",
+        source: "host",
+        scope: config.appId,
+      }),
+    [userContextStable, config.appId],
+  );
+  const missingJoinKey = !hostJoinIdentity;
 
   // AUTO-JOIN (0.12.2). When the host supplied no join key, the kit supplies its OWN — the same
   // per-install `device_key` the analytics surfaces auto-mint and persist — so the default wiring
@@ -119,12 +137,21 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //   • `missingJoinKey` — a host-supplied key ALWAYS wins, verbatim, and is never touched.
   //   • `autoJoinKey !== false` — the documented opt-out for a host that genuinely wants an
   //     unlinked onboarding session; opting out restores the pre-0.12.2 behavior exactly.
-  //   • `storage` — WITHOUT persistence `resolveAutoDeviceKey` is process-scoped, so every launch
-  //     would carry a DIFFERENT key. That is worse than no key: the server counts `min_sessions`
-  //     by distinct opens grouped on `device_key`, so a per-launch key corrupts the counter rather
-  //     than leaving it empty. Same reason `useLifecycleEvents` gates its own fallback on storage.
+  //   • `storage` that actually WORKS — without persistence the auto id is process-scoped, so every
+  //     launch would carry a DIFFERENT key. That is worse than no key: the server counts
+  //     `min_sessions` by distinct opens grouped on `device_key`, so a per-launch key corrupts the
+  //     counter rather than leaving it empty, and it inflates distinct-device counts on top. Same
+  //     reason `useLifecycleEvents` gates its own fallback on storage.
   //
-  // It resolves through `hydrateAutoDeviceKey`, never the sync `resolveAutoDeviceKey`: the sync
+  // ⚠️ 0.13.0 (K1): the third condition used to be `Boolean(storage)` — the PRESENCE of the prop,
+  // never the SUCCESS of the write. A REJECTING adapter (a locked / full / permission-denied
+  // AsyncStorage, the most common real breakage) therefore walked the per-launch key in through the
+  // front door: `hydrateAutoDeviceKey` resolves to the in-memory mint on every failure branch, and a
+  // string is a string. The gate now reads `IdentityRecord.durable`, which is `true` ONLY when the id
+  // was adopted from storage or written to it successfully — so a broken adapter lands on exactly the
+  // same "declined, and here is why" path as no adapter at all.
+  //
+  // It resolves through `hydrateDeviceIdentity`, never the sync `resolveAutoDeviceKey`: the sync
   // contract returns the freshly minted id and adopts the persisted one milliseconds later, which
   // is exactly the 0.12.1 H1 defect — the key stamped here must be the one the analytics side
   // stamps, not a fresh mint per launch. The value is therefore awaited BEHIND THE LOADER GATE
@@ -133,33 +160,35 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // provider mounted would recreate the A2A adapter and drop the server-learned `contextId`.
   const autoJoinPossible = Boolean(storage) && autoJoinKey !== false;
   const wantsAutoJoin = missingJoinKey && autoJoinPossible;
-  // `undefined` = the hydration is still in flight (the gate below holds); a string = the key to
-  // inject; `null` = gave up (see the timeout note in the effect) so the gate opens with no key.
-  const [autoJoinValue, setAutoJoinValue] = useState<string | null | undefined>(undefined);
+  // `undefined` = the hydration is still in flight (the gate below holds). Otherwise a settled
+  // outcome: a `key` to inject, or `null` plus the reason the kit declined, which the warning names.
+  const [autoJoinOutcome, setAutoJoinOutcome] = useState<AutoJoinOutcome | undefined>(undefined);
 
   useEffect(() => {
-    if (!wantsAutoJoin || autoJoinValue !== undefined || !storage) return;
+    if (!wantsAutoJoin || autoJoinOutcome !== undefined || !storage) return;
     let cancelled = false;
     // Ceiling on the read, the same discipline as `loadPersistedSession`: a hung storage adapter
     // must degrade to "no auto key", never to a stuck loader over the host's onboarding. Giving up
     // is deliberately NOT "fall back to the synchronous mint" — that key is per-launch, which is
     // the corruption this feature is gated on `storage` to avoid.
     const timer = setTimeout(() => {
-      if (!cancelled) setAutoJoinValue(null);
+      if (!cancelled) setAutoJoinOutcome({ key: null, reason: "timeout" });
     }, AUTO_JOIN_HYDRATION_TIMEOUT_MS);
-    void hydrateAutoDeviceKey({ appId: config.appId, storage }).then((key) => {
+    void hydrateDeviceIdentity({ appId: config.appId, storage }).then((identity) => {
       if (cancelled) return;
       clearTimeout(timer);
-      setAutoJoinValue(key || null);
+      setAutoJoinOutcome(
+        identity?.durable ? { key: identity.value } : { key: null, reason: "not-durable" },
+      );
     });
     return () => {
       cancelled = true;
       clearTimeout(timer);
     };
-  }, [wantsAutoJoin, autoJoinValue, config.appId, storage]);
+  }, [wantsAutoJoin, autoJoinOutcome, config.appId, storage]);
 
-  const injectedJoinKey = wantsAutoJoin && typeof autoJoinValue === "string" ? autoJoinValue : undefined;
-  const autoJoinPending = wantsAutoJoin && autoJoinValue === undefined;
+  const injectedJoinKey = wantsAutoJoin ? (autoJoinOutcome?.key ?? undefined) : undefined;
+  const autoJoinPending = wantsAutoJoin && autoJoinOutcome === undefined;
 
   // What actually goes on the wire: the host's context, with the auto join key merged in ONLY when
   // the host left the slot empty. Every other key the host passed survives untouched, and a host
@@ -172,6 +201,36 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     [userContextStable, injectedJoinKey],
   );
 
+  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS (K5), exactly as `startupUserIdRef`
+  // below freezes the user id, and for the identical reason: `userContext` feeds the `llm` memo, and
+  // wireai-rn recreates its A2A adapter whenever the `llm` identity changes — the adapter ctor resets
+  // `contextId` (`this.contextId = void 0`), so the server-learned session id is dropped.
+  //
+  // THE TEARDOWN THIS PREVENTS: a host that resolves its device key ASYNCHRONOUSLY renders once
+  // without it → auto-join injects `wdev_*` → the host key lands a tick later → `effectiveUserContext`
+  // flips → the memo rebuilds → the adapter is recreated → the user restarts onboarding mid-flow and
+  // the server is left holding an orphaned session. It is not a hypothetical shape: it is the default
+  // shape of any host that reads its device id out of async storage.
+  //
+  // Frozen at gate-open rather than at first render because the auto-join key itself arrives
+  // asynchronously — freezing earlier would freeze `undefined`. The value is carried as a JSON STRING
+  // so it can sit in a dependency array by value; a ref alone would not re-run the memo when it fills.
+  // Client events deliberately keep reading the LIVE `effectiveUserContext`: they are posted one at a
+  // time and carry no adapter, so late host context enriches them at no risk — the same split the
+  // user id already uses (frozen in session-start metadata, live via the `identify` event).
+  const frozenWireContextRef = useRef<string | null>(null);
+  if (!autoJoinPending && frozenWireContextRef.current === null) {
+    frozenWireContextRef.current = effectiveUserContext ? JSON.stringify(effectiveUserContext) : "";
+  }
+  const startupUserContextKey = frozenWireContextRef.current ?? "";
+  const startupUserContext = useMemo<Record<string, string | number | boolean> | undefined>(
+    () =>
+      startupUserContextKey
+        ? (JSON.parse(startupUserContextKey) as Record<string, string | number | boolean>)
+        : undefined,
+    [startupUserContextKey],
+  );
+
   // Dev-only warning (never a throw, never a wire change), once per mount, naming the exact fix.
   // Reconciled with auto-join: it fires only when the gap is still OPEN — injection was impossible
   // (no `storage`), the host opted out, or the read gave up. When auto-join covered the gap the
@@ -184,7 +243,11 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
       : !storage
         ? "it got no `storage` prop, and without persistence its key would be different on every " +
           "launch, which corrupts min_sessions instead of merely leaving the join empty."
-        : "your `storage` adapter did not answer in time.";
+        : autoJoinOutcome?.key === null && autoJoinOutcome.reason === "not-durable"
+          ? "your `storage` adapter answered but could not persist the key (the read or the write " +
+            "failed), so the key would be different on every launch, which corrupts min_sessions " +
+            "instead of merely leaving the join empty. Check the adapter you passed as `storage`."
+          : "your `storage` adapter did not answer in time.";
   useEffect(() => {
     if (!warnMissingJoinKey) return;
     warnInDev(
@@ -198,6 +261,31 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     );
   }, [warnMissingJoinKey, autoJoinReason]);
 
+  // THE SECOND CASE AUTO-JOIN WOULD OTHERWISE SILENCE (K9). 0.12.2 suppressed the missing-join-key
+  // warning whenever injection succeeded, which is right when the host genuinely owns no device id —
+  // and wrong when it owns one and simply forgot it HERE. That host used to get a loud warning and
+  // now gets a silent third id space: its app events under its own key, this onboarding session under
+  // `wdev_*`, and `activated` still zero. Nothing a single mount can see distinguishes the two cases,
+  // which is why the provenance registry exists: any surface constructed with a HOST-supplied device
+  // key records it, so this mount can ask whether the process demonstrably owns one.
+  //
+  // It WARNS rather than declining to inject: declining would leave the onboarding side with no key
+  // at all, which is strictly worse than a self-consistent one. It also does not silently ADOPT the
+  // other surface's key — that would be the kit guessing which of two ids a host meant, on the
+  // strength of construction order, and quietly changing what lands on the wire.
+  const hostKeyElsewhere = missingJoinKey ? hostIdentity("device", config.appId) : undefined;
+  const warnHostKeyElsewhere = Boolean(hostKeyElsewhere) && Boolean(injectedJoinKey);
+  useEffect(() => {
+    if (!warnHostKeyElsewhere) return;
+    warnInDev(
+      "[wireai] <WireOnboarding> got no user_context.device_key, so the kit injected its own — but " +
+        "another surface in this app was constructed WITH a host-supplied device key " +
+        `("${hostKeyElsewhere}"). Your app events carry that id and this onboarding session carries ` +
+        "the kit's, so the two land in disjoint id spaces and the `activated` funnel still reads " +
+        "zero. Pass the SAME id here: userContext={activationJoinContext(deviceKey)}.",
+    );
+  }, [warnHostKeyElsewhere, hostKeyElsewhere]);
+
   // The one case auto-join would otherwise SILENCE and must not: the host hand-wrote
   // `userContext={{ deviceKey }}`. That bucket is not the wire key, so the kit injects its own —
   // but the host demonstrably owns an id, and their app-side events carry THAT one, so the two
@@ -240,6 +328,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     storage ? null : { id: makeSessionId(), resumed: false },
   );
   const storageKey = persistKey ?? sessionStorageKey(config.appId);
+  const permissionsKey = permissionStorageKey(config.appId);
 
   useEffect(() => {
     if (!storage || session) return;
@@ -270,14 +359,63 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // host that does not opt in lands on the byte-for-byte legacy clear-on-complete path.
   const handleComplete = useCallback(
     (result: OnboardingResult) => {
-      if (storage && shouldClearOnComplete(retainSessionOnComplete)) clearPersistedSession(storage, storageKey);
+      if (storage && shouldClearOnComplete(retainSessionOnComplete)) {
+        clearPersistedSession(storage, storageKey);
+        // The permission record is keyed by session id, so a stale one already reads as empty,
+        // this only keeps the adapter from carrying a dead entry forever.
+        clearSettledPermissions(storage, permissionsKey);
+      }
       onComplete(result);
     },
-    [storage, storageKey, retainSessionOnComplete, onComplete],
+    [storage, storageKey, permissionsKey, retainSessionOnComplete, onComplete],
   );
 
   const sessionId = session?.id ?? "";
 
+  // ── Permission-screen memory: "shown once per session", kept true across an app KILL ─────────
+  //
+  // The in-memory guard covers one mount. A resumed session (the whole point of `storage`) is a
+  // NEW mount of the SAME session, so without a persisted record it would re-show a screen the user
+  // already answered, and on the ask path that is a second attempt at a prompt iOS grants once.
+  //
+  // Unlike the auto-join key, this does NOT hold the loader gate: it feeds no `llm` dependency, so
+  // a late arrival cannot recreate the A2A adapter. The flow simply suppresses permission screens
+  // while `permissionsPending` is true, and that window closes long before the first card arrives
+  // (one timeout-capped storage read against a backend round trip).
+  const wantsPermissionMemory = Boolean(storage) && (permissionScreens?.length ?? 0) > 0;
+  const [settledPermissions, setSettledPermissions] = useState<string[] | undefined>(undefined);
+  useEffect(() => {
+    if (!wantsPermissionMemory || !storage || !sessionId || settledPermissions !== undefined) return;
+    let cancelled = false;
+    void loadSettledPermissions(storage, permissionsKey, sessionId).then((ids) => {
+      if (!cancelled) setSettledPermissions(ids);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [wantsPermissionMemory, storage, permissionsKey, sessionId, settledPermissions]);
+
+  // Persist the settled set as it grows. Fire-and-forget: a failed write only costs a re-ask on a
+  // resume, never a broken flow. Without `storage` there is nothing to write to and the
+  // in-memory guard alone carries the once-only contract for this mount.
+  // Mirrored in a ref so the handler can compute the next set WITHOUT doing the storage write
+  // inside a state updater (React invokes updaters twice under StrictMode; a write belongs outside).
+  const settledPermissionsRef = useRef<string[] | undefined>(undefined);
+  settledPermissionsRef.current = settledPermissions;
+  const handlePermissionSettled = useCallback(
+    (id: string) => {
+      const current = settledPermissionsRef.current ?? [];
+      if (current.includes(id)) return;
+      const next = [...current, id];
+      settledPermissionsRef.current = next;
+      setSettledPermissions(next);
+      if (storage && wantsPermissionMemory && sessionId) {
+        saveSettledPermissions(storage, permissionsKey, sessionId, next);
+      }
+    },
+    [storage, wantsPermissionMemory, permissionsKey, sessionId],
+  );
+
   // Session-start snapshot of the bound user id. It seeds the A2A `metadata.userId` so the
   // adapter is built ONCE with whatever id was known at session start. A mid-session userId
   // change must NOT flow through this memo — recreating `llm` recreates the A2A adapter,
@@ -311,7 +449,9 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
         // Device snapshot + host-injected user context ride the session-start metadata so the
         // backend can segment the funnel. Old servers ignore these unknown keys (backward compat).
         device,
-        ...(effectiveUserContext ? { userContext: effectiveUserContext } : {}),
+        // The FROZEN wire context, never the live one — see the freeze note above. A change here
+        // recreates the A2A adapter and drops `contextId`.
+        ...(startupUserContext ? { userContext: startupUserContext } : {}),
         // The session-start user id (from the ref) rides the session-start metadata so the
         // server binds the session to a real user at creation. Reading the ref — not
         // `boundUserId` — keeps this memo off the userId dependency, so a mid-session change
@@ -320,7 +460,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
       },
       timeoutMs: 60_000,
     };
-  }, [config.serverUrl, config.appId, config.apiKey, metadataStable, sessionId, componentsStable, device, effectiveUserContext]);
+  }, [config.serverUrl, config.appId, config.apiKey, metadataStable, sessionId, componentsStable, device, startupUserContext]);
 
   // Where client-reported events are POSTed (`/v1/events`). Same tenant creds as the flow.
   const reportTarget = useMemo<ClientEventTarget>(
@@ -395,6 +535,10 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
             sessionId={sessionId}
             resumed={session.resumed}
             clientContext={clientContext}
+            permissionScreens={permissionScreens}
+            settledPermissions={settledPermissions}
+            permissionsPending={wantsPermissionMemory && settledPermissions === undefined}
+            onPermissionSettled={handlePermissionSettled}
           />
         </WireAIProvider>
         </IconRegistryProvider>

package/src/activation/wireActivation.ts

@@ -29,7 +29,8 @@ import {
   type ClientEventTarget,
 } from "../analytics/reportClientEvent";
 import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
-import { resolveUserContext, type WireUserContext } from "../context/userContext";
+import { cleanString, resolveUserContext, type WireUserContext } from "../context/userContext";
+import { resolveIdentity } from "../identity/identityRecord";
 import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import {
@@ -38,12 +39,8 @@ import {
   subscribeActivationRevalidation,
 } from "./revalidation";
 
-/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate. */
-const clean = (value: unknown): string | undefined => {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-};
+/** The shared trim helper (was a byte-identical private copy named `clean` in this file). */
+const clean = cleanString;
 
 /**
  * Tenant transport + context inputs for {@link createWireActivation}. `serverUrl`/`apiKey` are the
@@ -109,6 +106,15 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   // `createAnalytics` instance carry the SAME `device_key` for the same install. Minting locally here
   // gave one install two auto ids — see the registry note in context/deviceId.ts.
   const explicitDeviceKey = clean(config.deviceKey) ?? clean(config.userContext?.deviceKey);
+  // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
+  // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
+  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it on this path.
+  resolveIdentity({
+    value: explicitDeviceKey,
+    space: "device",
+    source: "host",
+    scope: config.appId,
+  });
   const autoDeviceKeyOptions: ResolveAutoDeviceKeyOptions = {
     appId: config.appId,
     // An explicit key opts out of minting AND persisting (unchanged contract).

package/src/analytics/analyticsEvent.ts

@@ -15,6 +15,11 @@
  * `onEvent`) — the app logs it explicitly on `onComplete` using the constant below, so the
  * funnel name stays canonical.
  */
+import {
+  permissionEventName,
+  permissionEventProps,
+  type WirePermissionEventName,
+} from "../permissions/permissionEvents";
 import type { OnboardingEvent } from "../types";
 
 export const WIRE_ONBOARDING_EVENTS = {
@@ -33,7 +38,12 @@ export type WireOnboardingEventName =
   (typeof WIRE_ONBOARDING_EVENTS)[keyof typeof WIRE_ONBOARDING_EVENTS];
 
 export type AnalyticsEvent = {
-  name: WireOnboardingEventName;
+  /**
+   * A permission screen maps to its own canonical `wire_permission_*` name rather than to an
+   * onboarding one: it is a distinct funnel (see `permissions/permissionEvents.ts`), and folding it
+   * into `wire_onboarding_turn` would make every permission rate unreadable.
+   */
+  name: WireOnboardingEventName | WirePermissionEventName;
   params?: Record<string, unknown>;
 };
 
@@ -61,6 +71,11 @@ export const toAnalyticsEvent = (event: OnboardingEvent): AnalyticsEvent => {
       };
     case "fallback":
       return { name: WIRE_ONBOARDING_EVENTS.fallback, params: { reason: event.reason } };
+    case "permission":
+      return {
+        name: permissionEventName(event.stage),
+        params: permissionEventProps(event.permission, event.status),
+      };
     default: {
       const _exhaustive: never = event;
       return _exhaustive;