@agent-native/core 0.131.7 → 0.132.0

package/corpus/core/src/cli/create.ts

@@ -50,6 +50,18 @@ const FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES = [
   "*/.claude/skills",
 ];
 const localPackageTarballs = new Map<string, string>();
+/** VCS/editor files that don't count as "not empty" for an in-place scaffold. */
+const IN_PLACE_ALLOWLIST = new Set([
+  ".git",
+  ".gitignore",
+  ".gitattributes",
+  ".DS_Store",
+  ".idea",
+  ".vscode",
+  "LICENSE",
+  "README.md",
+  "Thumbs.db",
+]);
 
 /**
  * Tagged error for input that fails CLI-level validation (repo names, app
@@ -110,6 +122,11 @@ export interface CreateAppOptions {
    * unconditional workspace scaffold.
    */
   forceWorkspace?: boolean;
+  /**
+   * Internal: scaffold into the current directory instead of a new subfolder.
+   * Set when the name argument is `.`/`./` (see `createApp`).
+   */
+  inPlace?: boolean;
 }
 
 /**
@@ -127,6 +144,13 @@ export async function createApp(
 ): Promise<void> {
   const clack = await import("@clack/prompts");
 
+  // `create .` (or `./`) means "scaffold into the current folder" — derive the
+  // project name from the folder's basename, like create-react-app / npm init.
+  if (name === "." || name === "./") {
+    name = path.basename(process.cwd());
+    opts = { ...opts, inPlace: true };
+  }
+
   // Reject an invalid provided name before any interactive prompt so bad input
   // fails fast instead of blocking on the start-shape picker below.
   if (name !== undefined) {
@@ -335,6 +359,44 @@ function assertValidProjectName(
     process.exit(1);
   }
 }
+/**
+ * Resolve where a scaffold writes and guard the target. A named project writes
+ * to a new sibling subfolder that must not already exist; `create .` writes
+ * into the current directory, which must be empty apart from benign VCS/editor
+ * files (a pre-existing repo is allowed).
+ *
+ * For an in-place scaffold we do NOT return the current directory: we build
+ * into a private staging directory and `finalizeScaffold` copies the result
+ * in afterward. Staging keeps the whole scaffold atomic — a mid-scaffold
+ * failure's cleanup can only ever delete the staging dir, never the user's
+ * current directory (including its `.git`).
+ */
+function resolveScaffoldTarget(
+  name: string,
+  inPlace: boolean | undefined,
+  clack: typeof import("@clack/prompts"),
+): string {
+  if (inPlace) {
+    const conflicting = fs
+      .readdirSync(process.cwd())
+      .filter((entry) => !IN_PLACE_ALLOWLIST.has(entry));
+    if (conflicting.length > 0) {
+      const shown = conflicting.slice(0, 3).join(", ");
+      const more = conflicting.length > 3 ? ", …" : "";
+      clack.cancel(
+        `Current directory is not empty (${shown}${more}). Scaffold into an empty folder, or run \`create <name>\` to make a new one.`,
+      );
+      process.exit(1);
+    }
+    return fs.mkdtempSync(path.join(os.tmpdir(), "agent-native-create-"));
+  }
+  const targetDir = path.resolve(process.cwd(), name);
+  if (fs.existsSync(targetDir)) {
+    clack.cancel(`Directory "${name}" already exists.`);
+    process.exit(1);
+  }
+  return targetDir;
+}
 
 /* ─────────────────────────────────────────────────────────────────────────
  * Workspace creation (new default)
@@ -378,11 +440,7 @@ async function createWorkspaceInteractive(
         });
   const templates = ["dispatch", ...optionalPicks];
 
-  const targetDir = path.resolve(process.cwd(), name);
-  if (fs.existsSync(targetDir)) {
-    clack.cancel(`Directory "${name}" already exists.`);
-    process.exit(1);
-  }
+  const targetDir = resolveScaffoldTarget(name, opts?.inPlace, clack);
 
   const s = clack.spinner();
   for (const template of templates) {
@@ -482,13 +540,15 @@ async function createWorkspaceInteractive(
   } catch (err: any) {
     s.stop("Failed to scaffold workspace.");
     // Remove the partially-scaffolded workspace so a retry of `agent-native
-    // create <name>` doesn't trip the "Directory already exists" guard.
+    // create <name>` doesn't trip the "Directory already exists" guard. For an
+    // in-place scaffold `targetDir` is the private staging dir, so this never
+    // touches the user's current directory.
     cleanupOnFailure(targetDir);
     clack.cancel(err?.message ?? String(err));
     process.exit(1);
   }
 
-  tryGitInit(targetDir);
+  finalizeScaffold(targetDir, opts?.inPlace);
 
   // Show the user the tree we just built so the workspace/app distinction is
   // visible, not just described. First-time users routinely expect their
@@ -845,11 +905,7 @@ async function createStandaloneApp(
 
   name = await promptNameIfMissing(name, clack, "app", "my-app");
 
-  const targetDir = path.resolve(process.cwd(), name);
-  if (fs.existsSync(targetDir)) {
-    clack.cancel(`Directory "${name}" already exists.`);
-    process.exit(1);
-  }
+  const targetDir = resolveScaffoldTarget(name, opts?.inPlace, clack);
 
   // Standalone is single-select — pick one template.
   let template =
@@ -889,12 +945,14 @@ async function createStandaloneApp(
     s.stop("App created!");
   } catch (err: any) {
     s.stop("Failed to create app.");
+    // `targetDir` is the private staging dir for an in-place scaffold, so this
+    // only ever removes the staging copy, never the user's current directory.
     cleanupOnFailure(targetDir);
     clack.cancel(err?.message ?? String(err));
     process.exit(1);
   }
 
-  tryGitInit(targetDir);
+  finalizeScaffold(targetDir, opts?.inPlace);
 
   if (template === "headless") {
     clack.outro(
@@ -954,6 +1012,35 @@ function cleanupOnFailure(targetDir: string): void {
   }
 }
 
+/**
+ * Land a finished scaffold in its final home and initialize git. A named
+ * scaffold is already in place, so this only inits git. An in-place scaffold
+ * (`create .`) was built in `scaffoldDir` (a staging dir); copy only the files
+ * that don't already exist into the current directory so pre-existing files
+ * (`.git`, `README.md`, `.gitignore`, editor configs) are preserved, then drop
+ * the staging dir. Git init/commit is skipped when the current directory is
+ * already a repo so we never write an unexpected commit into the user's
+ * history.
+ */
+function finalizeScaffold(scaffoldDir: string, inPlace?: boolean): void {
+  if (!inPlace) {
+    tryGitInitUnlessRepo(scaffoldDir);
+    return;
+  }
+  const dest = process.cwd();
+  try {
+    copyDir(scaffoldDir, dest, undefined, { skipExisting: true });
+  } finally {
+    cleanupOnFailure(scaffoldDir);
+  }
+  tryGitInitUnlessRepo(dest);
+}
+
+function tryGitInitUnlessRepo(dir: string): void {
+  if (fs.existsSync(path.join(dir, ".git"))) return;
+  tryGitInit(dir);
+}
+
 /* ─────────────────────────────────────────────────────────────────────────
  * Shared scaffolding helpers
  * ───────────────────────────────────────────────────────────────────────── */
@@ -3399,13 +3486,25 @@ function replacePlaceholders(
   }
 }
 
-function copyDir(src: string, dest: string, root?: string): void {
+function copyDir(
+  src: string,
+  dest: string,
+  root?: string,
+  opts?: { skipExisting?: boolean },
+): void {
   const resolvedRoot = root ?? path.resolve(src);
+  const skipExisting = opts?.skipExisting ?? false;
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const srcPath = path.join(src, entry.name);
     if (shouldSkipScaffoldEntry(entry.name, srcPath)) continue;
     const destPath = path.join(dest, entry.name);
+    // Preserve anything already at the destination (in-place scaffold merges
+    // into a directory the user may already own). Directories still recurse so
+    // new files land inside a pre-existing folder.
+    if (skipExisting && !entry.isDirectory() && fs.existsSync(destPath)) {
+      continue;
+    }
     if (entry.isSymbolicLink()) {
       const target = fs.readlinkSync(srcPath);
       const resolvedTarget = path.resolve(path.dirname(srcPath), target);
@@ -3415,7 +3514,7 @@ function copyDir(src: string, dest: string, root?: string): void {
         try {
           const stat = fs.statSync(srcPath);
           if (stat.isDirectory()) {
-            copyDir(srcPath, destPath, resolvedRoot);
+            copyDir(srcPath, destPath, resolvedRoot, opts);
           } else {
             fs.copyFileSync(srcPath, destPath);
           }
@@ -3424,7 +3523,7 @@ function copyDir(src: string, dest: string, root?: string): void {
         }
       }
     } else if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, resolvedRoot);
+      copyDir(srcPath, destPath, resolvedRoot, opts);
     } else {
       fs.copyFileSync(srcPath, destPath);
     }

package/corpus/core/src/client/AgentPanel.tsx

@@ -88,6 +88,7 @@ import {
 } from "./agent-sidebar-state.js";
 import { trackEvent } from "./analytics.js";
 import { agentNativePath, appPath } from "./api-path.js";
+import { readClientAppState } from "./application-state.js";
 import { assistantUiRecoverableRenderErrorKind } from "./assistant-ui-recovery.js";
 import type { AssistantChatProps } from "./AssistantChat.js";
 import { shouldParentFrameOwnAgentPanel } from "./builder-frame.js";
@@ -2356,13 +2357,7 @@ function URLSync({ browserTabId }: { browserTabId?: string }) {
     queryKey: setUrlQueryKey,
     queryFn: async () => {
       const read = async (key: string) => {
-        const res = await fetch(
-          agentNativePath(`/_agent-native/application-state/${key}`),
-        );
-        if (!res.ok || res.status === 204) return null;
-        const text = await res.text();
-        if (!text) return null;
-        const data = JSON.parse(text);
+        const data = await readClientAppState<Record<string, unknown>>(key);
         return data ? { key, command: data } : null;
       };
       try {

package/corpus/core/src/client/AssistantChat.tsx

@@ -3421,7 +3421,11 @@ const AssistantChatInner = forwardRef<
           }
           window.dispatchEvent(
             new CustomEvent("agentNative.chatRunning", {
-              detail: { isRunning: false, tabId: tabId || threadId },
+              detail: {
+                isRunning: false,
+                tabId: tabId || threadId,
+                reason: "failed",
+              },
             }),
           );
           return;
@@ -4510,7 +4514,11 @@ const AssistantChatInner = forwardRef<
       if (typeof window !== "undefined") {
         window.dispatchEvent(
           new CustomEvent("agentNative.chatRunning", {
-            detail: { isRunning: false, tabId: tabId || threadId },
+            detail: {
+              isRunning: false,
+              tabId: tabId || threadId,
+              reason: "stopped",
+            },
           }),
         );
       }

package/corpus/core/src/client/MultiTabAssistantChat.tsx

@@ -2610,6 +2610,9 @@ export function MultiTabAssistantChat({
                   hasInFlightWork={() =>
                     chatRefs.current.get(tabId)?.hasInFlightWork() ?? false
                   }
+                  isAwaitingResponse={() =>
+                    chatRefs.current.get(tabId)?.isRunning() ?? false
+                  }
                   onRetry={() => {
                     const handle = chatRefs.current.get(tabId);
                     handle?.sendRecoveryMessage(

package/corpus/core/src/client/RunStuckBanner.tsx

@@ -50,6 +50,16 @@ export interface RunStuckBannerProps {
    * render; omit to keep the unconditional Retry/Cancel behavior.
    */
   hasInFlightWork?: () => boolean;
+  /**
+   * Returns true when this chat is actually waiting on a reply - typically
+   * backed by `chatHandle.isRunning()`. "Stuck" is a claim about THIS client,
+   * but the run row is the server's; a turn that finished normally can leave a
+   * row in `running` (terminal marking is best-effort, and the stale-run reaper
+   * runs later). Without this gate an idle, completed chat shows the warning
+   * and auto-retry re-prompts a thread the user considers done. Checked fresh
+   * on every render; omit to keep the unconditional behavior.
+   */
+  isAwaitingResponse?: () => boolean;
   /**
    * Called whenever the stuck state transitions. Useful for surfacing
    * observability events (Sentry, PostHog) at the call site.
@@ -170,6 +180,7 @@ export function RunStuckBanner({
   autoRetry = false,
   autoRetryOwnerId,
   hasInFlightWork,
+  isAwaitingResponse,
   className,
 }: RunStuckBannerProps) {
   const state = useRunStuckDetection({
@@ -180,6 +191,11 @@ export function RunStuckBanner({
   });
   const abortRun = useAbortRun(apiUrl);
   const [busy, setBusy] = useState<BusyState>({ type: "none" });
+  // "An automatic attempt was made for this run" is a different fact from
+  // "the controls are locked while a request is in flight". Sharing one flag
+  // for both would force the buttons to stay disabled just to keep the
+  // message on screen.
+  const [autoRetriedRunId, setAutoRetriedRunId] = useState<string | null>(null);
   const autoRetriedRunIdsRef = useRef<Set<string>>(new Set());
   const generatedOwnerIdRef = useRef<string | null>(null);
   if (!generatedOwnerIdRef.current) {
@@ -204,6 +220,7 @@ export function RunStuckBanner({
   // either signal says so.
   const inFlightWork =
     state.hasInFlightWork === true || (hasInFlightWork?.() ?? false);
+  const awaitingResponse = isAwaitingResponse?.() ?? true;
   // Server-continued runs are recovered by the SERVER (chained continuation
   // chunks + lost-handoff sweep); an automatic client abort would kill a live
   // server-chained run. Auto-retry is therefore disabled unconditionally for
@@ -261,6 +278,9 @@ export function RunStuckBanner({
       // A live tool/A2A call in flight — never auto-abort real work (see
       // `inFlightWork` comment above).
       inFlightWork ||
+      // Nothing is waiting on this run here; re-prompting would restart a
+      // thread the user already considers finished.
+      !awaitingResponse ||
       !state.isStuck ||
       !state.runId ||
       busy.type !== "none" ||
@@ -274,21 +294,22 @@ export function RunStuckBanner({
       autoRetriedRunIdsRef.current.add(runId);
       if (!claimed) return;
       setBusy({ type: "retry", runId });
+      setAutoRetriedRunId(runId);
       trackEvent("agent_chat_stuck_auto_retry", {
         runId,
         threadId: threadId ?? null,
         stuckSinceMs: state.stuckSinceMs ?? null,
       });
       void abortRun(runId, "auto_stuck_retry").then((aborted) => {
-        if (aborted) {
-          onRetry?.(aborted);
-          return;
-        }
+        // Release the controls on both outcomes. If the abort does not move
+        // the row off `running`, polling may never observe a new run id. The
+        // automatic-attempt set still prevents re-entry.
         setBusy((current) =>
           current.type !== "none" && current.runId === runId
             ? { type: "none" }
             : current,
         );
+        if (aborted) onRetry?.(aborted);
       });
     });
   }, [
@@ -304,6 +325,7 @@ export function RunStuckBanner({
     state.runId,
     state.stuckSinceMs,
     threadId,
+    awaitingResponse,
   ]);
 
   // A stale progress timestamp is not actionable while the server is still
@@ -314,7 +336,8 @@ export function RunStuckBanner({
     !state.isStuck ||
     !state.runId ||
     backgroundWorkerStillAlive ||
-    inFlightWork
+    inFlightWork ||
+    !awaitingResponse
   ) {
     return null;
   }
@@ -380,7 +403,7 @@ export function RunStuckBanner({
             No progress
             {stuckSeconds != null ? ` for ${stuckSeconds}s` : ""}. The agent may
             have hit a server timeout or lost its connection.
-            {autoRetry && busyType === "retry"
+            {autoRetry && autoRetriedRunId === state.runId
               ? " Retrying automatically now."
               : ""}
           </span>

package/corpus/core/src/client/agent-chat.ts

@@ -9,6 +9,7 @@
 
 import type { ReasoningEffort } from "../shared/reasoning-effort.js";
 import { agentNativePath } from "./api-path.js";
+import { readClientAppState } from "./application-state.js";
 import {
   isInBuilderFrame,
   isTrustedBuilderMessage,
@@ -598,15 +599,9 @@ export async function refreshAgentChatContext(): Promise<AgentChatContextState>
     return agentChatContextState;
   }
   try {
-    const res = await fetch(
-      agentNativePath(
-        `/_agent-native/application-state/${AGENT_CHAT_CONTEXT_STATE_KEY}`,
-      ),
-    );
-    if (!res.ok || res.status === 204) return agentChatContextState;
-    const text = await res.text();
-    if (!text) return agentChatContextState;
-    const state = normalizeAgentChatContextState(JSON.parse(text));
+    const raw = await readClientAppState(AGENT_CHAT_CONTEXT_STATE_KEY);
+    if (raw === null) return agentChatContextState;
+    const state = normalizeAgentChatContextState(raw);
     if (!state) return agentChatContextState;
     return publishAgentChatContextItems(state.items, {
       persist: false,

package/corpus/core/src/client/application-state.ts

@@ -93,19 +93,117 @@ function jsonBody(value: unknown): string {
   return body;
 }
 
+/**
+ * Result of a batched read. `values` holds only the keys the server has a row
+ * for; every other requested key is in `missing`. A key stored with a `null`
+ * value lands in `values` with `null` and NOT in `missing` — that is how
+ * "never written" stays distinguishable from "written as null/empty".
+ */
+export interface ClientAppStateBatch {
+  values: Record<string, unknown>;
+  missing: string[];
+}
+
+/** Server caps a batch at 100 keys; stay under it when splitting. */
+const MAX_BATCH_KEYS = 100;
+
+export async function readClientAppStateMany(
+  keys: readonly string[],
+  options: ClientAppStateReadOptions = {},
+): Promise<ClientAppStateBatch> {
+  const unique = [...new Set(keys)];
+  for (const key of unique) appStateUrl(key); // validates the key shape
+  if (unique.length === 0) return { values: {}, missing: [] };
+
+  const merged: ClientAppStateBatch = { values: {}, missing: [] };
+  for (let i = 0; i < unique.length; i += MAX_BATCH_KEYS) {
+    const chunk = unique.slice(i, i + MAX_BATCH_KEYS);
+    const url = `${agentNativePath("/_agent-native/application-state")}?keys=${chunk
+      .map(encodeURIComponent)
+      .join(",")}`;
+    const response = await fetch(url, {
+      method: "GET",
+      cache: "no-store",
+      signal: options.signal,
+    });
+    const batch = await parseAppStateResponse<ClientAppStateBatch | null>(
+      response,
+      `Read application state [${chunk.join(", ")}]`,
+    );
+    if (!batch || typeof batch !== "object" || !batch.values) {
+      throw new Error(
+        `Read application state [${chunk.join(", ")}] returned an unexpected payload.`,
+      );
+    }
+    Object.assign(merged.values, batch.values);
+    merged.missing.push(...(batch.missing ?? []));
+  }
+  return merged;
+}
+
+// Reads issued in the same tick are coalesced into one batched request. Every
+// mounted composer, question card and suggestion hook reads its own key on
+// mount, which used to be one HTTP request (and one full identity resolution)
+// each — ~55 on an analytics dashboard load.
+let pendingBatch:
+  | { keys: Set<string>; promise: Promise<ClientAppStateBatch> }
+  | undefined;
+
+function scheduleBatchedRead(key: string): Promise<ClientAppStateBatch> {
+  if (pendingBatch) {
+    pendingBatch.keys.add(key);
+    return pendingBatch.promise;
+  }
+  const keys = new Set([key]);
+  const promise = new Promise<ClientAppStateBatch>((resolve, reject) => {
+    setTimeout(() => {
+      pendingBatch = undefined;
+      readClientAppStateMany([...keys]).then(resolve, reject);
+    }, 0);
+  });
+  pendingBatch = { keys, promise };
+  return promise;
+}
+
+function awaitWithAbort<T>(
+  promise: Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> {
+  if (!signal) return promise;
+  const abortReason = () =>
+    signal.reason ?? new Error("The operation was aborted");
+  if (signal.aborted) return Promise.reject(abortReason());
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(abortReason());
+    };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        cleanup();
+        if (signal.aborted) reject(abortReason());
+        else resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}
+
 export async function readClientAppState<T = unknown>(
   key: string,
   options: ClientAppStateReadOptions = {},
 ): Promise<T | null> {
-  const response = await fetch(appStateUrl(key), {
-    method: "GET",
-    cache: "no-store",
-    signal: options.signal,
-  });
-  return parseAppStateResponse<T | null>(
-    response,
-    `Read application state "${key}"`,
-  );
+  appStateUrl(key); // validates the key shape before it joins a batch
+  if (options.signal?.aborted) {
+    throw options.signal.reason ?? new Error("Aborted");
+  }
+  const batch = await awaitWithAbort(scheduleBatchedRead(key), options.signal);
+  return (batch.values[key] ?? null) as T | null;
 }
 
 export async function writeClientAppState<T = unknown>(
@@ -129,9 +227,14 @@ export async function deleteClientAppState(
 ): Promise<void> {
   const response = await fetch(appStateUrl(key), {
     method: "DELETE",
-    headers: options.requestSource
-      ? { "X-Request-Source": options.requestSource }
-      : undefined,
+    // DELETE carries no JSON body, so this custom header is the only
+    // same-origin marker the CSRF check can see from an embedded frame.
+    headers: {
+      "X-Agent-Native-CSRF": "1",
+      ...(options.requestSource
+        ? { "X-Request-Source": options.requestSource }
+        : {}),
+    },
     keepalive: options.keepalive,
     signal: options.signal,
   });

package/corpus/core/src/client/dynamic-suggestions.ts

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState } from "react";
 
-import { agentNativePath } from "./api-path.js";
+import { readClientAppState } from "./application-state.js";
 import { useChangeVersions } from "./use-change-version.js";
 import type { ChatThreadScope } from "./use-chat-threads.js";
 
@@ -89,17 +89,9 @@ function appStateKeyForBrowserTab(key: string, browserTabId?: string): string {
 }
 
 async function readAppState(key: string): Promise<unknown> {
-  const res = await fetch(
-    agentNativePath(`/_agent-native/application-state/${key}`),
-  );
-  if (!res.ok || res.status === 204) return null;
-  const text = await res.text();
-  if (!text) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return null;
-  }
+  // Reads issued in the same tick coalesce into one batched request, so the
+  // four keys below cost one round trip rather than four.
+  return readClientAppState(key).catch(() => null);
 }
 
 async function readScopedAppState(

package/corpus/core/src/client/frame-protocol.ts

@@ -115,7 +115,11 @@ export interface FrameOriginMessage {
 
 export interface ChatRunningMessage {
   type: "agentNative.chatRunning";
-  detail: { isRunning: boolean; tabId?: string };
+  detail: {
+    isRunning: boolean;
+    tabId?: string;
+    reason?: "stopped" | "failed";
+  };
 }
 
 export interface UserInfoMessage {

package/corpus/core/src/client/guided-questions.tsx

@@ -12,8 +12,11 @@ import {
 import { useCallback, useEffect, useMemo, useState } from "react";
 
 import { sendToAgentChat } from "./agent-chat.js";
-import { agentNativePath } from "./api-path.js";
-import { setClientAppState } from "./application-state.js";
+import {
+  deleteClientAppState,
+  readClientAppState,
+  setClientAppState,
+} from "./application-state.js";
 import { useChangeVersions } from "./use-change-version.js";
 import { cn } from "./utils.js";
 
@@ -998,10 +1001,6 @@ export function useGuidedQuestionFlow({
     () => normalizeBrowserTabId(browserTabId),
     [browserTabId],
   );
-  const endpointFor = useCallback(
-    (key: string) => agentNativePath(`/_agent-native/application-state/${key}`),
-    [],
-  );
   const scopedKey = normalizedBrowserTabId
     ? `${stateKey}:${normalizedBrowserTabId}`
     : stateKey;
@@ -1036,17 +1035,11 @@ export function useGuidedQuestionFlow({
     enabled,
     queryFn: async () => {
       const read = async (key: string) => {
-        const res = await fetch(endpointFor(key));
-        if (!res.ok) return null;
-        const text = await res.text();
-        if (!text) return null;
-        try {
-          const parsed = JSON.parse(text);
-          if (Array.isArray(parsed?.questions) && parsed.questions.length > 0) {
-            return parsed as GuidedQuestionPayload;
-          }
-        } catch {
-          return null;
+        const parsed = await readClientAppState<GuidedQuestionPayload>(
+          key,
+        ).catch(() => null);
+        if (Array.isArray(parsed?.questions) && parsed.questions.length > 0) {
+          return parsed;
         }
         return null;
       };
@@ -1086,16 +1079,12 @@ export function useGuidedQuestionFlow({
   const clear = useCallback(() => {
     setPayload(null);
     queryClient.setQueryData(resolvedQueryKey, null);
-    const del = (key: string) =>
-      fetch(endpointFor(key), {
-        method: "DELETE",
-        headers: { "X-Agent-Native-CSRF": "1" },
-      }).catch(() => {});
+    const del = (key: string) => deleteClientAppState(key).catch(() => {});
     // Clear whichever key actually held the payload (scoped or bare) so the
     // card doesn't reappear on the next poll.
     del(scopedKey);
     if (scopedKey !== stateKey) del(stateKey);
-  }, [endpointFor, queryClient, resolvedQueryKey, scopedKey, stateKey]);
+  }, [queryClient, resolvedQueryKey, scopedKey, stateKey]);
 
   const handleSubmit = useCallback(
     (answers: GuidedQuestionAnswers) => {