@opengeni/react 0.13.0 → 0.20.0

package/src/hooks/use-turn-queue.ts

@@ -1,14 +1,20 @@
-import type { SessionEvent, SessionQueueSnapshot, SessionTurn } from "@opengeni/sdk";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { useOpenGeni, type ClientOverride } from "../provider";
+import type {
+  ComposerDraft,
+  EffectiveSessionControl,
+  SessionEvent,
+  SessionQueueMutationResponse,
+  SessionQueueSnapshot,
+  SessionTurn,
+} from "@opengeni/sdk";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
 import {
   useDebouncedCallback,
-  useMutationRunner,
   useSessionEventTrigger,
   type SessionEventFeedOptions,
 } from "./internal";
 
-/** Events that can change the authoritative prompt queue or its pause gates. */
+/** Events that can change the authoritative prompt queue or effective control. */
 export function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean {
   return (
     event.type.startsWith("turn.") ||
@@ -18,7 +24,21 @@ export function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean {
   );
 }
 
-export type UseTurnQueueOptions = ClientOverride &
+function queueSnapshotCovers(
+  candidate: SessionQueueSnapshot | null,
+  observed: SessionQueueSnapshot,
+): boolean {
+  return Boolean(
+    candidate &&
+    candidate.version >= observed.version &&
+    candidate.effectiveControl.controlVersion >= observed.effectiveControl.controlVersion,
+  );
+}
+
+export type QueueMutationKind = "move" | "edit" | "steer" | "delete";
+const EMPTY_PENDING_BY_TURN: Readonly<Record<string, QueueMutationKind>> = {};
+
+export type UseTurnQueueOptions = EmbeddedSessionClientOverride &
   SessionEventFeedOptions & {
     pollIntervalMs?: number | undefined;
   };
@@ -27,69 +47,124 @@ export type UseTurnQueueResult = {
   snapshot: SessionQueueSnapshot | null;
   /** Human/API prompts exactly in server execution order. Never client-sorted. */
   queue: SessionTurn[];
-  controlState: SessionQueueSnapshot["controlState"] | null;
-  controlGeneration: number | null;
-  workspaceInferenceState: SessionQueueSnapshot["workspaceInferenceState"] | null;
-  workspaceInferenceGeneration: number | null;
-  workspaceRunExceptionGeneration: number | null;
+  effectiveControl: EffectiveSessionControl | null;
+  /** The latest interrupted attempt has not yet durably proved physical quiescence. */
+  stoppingPreviousAttempt: boolean;
   loading: boolean;
   error: Error | null;
   refresh: () => Promise<void>;
-  /** Delete a waiting prompt before the worker claims it. */
+  moveTurn: (turnId: string, beforeTurnId: string | null) => Promise<boolean>;
+  /** Atomically withdraw a waiting prompt into the private durable composer draft. */
+  editTurn: (
+    turnId: string,
+    options: { expectedDraftRevision: number; replaceDraft: boolean },
+  ) => Promise<ComposerDraft | null>;
+  /** Advance the same durable waiting prompt; no duplicate prompt is created. */
+  steerTurn: (turnId: string) => Promise<boolean>;
   removeTurn: (turnId: string) => Promise<boolean>;
+  pendingByTurn: Readonly<Record<string, QueueMutationKind>>;
+  mutationFor: (turnId: string) => QueueMutationKind | null;
   mutating: boolean;
   mutationError: Error | null;
   clearMutationError: () => void;
 };
 
 /**
- * The single authoritative waiting-prompt queue. The server owns ordering; the
- * client renders the returned array verbatim and supports deletion only.
+ * The one authoritative human prompt queue. Every mutation carries the exact
+ * server versions the operator saw and accepts only monotonic snapshots. A
+ * conflict immediately reloads server truth; the client never invents order.
  */
 export function useTurnQueue(
   sessionId: string | null | undefined,
   options: UseTurnQueueOptions = {},
 ): UseTurnQueueResult {
-  const { client, workspaceId } = useOpenGeni(options);
+  const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
+    useEmbeddedSession(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
   const [snapshot, setSnapshot] = useState<SessionQueueSnapshot | null>(null);
+  const [stateTargetKey, setStateTargetKey] = useState(targetKey);
   const [loading, setLoading] = useState(enabled);
   const [error, setError] = useState<Error | null>(null);
-  const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
-  const generation = useRef(0);
-  const targetKeyRef = useRef<string | null>(null);
+  const [mutationError, setMutationError] = useState<Error | null>(null);
+  const [pendingByTurn, setPendingByTurn] = useState<Record<string, QueueMutationKind>>({});
+  const pendingRef = useRef<Record<string, QueueMutationKind>>({});
+  const readGeneration = useRef(0);
+  const targetKeyRef = useRef(targetKey);
   const snapshotRef = useRef<SessionQueueSnapshot | null>(null);
 
-  const replaceSnapshot = useCallback((next: SessionQueueSnapshot | null): void => {
-    snapshotRef.current = next;
-    setSnapshot(next);
-  }, []);
-
-  const load = useCallback(async (): Promise<void> => {
-    if (!sessionId) return;
-    const ticket = ++generation.current;
-    try {
-      const fetched = await client.getQueue(workspaceId, sessionId);
-      if (ticket === generation.current) {
-        replaceSnapshot(fetched);
-        setError(null);
-        setLoading(false);
+  // Revoke the old target only when the new one commits. A concurrent render
+  // may suspend while the previous target remains visible and interactive.
+  useLayoutEffect(() => {
+    if (targetKeyRef.current === targetKey) return;
+    targetKeyRef.current = targetKey;
+    readGeneration.current += 1;
+    snapshotRef.current = null;
+    pendingRef.current = {};
+    setStateTargetKey(targetKey);
+    setSnapshot(null);
+    setLoading(enabled);
+    setError(null);
+    setMutationError(null);
+    setPendingByTurn({});
+  }, [enabled, targetKey]);
+
+  const acceptSnapshot = useCallback(
+    (ownedTargetKey: string, next: SessionQueueSnapshot | null): boolean => {
+      if (targetKeyRef.current !== ownedTargetKey) return false;
+      const current = snapshotRef.current;
+      if (
+        next &&
+        current &&
+        (next.version < current.version ||
+          next.effectiveControl.controlVersion < current.effectiveControl.controlVersion)
+      ) {
+        return false;
       }
-    } catch (cause) {
-      if (ticket === generation.current) {
-        setError(cause instanceof Error ? cause : new Error(String(cause)));
-        setLoading(false);
+      snapshotRef.current = next;
+      setStateTargetKey(ownedTargetKey);
+      setSnapshot(next);
+      return true;
+    },
+    [],
+  );
+
+  const load = useCallback(
+    async (rejectOnFailure = false): Promise<void> => {
+      if (!sessionId) return;
+      const ownedTargetKey = `${workspaceId}\u0000${sessionId}`;
+      const ticket = ++readGeneration.current;
+      try {
+        const fetched = await client.getQueue(workspaceId, sessionId);
+        if (targetKeyRef.current !== ownedTargetKey) return;
+        const ownsLatestRead = ticket === readGeneration.current;
+        if (rejectOnFailure) {
+          const committed = acceptSnapshot(ownedTargetKey, fetched);
+          if (!committed && !queueSnapshotCovers(snapshotRef.current, fetched)) {
+            throw new TypeError("Queue reconciliation did not commit authoritative state");
+          }
+          setError(null);
+          if (ownsLatestRead) setLoading(false);
+        } else if (ownsLatestRead) {
+          acceptSnapshot(ownedTargetKey, fetched);
+          setError(null);
+          setLoading(false);
+        }
+      } catch (cause) {
+        if (
+          targetKeyRef.current === ownedTargetKey &&
+          (ticket === readGeneration.current || rejectOnFailure)
+        ) {
+          setError(asError(cause));
+          if (ticket === readGeneration.current) setLoading(false);
+        }
+        if (rejectOnFailure) throw cause;
       }
-    }
-  }, [client, workspaceId, sessionId, replaceSnapshot]);
+    },
+    [client, workspaceId, sessionId, acceptSnapshot],
+  );
 
   useEffect(() => {
-    const targetKey = `${workspaceId}\u0000${sessionId ?? ""}`;
-    if (targetKeyRef.current !== targetKey) {
-      targetKeyRef.current = targetKey;
-      replaceSnapshot(null);
-      setError(null);
-    }
     if (!enabled) {
       setLoading(false);
       return;
@@ -99,58 +174,179 @@ export function useTurnQueue(
     const pollIntervalMs = options.pollIntervalMs;
     if (pollIntervalMs === undefined || pollIntervalMs <= 0) {
       return () => {
-        generation.current += 1;
+        readGeneration.current += 1;
       };
     }
     const timer = setInterval(() => void load(), pollIntervalMs);
     return () => {
       clearInterval(timer);
-      generation.current += 1;
+      readGeneration.current += 1;
     };
-  }, [load, enabled, workspaceId, sessionId, options.pollIntervalMs, replaceSnapshot]);
+  }, [load, enabled, options.pollIntervalMs]);
+
+  useEffect(() => {
+    if (enabled && workspaceControlEvent) void load();
+  }, [enabled, load, workspaceControlEvent]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "queue", load);
+  }, [enabled, load, registerSessionReconciler, sessionId]);
 
   const scheduleRefresh = useDebouncedCallback(() => void load());
-  useSessionEventTrigger(client, workspaceId, sessionId, isTurnQueueEvent, scheduleRefresh, {
-    enabled,
-    ...(options.events !== undefined ? { events: options.events } : {}),
-  });
+  useSessionEventTrigger(
+    client,
+    workspaceId,
+    sessionId,
+    isTurnQueueEvent,
+    scheduleRefresh,
+    {
+      enabled,
+      ...(options.events !== undefined ? { events: options.events } : {}),
+    },
+    async () => await load(true),
+  );
 
-  const removeTurn = useCallback(
-    async (turnId: string): Promise<boolean> => {
-      if (!sessionId) return false;
+  const mutate = useCallback(
+    async (
+      turnId: string,
+      kind: QueueMutationKind,
+      command: (
+        current: SessionQueueSnapshot,
+        turn: SessionTurn,
+      ) => Promise<SessionQueueMutationResponse>,
+    ): Promise<SessionQueueMutationResponse | null> => {
+      const ownedTargetKey = targetKey;
+      if (!sessionId || targetKeyRef.current !== ownedTargetKey || pendingRef.current[turnId]) {
+        return null;
+      }
       const current = snapshotRef.current;
-      const item = current?.items.find((turn) => turn.id === turnId);
-      if (!current || !item) return false;
-      const result = await run(() =>
-        client.cancelQueueItem(workspaceId, sessionId, turnId, {
+      const turn = current?.items.find((candidate) => candidate.id === turnId);
+      if (!current || !turn) return null;
+      pendingRef.current = { ...pendingRef.current, [turnId]: kind };
+      setStateTargetKey(ownedTargetKey);
+      setPendingByTurn(pendingRef.current);
+      setMutationError(null);
+      try {
+        const result = await command(current, turn);
+        if (targetKeyRef.current !== ownedTargetKey) return null;
+        acceptSnapshot(ownedTargetKey, result.snapshot);
+        return result;
+      } catch (cause) {
+        if (targetKeyRef.current === ownedTargetKey) {
+          setMutationError(asError(cause));
+          await load();
+        }
+        return null;
+      } finally {
+        if (targetKeyRef.current === ownedTargetKey && turnId in pendingRef.current) {
+          const next = { ...pendingRef.current };
+          delete next[turnId];
+          pendingRef.current = next;
+          setPendingByTurn(next);
+        }
+      }
+    },
+    [acceptSnapshot, load, sessionId, targetKey],
+  );
+
+  const moveTurn = useCallback(
+    async (turnId: string, beforeTurnId: string | null): Promise<boolean> => {
+      const result = await mutate(turnId, "move", (current) =>
+        client.moveQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
           expectedQueueVersion: current.version,
-          expectedItemVersion: item.version,
+          beforeTurnId,
         }),
       );
-      if (!result) {
-        void load();
-        return false;
-      }
-      replaceSnapshot(result.snapshot);
-      return true;
+      return result !== null;
+    },
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const editTurn = useCallback(
+    async (
+      turnId: string,
+      edit: { expectedDraftRevision: number; replaceDraft: boolean },
+    ): Promise<ComposerDraft | null> => {
+      const result = await mutate(turnId, "edit", (_current, turn) =>
+        client.editQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          expectedDraftRevision: edit.expectedDraftRevision,
+          replaceDraft: edit.replaceDraft,
+        }),
+      );
+      return result?.draft ?? null;
     },
-    [client, workspaceId, sessionId, run, load, replaceSnapshot],
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const steerTurn = useCallback(
+    async (turnId: string): Promise<boolean> => {
+      const result = await mutate(turnId, "steer", (current, turn) =>
+        client.steerQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          controlEtag: current.effectiveControl.controlEtag,
+        }),
+      );
+      return result !== null;
+    },
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const removeTurn = useCallback(
+    async (turnId: string): Promise<boolean> => {
+      const result = await mutate(turnId, "delete", (_current, turn) =>
+        client.deleteQueueItem(workspaceId, sessionId!, turnId, {
+          clientEventId: operationKey(),
+          expectedTurnVersion: turn.version,
+          reason: "Deleted from the prompt queue",
+        }),
+      );
+      return result !== null;
+    },
+    [client, mutate, sessionId, workspaceId],
+  );
+
+  const identityMatches = stateTargetKey === targetKey;
+  const visibleSnapshot = identityMatches ? snapshot : null;
+  const visiblePendingByTurn = identityMatches ? pendingByTurn : EMPTY_PENDING_BY_TURN;
+  const mutating = useMemo(
+    () => Object.keys(visiblePendingByTurn).length > 0,
+    [visiblePendingByTurn],
+  );
+  const mutationFor = useCallback(
+    (turnId: string): QueueMutationKind | null => visiblePendingByTurn[turnId] ?? null,
+    [visiblePendingByTurn],
   );
 
   return {
-    snapshot,
-    queue: snapshot?.items ?? [],
-    controlState: snapshot?.controlState ?? null,
-    controlGeneration: snapshot?.controlGeneration ?? null,
-    workspaceInferenceState: snapshot?.workspaceInferenceState ?? null,
-    workspaceInferenceGeneration: snapshot?.workspaceInferenceGeneration ?? null,
-    workspaceRunExceptionGeneration: snapshot?.workspaceRunExceptionGeneration ?? null,
-    loading,
-    error,
+    snapshot: visibleSnapshot,
+    queue: visibleSnapshot?.items ?? [],
+    effectiveControl: visibleSnapshot?.effectiveControl ?? null,
+    stoppingPreviousAttempt: visibleSnapshot?.stoppingPreviousAttempt ?? false,
+    loading: identityMatches ? loading : enabled,
+    error: identityMatches ? error : null,
     refresh: load,
+    moveTurn,
+    editTurn,
+    steerTurn,
     removeTurn,
+    pendingByTurn: visiblePendingByTurn,
+    mutationFor,
     mutating,
-    mutationError,
-    clearMutationError,
+    mutationError: identityMatches ? mutationError : null,
+    clearMutationError: useCallback(() => {
+      if (targetKeyRef.current === targetKey) setMutationError(null);
+    }, [targetKey]),
   };
 }
+
+function operationKey(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}

package/src/hooks/use-windowed-sections.ts

@@ -6,12 +6,12 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
    The Changes tab stacks N file diffs in one scroll pane. Mounting N Shiki
    highlighters (Pierre's `PatchDiff`) at once is the exact wart this replaces,
    so we mount only the sections inside the visible window ± overscan and reserve
-   the rest as empty space (dossier §10.7, D2).
+   the rest as empty space (D2).
 
    Why NOT `virtua` here (unlike the file tree/rail): Pierre renders each diff in
    a shadow DOM with its own internal overflow/virtualization, so an outer
    measuring virtualizer can read a collapsed or fixed height and lay sections
-   out wrong (dossier risk #6). This hook windows by mounting/unmounting whole
+   out wrong (known layout risk). This hook windows by mounting/unmounting whole
    file sections off a scroll offset and a per-section height ESTIMATE (refined
    by measurement when a real browser provides it), which never depends on
    Pierre reporting its own height — and the math is pure + deterministic, so

package/src/hooks/use-workspace-capture.ts

@@ -14,6 +14,79 @@ const REVISION_CAPTURED = "workspace.revision.captured";
 const REVISION_DEGRADED = "workspace.revision.degraded";
 const MANIFEST_FETCH_TIMEOUT_MS = 15_000;
 
+type AvailableCaptureResponse = Extract<GetWorkspaceCaptureResponse, { available: true }>;
+
+const CAPTURE_STATS_NUMBER_FIELDS = [
+  "repoCount",
+  "fileCount",
+  "additions",
+  "deletions",
+  "totalBytes",
+  "tooLargeCount",
+  "binaryCount",
+  "treeEntryCount",
+  "durationMs",
+] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Signed manifests bypass the authenticated JSON client's wire decoder. Treat
+ * the blob as untrusted until its outer schema and exact revision identity match
+ * the metadata response that minted the URL. The API performs the full contract
+ * parse; this client-side boundary prevents a corrupt/mis-keyed response from
+ * being presented as a different authoritative capture.
+ */
+function captureManifestForResponse(
+  value: unknown,
+  response: AvailableCaptureResponse,
+): WorkspaceCaptureManifest {
+  if (
+    !isRecord(value) ||
+    value.version !== 1 ||
+    !Number.isSafeInteger(value.revision) ||
+    typeof value.capturedAt !== "string" ||
+    !(value.turnId === null || typeof value.turnId === "string") ||
+    !Number.isSafeInteger(value.leaseEpoch) ||
+    !isRecord(value.treeIndex) ||
+    typeof value.treeTruncated !== "boolean" ||
+    !Array.isArray(value.repos) ||
+    !Array.isArray(value.files) ||
+    !isRecord(value.stats)
+  ) {
+    throw new Error("Workspace capture manifest failed validation.");
+  }
+
+  if (
+    value.revision !== response.revision ||
+    value.capturedAt !== response.capturedAt ||
+    value.turnId !== response.turnId ||
+    value.leaseEpoch !== response.leaseEpoch
+  ) {
+    throw new Error("Workspace capture manifest identity did not match its response.");
+  }
+
+  for (const field of CAPTURE_STATS_NUMBER_FIELDS) {
+    if (!Number.isSafeInteger(value.stats[field]) || value.stats[field] !== response.stats[field]) {
+      throw new Error("Workspace capture manifest statistics did not match its response.");
+    }
+  }
+  if (
+    typeof value.stats.treeTruncated !== "boolean" ||
+    value.stats.treeTruncated !== response.stats.treeTruncated ||
+    (value.stats.fingerprint ?? null) !== (response.stats.fingerprint ?? null) ||
+    value.repos.length !== response.stats.repoCount ||
+    value.files.length !== response.stats.fileCount ||
+    value.treeTruncated !== response.stats.treeTruncated
+  ) {
+    throw new Error("Workspace capture manifest statistics did not match its response.");
+  }
+
+  return value as WorkspaceCaptureManifest;
+}
+
 export type UseWorkspaceCaptureOptions = ClientOverride & {
   /** Live event log (usually `useSessionEvents().events`) — a
    *  `workspace.revision.captured` for a NEWER revision refreshes the manifest. */
@@ -54,7 +127,7 @@ export type UseWorkspaceCaptureResult = {
 /**
  * The cold-paint data source: fetch the latest turn-end workspace capture with a
  * SINGLE api round-trip on mount (no machine, no Channel-A — this is the <200ms
- * first paint, dossier §10.4/§12-A1). The manifest is served inline in the common
+ * first paint). The manifest is served inline in the common
  * case; a rare >2MB manifest comes back as a short-TTL signed URL we follow.
  *
  * Subscribes to the live event log: a `workspace.revision.captured` for a revision
@@ -89,64 +162,93 @@ export function useWorkspaceCapture(
   // A generation counter fences a slow in-flight fetch against a newer one (or an
   // identity change) so a stale response can never overwrite fresher state.
   const generationRef = useRef(0);
+  const requestAbortRef = useRef<AbortController | null>(null);
   // Event sequence numbers are scoped to a session. Keeping this cursor across an
   // identity switch would discard the new session's low-numbered announcements.
   const lastSeqRef = useRef(0);
 
   const refresh = useCallback(async () => {
     if (!sessionId) return;
+    requestAbortRef.current?.abort();
+    const requestAbort = new AbortController();
+    requestAbortRef.current = requestAbort;
     const generation = (generationRef.current += 1);
     setStateIdentity(identityKey);
     setLoading(true);
     setError(null);
     try {
-      const res: GetWorkspaceCaptureResponse = await client.getWorkspaceCapture(
-        workspaceId,
-        sessionId,
-      );
-      if (generationRef.current !== generation) return;
-      if (!res.available) {
-        setCapture(null);
-        setAvailable(false);
-        setFileCount(0);
-        setDegradedReason(res.degradedReason ?? null);
-        return;
-      }
-      setDegradedReason(null);
-      // Resolve the changed-file count immediately from the response's stats — the
-      // default-tab signal must not wait on a >2MB manifest-URL hop.
-      setFileCount(res.stats.fileCount);
-      // Exactly one of manifest / manifestUrl is non-null (M2 contract). The inline
-      // manifest is the <200ms common case; a >2MB manifest is a signed URL hop.
-      let manifest = res.manifest;
-      if (!manifest && res.manifestUrl) {
-        const response = await fetch(res.manifestUrl.url, {
-          signal: AbortSignal.timeout(MANIFEST_FETCH_TIMEOUT_MS),
-        });
+      // A signed URL can expire between mint and GET. Re-enter the authenticated
+      // endpoint once to mint a fresh URL; never replay or log the old credential.
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        const res: GetWorkspaceCaptureResponse = await client.getWorkspaceCapture(
+          workspaceId,
+          sessionId,
+          { signal: requestAbort.signal },
+        );
         if (generationRef.current !== generation) return;
-        if (!response.ok)
-          throw new Error(`workspace capture manifest fetch failed: ${response.status}`);
-        manifest = (await response.json()) as WorkspaceCaptureManifest;
-        if (generationRef.current !== generation) return;
-      }
-      if (!manifest) {
-        // available:true but neither manifest nor a working URL — degrade, never crash.
-        setCapture(null);
-        setAvailable(false);
+        if (!res.available) {
+          setCapture(null);
+          setAvailable(false);
+          setFileCount(0);
+          setDegradedReason(res.degradedReason ?? null);
+          return;
+        }
+        setDegradedReason(null);
+        // Resolve the changed-file count immediately from the response's stats — the
+        // default-tab signal must not wait on a >2MB manifest-URL hop.
+        setFileCount(res.stats.fileCount);
+        // Exactly one of manifest / manifestUrl is non-null (M2 contract). The inline
+        // manifest is the <200ms common case; a >2MB manifest is a signed URL hop.
+        let manifestValue: unknown = res.manifest;
+        if (!manifestValue && res.manifestUrl) {
+          const response = await fetch(res.manifestUrl.url, {
+            signal: AbortSignal.any([
+              requestAbort.signal,
+              AbortSignal.timeout(MANIFEST_FETCH_TIMEOUT_MS),
+            ]),
+            credentials: "omit",
+            cache: "no-store",
+            referrerPolicy: "no-referrer",
+          }).catch(() => null);
+          if (generationRef.current !== generation) return;
+          if (!response?.ok) {
+            if (
+              attempt === 0 &&
+              (response === null || response.status === 401 || response.status === 403)
+            ) {
+              continue;
+            }
+            throw new Error(
+              `Workspace capture manifest download failed${response ? ` (${response.status})` : ""}.`,
+            );
+          }
+          try {
+            manifestValue = await response.json();
+          } catch {
+            throw new Error("Workspace capture manifest was not valid JSON.");
+          }
+          if (generationRef.current !== generation) return;
+        }
+        if (!manifestValue) {
+          throw new Error("Workspace capture response did not include a manifest.");
+        }
+        const manifest = captureManifestForResponse(manifestValue, res);
+        setCapture(manifest);
+        setAvailable(true);
+        // Fold the served revision into the announced high-water mark so a capture we
+        // JUST loaded is never reported stale against an older announce.
+        setAnnouncedRevision((prev) =>
+          prev === null || manifest.revision > prev ? manifest.revision : prev,
+        );
         return;
       }
-      setCapture(manifest);
-      setAvailable(true);
-      // Fold the served revision into the announced high-water mark so a capture we
-      // JUST loaded is never reported stale against an older announce.
-      setAnnouncedRevision((prev) =>
-        prev === null || manifest.revision > prev ? manifest.revision : prev,
-      );
+      throw new Error("Workspace capture manifest download failed after refreshing its URL.");
     } catch (cause) {
       if (generationRef.current !== generation) return;
       setError(cause instanceof Error ? cause : new Error(String(cause)));
     } finally {
       if (generationRef.current === generation) setLoading(false);
+      if (requestAbortRef.current === requestAbort) requestAbortRef.current = null;
     }
   }, [client, workspaceId, sessionId, identityKey]);
 
@@ -154,6 +256,8 @@ export function useWorkspaceCapture(
   useEffect(() => {
     // Invalidate a request started for the previous identity before clearing its
     // state. The cleanup also fences a response that arrives after unmount.
+    requestAbortRef.current?.abort();
+    requestAbortRef.current = null;
     generationRef.current += 1;
     lastSeqRef.current = 0;
     setCapture(null);
@@ -168,6 +272,8 @@ export function useWorkspaceCapture(
     }
     void refresh();
     return () => {
+      requestAbortRef.current?.abort();
+      requestAbortRef.current = null;
       generationRef.current += 1;
     };
   }, [enabled, refresh]);