@wireai/activation 0.13.0 → 0.13.3

package/dist/{types-CNUqMK0D.d.mts → types-l2tfg23P.d.mts}

@@ -2,6 +2,46 @@ import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
 import { C as CoachmarkStorage } from './types-BcmagF6K.mjs';
 import { W as WireFeatures, a as WireFeaturesConfig } from './types-CKFhyrMu.mjs';
 
+/**
+ * submitResult — the ONE delivery verdict every user-payload POST in this kit reports back.
+ *
+ * WHY IT IS SHARED, AND WHY IT IS NOT A BOOLEAN. Two surfaces post a payload the user typed —
+ * `submitReview` (`reviews/transport.ts`) and `submitQuestionnaireResponse`
+ * (`questionnaire/transport.ts`) — and NEITHER has a persisted queue behind it (unlike
+ * `analytics/eventQueue`, with its `maxSize`/`maxRetries`/backoff). Both sit behind a permanent
+ * once-gate: the host writes `wire_review_<id>_seen` / `wire_questionnaire_<id>_<ver>_seen` when the
+ * gate resolves, so a payload that dies in the socket is lost AND the user is never asked again.
+ * Reading the fate of the request is the only thing that lets a caller keep an undelivered payload
+ * recoverable, so the two surfaces must answer the same question in the same words.
+ *
+ *   • `accepted` — the server answered 2xx. Stored.
+ *   • `rejected` — the server ANSWERED, non-2xx. It was reached; it either stored the payload and
+ *                  lost the ack (a gateway 502 after the write commits) or deliberately refused it.
+ *                  Either way the server owns the outcome and a re-post risks a SECOND row.
+ *   • `unsent`   — nothing came back at all: no target, a missing/throwing `fetch`, a rejected
+ *                  request. **This is the ONLY outcome a caller may retry on.**
+ *
+ * ── WHY THREE VALUES AND NOT TWO (pinned here so the defect cannot move surface) ───────────────
+ *
+ * `submitReview` was a boolean for exactly one unpublished release, and the boolean WAS the bug.
+ * `false` meant both "nothing reached the server" and "the server answered non-2xx", and the caller
+ * treats `false` as "still owed" and re-posts. But the server mints its own row id
+ * (`create_review` / `_new_id()`), and neither `CreateReviewRequest` nor the questionnaire response
+ * body carries a client id, so there is NO idempotency key on the wire: a 502 returned AFTER the
+ * insert commits means the re-post writes a SECOND row. A response of any status proves the server
+ * was reached, and that is a different question from whether it liked the payload.
+ *
+ * ── THE RESIDUAL, STATED HONESTLY ─────────────────────────────────────────────────────────────
+ *
+ * `unsent` is not proof the server never got it. A connection dropped after the request was written
+ * — or after the row committed — surfaces as a thrown/rejected `fetch`, exactly like an offline
+ * device. Retrying only on `unsent` is therefore SAFER, not SAFE. Closing that window needs a
+ * CLIENT-MINTED IDEMPOTENCY KEY the server upserts on, which is a server change and not something
+ * the kit can fake. Until it exists, prefer losing a row over inventing one: a lost detractor is a
+ * gap in the data, a duplicated one is a lie in the data.
+ */
+type SubmitResult = "accepted" | "rejected" | "unsent";
+
 /**
  * The firing verdict — the SAME contract on both sides of the seam. `decideReview`
  * turns local rules into one of these; a server `{fire, reason}` (from
@@ -161,4 +201,4 @@ interface ReviewGateController {
     markResolved: () => void;
 }
 
-export type { ReviewGateProps as R, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewDecisionResponse as g, ReviewGateEvent as h, ReviewGateEventName as i, ReviewSubmission as j, ReviewTarget as k };
+export type { ReviewGateProps as R, SubmitResult as S, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewDecisionResponse as g, ReviewGateEvent as h, ReviewGateEventName as i, ReviewSubmission as j, ReviewTarget as k };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.13.0",
+  "version": "0.13.3",
   "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>",
@@ -137,8 +137,11 @@
   "scripts": {
     "build": "tsup",
     "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm run test:canary",
     "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
     "test": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"src/**/*.test.ts\" \"test/canary/**/*.test.tsx\"",
+    "test:canary": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"test/canary/**/*.test.tsx\"",
     "pack:tarball": "npm pack"
   },
   "peerDependencies": {

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);
@@ -145,7 +179,17 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // Trailing-edge debounce timer for prefetch-on-select (see previewOnSelect below).
   const previewTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const started = useRef(false);
+  // The attempt generation. It lives in STATE, not in a ref, and both the auto-start effect and
+  // the startup watchdog list it in their deps — a retry has to genuinely RE-ARM both, and a ref
+  // cannot re-trigger an effect. Nothing else in those deps moves on a retry: `sendMessage` is
+  // memoized in wireai-rn on [registry, provider, model], and `lastCard` is still `undefined`
+  // because no card ever arrived. Without the generation the kickoff is never re-sent, `timedOut`
+  // can never become true a second time, and the retry budget can never be spent — which leaves a
+  // backend that never answers sitting on the loader forever.
+  const [runId, setRunId] = useState(0);
+  // The generation whose kickoff has already been sent. -1 = nothing sent yet (so the very first
+  // run can be told apart from a retry, which must NOT re-fire `started`/`resumed`).
+  const startedRunRef = useRef(-1);
   const finished = useRef(false);
   const errored = useRef(false);
   const attempts = useRef(0);
@@ -156,6 +200,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"),
@@ -171,33 +220,50 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const progress = useMemo(() => readProgress(lastCard?.response), [lastCard]);
 
   // 1. Auto-start: the backend treats the first inbound message as "begin".
-  //    On a RESUMED session (persisted id restored after an app kill) the kickoff is
-  //    the skip sentinel instead: the server has this session mid-flow with a pending
-  //    question, and would record `startMessage`'s literal text as its ANSWER — the
-  //    sentinel advances one card recording nothing (a `screen_skipped`). On a session
-  //    the server no longer knows (restart/expiry), the sentinel degrades cleanly to a
-  //    normal kickoff under the same id. Retries re-send the same kickoff.
+  //    ONLY the very first attempt of a fresh session sends `startMessage`. Every other kickoff
+  //    — a RESUMED session (persisted id restored after an app kill) and every RETRY — sends the
+  //    skip sentinel, because both can reach a server that already has a question PENDING on this
+  //    session, and a non-empty message arriving against a pending question is recorded as that
+  //    question's ANSWER (server engine dispatch: `if user_message and pending and not
+  //    _stop_requested(...)` appends `{key, question, answer}` to `session["answers"]`). For a
+  //    retry that is not hypothetical: the watchdog fires at `startTimeoutMs` while a slow LLM is
+  //    still generating, so the server can genuinely hold card 1 pending when the retry lands, and
+  //    the user's first onboarding answer becomes the literal kickoff text — silently.
+  //    THE COST, stated plainly: when the server DID have card 1 pending, the sentinel SKIPS that
+  //    card — the user loses one question and the server logs a `screen_skipped`. Deliberate. A
+  //    skipped question is visible in the funnel and recorded as nothing; a kickoff string stored
+  //    as the user's first answer is invisible and poisons the data the product is built on.
+  //    When the server has no pending (restart/expiry, or a retry whose predecessor never landed)
+  //    the sentinel is zeroed and falls through — it degrades cleanly to a normal kickoff under
+  //    the same id, which is what makes it safe to send on an attempt that may be either.
   useEffect(() => {
-    if (started.current) return;
-    started.current = true;
-    sendMessage(resumed ? SKIP_ONE_SENTINEL : startMessage);
+    if (startedRunRef.current === runId) return;
+    const isFirstRun = startedRunRef.current < 0;
+    startedRunRef.current = runId;
+    sendMessage(isFirstRun && !resumed ? startMessage : SKIP_ONE_SENTINEL);
+    // Only the FIRST run is a session start. A retry re-kicks the flow (with the sentinel) but
+    // must not re-fire `started`/`resumed`, or every host funnel double-counts the session; the
+    // retry itself is already surfaced as a `retry` event by the error effect below.
+    if (!isFirstRun) return;
     // Surface the session id (the A2A contextId) on the start event so a host can capture it
     // and bind a user AFTER the flow via `identifyOnboarding({ contextId })` — completion clears
     // the persisted session, so the in-flight event is the reliable post-flow handle. sessionId
-    // is stable for the whole session (minted before this subtree mounts), so this stays mount-once.
+    // is stable for the whole session (minted before this subtree mounts), so this stays once
+    // per session.
     onEventRef.current?.(
       resumed
         ? { type: "resumed", contextId: sessionId }
         : { type: "started", contextId: sessionId },
     );
-  }, [sendMessage, startMessage, resumed, sessionId]);
+  }, [sendMessage, startMessage, resumed, sessionId, runId]);
 
-  // 2. Startup watchdog.
+  // 2. Startup watchdog. `runId` is load-bearing in these deps: after a retry there is still no
+  //    card, so `lastCard` does not change and nothing else would re-arm the timer.
   useEffect(() => {
     if (lastCard) return;
     const timer = setTimeout(() => setTimedOut(true), startTimeoutMs);
     return () => clearTimeout(timer);
-  }, [lastCard, startTimeoutMs]);
+  }, [lastCard, startTimeoutMs, runId]);
 
   // A new card arrived → clear any prior inline validation error + emit a turn event.
   useEffect(() => {
@@ -248,8 +314,10 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // Does NOT clear the attempt counter or the degraded flag — the caller decides that.
   const restartThread = useCallback(() => {
     setTimedOut(false);
-    started.current = false;
     errored.current = false;
+    // Bumping the generation IN STATE is what actually re-runs the kickoff effect and re-arms the
+    // watchdog. Flipping a ref here would re-trigger neither.
+    setRunId((n) => n + 1);
     reset();
   }, [reset]);
 
@@ -324,6 +392,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
@@ -438,6 +551,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

@@ -34,6 +34,12 @@ import {
   DEFAULT_SESSION_TTL_MS,
   type LoadedSession,
 } from "./session/persistedSession";
+import {
+  clearSettledPermissions,
+  loadSettledPermissions,
+  permissionStorageKey,
+  saveSettledPermissions,
+} from "./permissions/permissionMemory";
 import type { OnboardingResult, WireOnboardingProps } from "./types";
 import { warnInDev } from "./utils/warnInDev";
 
@@ -70,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
@@ -107,7 +114,8 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // `activated` funnel rather than an error. Two real consumers shipped without it.
   //
   // 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
+  // surface can later ask "does this app own a device id?" — see the third-id-space 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.
@@ -136,7 +144,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //     counter rather than leaving it empty, and it inflates distinct-device counts on top. Same
   //     reason `useLifecycleEvents` gates its own fallback on storage.
   //
-  // ⚠️ 0.13.0 (K1): the third condition used to be `Boolean(storage)` — the PRESENCE of the prop,
+  // ⚠️ 0.13.0: 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
@@ -146,8 +154,8 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //
   // 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
+  // is exactly the split-identity defect 0.12.1 shipped — the key stamped here must be the one the
+  // analytics side stamps, not a fresh mint per launch. It is therefore awaited BEHIND THE LOADER GATE
   // below (the same gate the persisted-session read already holds, and it is only ever open when
   // `storage` is present anyway), because `userContext` feeds the `llm` memo: swapping it after the
   // provider mounted would recreate the A2A adapter and drop the server-learned `contextId`.
@@ -194,7 +202,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     [userContextStable, injectedJoinKey],
   );
 
-  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS (K5), exactly as `startupUserIdRef`
+  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS, 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.
@@ -254,7 +262,7 @@ 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
+  // THE SECOND CASE AUTO-JOIN WOULD OTHERWISE SILENCE. 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
@@ -321,6 +329,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;
@@ -351,14 +360,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,
@@ -478,6 +536,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

@@ -5,8 +5,8 @@
  * because the kit didn't own them — an awaitable action POST (`wireTrackActionAwait`), its OWN
  * per-open session id (`getWireSessionId`, minted because the kit's `getCurrentSessionId` desynced
  * cross-bundle — defect B), and an await-then-bump revalidation dance (`bumpActivationDecision`).
- * Defect B is fixed (PR #48: `getCurrentSessionId` is a `globalThis` singleton, reliable under
- * `dist`), so the kit can now own all three behind one thin surface:
+ * Defect B is fixed — `getCurrentSessionId` is now a `globalThis` singleton, reliable under
+ * `dist` — so the kit can own all three behind one thin surface:
  *
  *   const wire = createWireActivation({ serverUrl, apiKey });   // or useWireActivation(...)
  *   await wire.track("journal_done");                            // awaitable POST + auto-revalidate
@@ -108,7 +108,7 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   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.
+  // and forgot it here" (the silent third id space). Recording only; nothing reads it on this path.
   resolveIdentity({
     value: explicitDeviceKey,
     space: "device",

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;

package/src/analytics/analyticsFacade.ts

@@ -198,7 +198,7 @@ export const createAnalytics = (
       : undefined;
   // 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 here.
+  // and forgot it here" (the silent third id space). Recording only; nothing reads it here.
   resolveIdentity({
     value: hostDeviceKeyAtInit,
     space: "device",
@@ -333,7 +333,7 @@ export const createAnalytics = (
 
   const screen = (name: string, props?: AnalyticsProps): void => {
     if (!name) return;
-    // Reuse the K6 screen event shape (question_key='screen'); route through the queue for offline-first.
+    // Reuse the existing screen event shape (question_key='screen'); route through the queue for offline-first.
     const meta = { screen: name, ...(props ?? {}) };
     const clientEvent: ClientEvent = {
       event_type: "app_event",