@opengeni/react 0.45.0 → 0.48.0

package/src/timeline/projection.ts

@@ -540,6 +540,18 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
 
       case "tool.auth_needed":
       case "credential.auth_needed": {
+        if (
+          event.type === "tool.auth_needed" &&
+          !stringValue(payload.toolName) &&
+          stringValue(payload.serverId) !== "codex_apps"
+        ) {
+          // Historical optional-MCP initialize/tools-list credential misses are
+          // setup availability, not evidence of a concrete conversational tool
+          // call. Keep the raw event in Debug/audit but do not manufacture an
+          // actionable reconnect card in the transcript. Actual tools/call auth
+          // failures carry a concrete toolName and remain visible.
+          break;
+        }
         // Keep the whole structured payload — the renderer turns it into a clean
         // inline reconnect card, and the app starts the recovery flow off the
         // connectionId/resource. Losing it to a plain-text notice was the ugly
@@ -549,6 +561,8 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           kind: "auth-needed",
           id: event.id,
           turnId,
+          serverId: typeof payload.serverId === "string" ? payload.serverId : null,
+          source: event.type === "tool.auth_needed" ? "tool" : "credential",
           providerDomain: stringValue(payload.providerDomain),
           connectionId: typeof payload.connectionId === "string" ? payload.connectionId : null,
           reason: authNeededReason(payload.reason),
@@ -1609,6 +1623,15 @@ export function extractSessionRef(value: unknown, depth = 0): string | null {
     return null;
   }
   const record = value as Record<string, unknown>;
+  const receiptResource = asRecord(record.resource);
+  if (
+    record.receiptVersion === "mcp-mutation-receipt.v1" &&
+    receiptResource.type === "session" &&
+    typeof receiptResource.id === "string" &&
+    looksLikeId(receiptResource.id)
+  ) {
+    return receiptResource.id;
+  }
   if (typeof record.sessionId === "string" && looksLikeId(record.sessionId)) {
     return record.sessionId;
   }

package/src/timeline/registry.ts

@@ -1,3 +1,4 @@
+import type { RetainedArtifactReference } from "@opengeni/sdk";
 import type { ComponentType } from "react";
 import { mcpToolLeaf } from "./tool-display-name";
 import type { ToolCallItem } from "./types";
@@ -22,8 +23,14 @@ import type { ToolCallItem } from "./types";
 
 export type ToolRendererProps = {
   item: ToolCallItem;
+  loadRetainedScreenshot?: RetainedScreenshotLoader | undefined;
 };
 
+export type RetainedScreenshotLoader = (
+  artifact: RetainedArtifactReference,
+  signal: AbortSignal,
+) => Promise<Uint8Array | null>;
+
 export type ToolRenderer = ComponentType<ToolRendererProps>;
 
 /** A registry entry: which key it matches and the component that renders it. */

package/src/timeline/screenshot-lightbox.tsx

@@ -3,6 +3,7 @@ import { AnimatePresence, motion } from "motion/react";
 import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from "react";
 import { Dialog } from "radix-ui";
 import { cn } from "../lib/cn";
+import { usePortalTokenStyle } from "../lib/use-portal-token-style";
 
 /* ----------------------------------------------------------------------------
    Screenshot lightbox
@@ -18,7 +19,7 @@ import { cn } from "../lib/cn";
    -------------------------------------------------------------------------- */
 
 type LightboxController = {
-  open: (src: string, caption?: string) => void;
+  open: (src: string, caption?: string, source?: HTMLElement | null) => void;
 };
 
 const LightboxContext = createContext<LightboxController | null>(null);
@@ -59,17 +60,25 @@ export function LightboxProvider({ children }: { children: ReactNode }) {
 
 function LightboxRoot({ children }: { children: ReactNode }) {
   const [state, setState] = useState<{ src: string; caption?: string } | null>(null);
+  const [tokenSource, setTokenSource] = useState<HTMLElement | null>(null);
+  const portalStyle = usePortalTokenStyle(tokenSource);
 
-  const open = useCallback((src: string, caption?: string) => {
+  const open = useCallback((src: string, caption?: string, source?: HTMLElement | null) => {
+    setTokenSource(source ?? null);
     setState(caption ? { src, caption } : { src });
   }, []);
 
+  const close = useCallback(() => {
+    setState(null);
+    setTokenSource(null);
+  }, []);
+
   const controller = useMemo<LightboxController>(() => ({ open }), [open]);
 
   return (
     <LightboxContext.Provider value={controller}>
       {children}
-      <Dialog.Root open={state !== null} onOpenChange={(next) => !next && setState(null)}>
+      <Dialog.Root open={state !== null} onOpenChange={(next) => !next && close()}>
         <AnimatePresence>
           {state !== null ? (
             <Dialog.Portal forceMount>
@@ -80,6 +89,7 @@ function LightboxRoot({ children }: { children: ReactNode }) {
                   exit={{ opacity: 0 }}
                   transition={{ duration: 0.15 }}
                   className="og-root fixed inset-0 z-50 bg-black/90 backdrop-blur-md"
+                  style={portalStyle}
                 />
               </Dialog.Overlay>
               <Dialog.Content
@@ -101,10 +111,11 @@ function LightboxRoot({ children }: { children: ReactNode }) {
                   // figcaption's "click outside to close" affordance is real.
                   onClick={(event) => {
                     if (event.target === event.currentTarget) {
-                      setState(null);
+                      close();
                     }
                   }}
                   className="og-root fixed inset-0 z-50 flex items-center justify-center p-6 sm:p-12"
+                  style={portalStyle}
                 >
                   <Dialog.Title className="sr-only">Screenshot</Dialog.Title>
                   {/* The figure is one self-contained object: image, caption, and

package/src/timeline/shared.tsx

@@ -154,16 +154,16 @@ export function ActivityDisclosure({
   const rowClass = cn(
     "group/disclosure flex w-full min-w-0 items-center gap-2 rounded-og-sm px-1.5 py-1.5 text-left text-og-base",
     "text-og-fg-muted transition-colors duration-150",
-    // A tool row is a touch target on coarse pointers: grow its padding so the
-    // hit area clears the 40px minimum without loosening the dense desktop rail.
-    "pointer-coarse:py-2.5",
+    // A tool row is a touch target on coarse pointers: grow its hit area to the
+    // 44px mobile minimum without loosening the dense desktop rail.
+    "pointer-coarse:min-h-11 pointer-coarse:py-2.5",
   );
   // The chevron rotates to point down when open; it tracks `data-state` on this
   // same row (the Trigger), so the affordance never freezes.
   const inner = (
     <>
       {hasBody ? (
-        <ChevronRightIcon className="size-3.5 shrink-0 text-og-fg-subtle transition-transform duration-[var(--og-duration-disclose)] ease-og-in-out group-data-[state=open]/disclosure:rotate-90" />
+        <ChevronRightIcon className="size-3.5 shrink-0 text-og-fg-subtle transition-transform duration-[var(--_og-duration-disclose)] ease-og-in-out group-data-[state=open]/disclosure:rotate-90" />
       ) : (
         <span className="size-3.5 shrink-0" />
       )}
@@ -226,7 +226,7 @@ export function ActivityDisclosure({
         data-status={dataStatus}
         className={cn(
           rowClass,
-          "cursor-pointer outline-none hover:bg-og-surface-1 hover:text-og-fg",
+          "cursor-pointer outline-hidden hover:bg-og-surface-1 hover:text-og-fg",
           "focus-visible:ring-2 focus-visible:ring-og-accent focus-visible:ring-offset-0",
         )}
       >
@@ -498,7 +498,7 @@ export function Thumbnail({
       type="button"
       onClick={(event) => {
         event.stopPropagation();
-        lightbox.open(src, caption);
+        lightbox.open(src, caption, event.currentTarget);
       }}
       onKeyDown={(event) => {
         if (event.key === "Enter" || event.key === " ") {
@@ -507,7 +507,7 @@ export function Thumbnail({
       }}
       className={cn(
         MEDIA_BOX,
-        "group/thumb relative inline-flex overflow-hidden bg-og-bg outline-none",
+        "group/thumb relative inline-flex overflow-hidden bg-og-bg outline-hidden",
         "focus-visible:ring-2 focus-visible:ring-og-accent",
       )}
       aria-label="Expand screenshot"
@@ -554,7 +554,7 @@ export function ScreenshotFigure({
       ) : lightbox ? (
         <button
           type="button"
-          onClick={() => lightbox.open(src, caption)}
+          onClick={(event) => lightbox.open(src, caption, event.currentTarget)}
           className={surface}
           aria-label="Expand screenshot"
         >

package/src/timeline/tool-renderers.tsx

@@ -1,4 +1,4 @@
-import type { GitFileDiff } from "@opengeni/sdk";
+import type { GitFileDiff, RetainedArtifactReference } from "@opengeni/sdk";
 import {
   BoxIcon,
   BrainCircuitIcon,
@@ -28,7 +28,7 @@ import {
   TerminalIcon,
   WrenchIcon,
 } from "lucide-react";
-import type { ReactNode } from "react";
+import { useEffect, useState, type ReactNode } from "react";
 import { stringifyPayload, tryParseJson } from "../lib/format";
 import { useTimelineComputeLabel } from "./compute-label";
 import {
@@ -40,7 +40,7 @@ import {
   mediaPreviewFact,
   parseExecBannerSessionId,
   parseToolArgs,
-  redactSecrets,
+  retainedScreenshotMetadata,
   sandboxCommandExitCode,
   stripExecBanner,
   tailPeek,
@@ -559,7 +559,7 @@ function asComputerArgs(args: unknown): Partial<ComputerAction> {
   };
 }
 
-function ComputerCallRenderer({ item }: ToolRendererProps) {
+function ComputerCallRenderer({ item, loadRetainedScreenshot }: ToolRendererProps) {
   const raw = (item.raw ?? {}) as {
     action?: ComputerAction;
     actions?: ComputerAction[];
@@ -582,6 +582,7 @@ function ComputerCallRenderer({ item }: ToolRendererProps) {
   const rejected = raw.providerData?.approvalStatus === "rejected";
   const readOnly = typeof out === "string" && out.includes("read-only");
   const shotUrl = screenshotDataUrl(out);
+  const retained = retainedScreenshotMetadata(out);
   const omittedMedia = mediaPreviewFact(out);
   const empty = out === "" || out == null;
   const batched = actions.length > 1 ? actions.map((a) => computerVerb(a)).join(" · ") : null;
@@ -640,6 +641,41 @@ function ComputerCallRenderer({ item }: ToolRendererProps) {
   const isFailed = item.status === "failed";
   const isCancelled = item.status === "cancelled";
 
+  if (retained) {
+    if (!retained.available) {
+      const state =
+        retained.reason === "expired" || retained.reason === "deleted"
+          ? retained.reason
+          : "unavailable";
+      return (
+        <ActivityDisclosure
+          icon={<CameraOffIcon className={ICON_SIZE} />}
+          iconTone={isFailed ? "failed" : "muted"}
+          title={`${verb}${countSuffix} · ${state}`}
+          failed={isFailed}
+          cancelled={isCancelled}
+          preview={`screenshot ${state}`}
+          media={<MediaEmpty />}
+        >
+          <BodyNote tone={isFailed ? "error" : undefined}>
+            Screenshot {state}: {retained.reason.replaceAll("_", " ")}.
+          </BodyNote>
+        </ActivityDisclosure>
+      );
+    }
+    return (
+      <RetainedScreenshotDisclosure
+        artifact={retained}
+        load={loadRetainedScreenshot}
+        verb={verb}
+        countSuffix={countSuffix}
+        batched={batched}
+        failed={isFailed}
+        cancelled={isCancelled}
+      />
+    );
+  }
+
   if (shotUrl) {
     const caption = `${verb}${actions.length > 1 ? ` (+${actions.length - 1} more)` : ""}`;
     return (
@@ -720,6 +756,112 @@ function ComputerCallRenderer({ item }: ToolRendererProps) {
   );
 }
 
+function RetainedScreenshotDisclosure({
+  artifact,
+  load,
+  verb,
+  countSuffix,
+  batched,
+  failed,
+  cancelled,
+}: {
+  artifact: RetainedArtifactReference;
+  load: ToolRendererProps["loadRetainedScreenshot"];
+  verb: string;
+  countSuffix: string;
+  batched: string | null;
+  failed: boolean;
+  cancelled: boolean;
+}) {
+  const [state, setState] = useState<
+    | { kind: "loading" }
+    | { kind: "ready"; url: string }
+    | { kind: "unavailable"; label: string }
+    | { kind: "error"; message: string }
+  >({ kind: "loading" });
+
+  useEffect(() => {
+    if (!load) {
+      setState({ kind: "unavailable", label: "retrieval is not configured" });
+      return;
+    }
+    const controller = new AbortController();
+    let objectUrl: string | null = null;
+    setState({ kind: "loading" });
+    void load(artifact, controller.signal)
+      .then((bytes) => {
+        if (controller.signal.aborted) return;
+        if (!bytes) {
+          setState({ kind: "unavailable", label: "bytes are unavailable" });
+          return;
+        }
+        objectUrl = URL.createObjectURL(new Blob([Uint8Array.from(bytes)], { type: "image/png" }));
+        setState({ kind: "ready", url: objectUrl });
+      })
+      .catch((error: unknown) => {
+        if (controller.signal.aborted) return;
+        const status =
+          error && typeof error === "object" && "status" in error
+            ? Number((error as { status?: unknown }).status)
+            : null;
+        setState(
+          status === 404
+            ? { kind: "unavailable", label: "deleted" }
+            : status === 410
+              ? { kind: "unavailable", label: "expired or unavailable" }
+              : {
+                  kind: "error",
+                  message: "retrieval failed",
+                },
+        );
+      });
+    return () => {
+      controller.abort();
+      if (objectUrl) URL.revokeObjectURL(objectUrl);
+    };
+  }, [artifact, load]);
+
+  const caption = `${verb}${countSuffix}`;
+  return (
+    <ActivityDisclosure
+      icon={<CameraIcon className={ICON_SIZE} />}
+      iconTone={failed ? "failed" : state.kind === "ready" ? "accent" : "muted"}
+      title={caption}
+      failed={failed}
+      cancelled={cancelled}
+      preview={
+        state.kind === "loading"
+          ? "loading retained screenshot…"
+          : state.kind === "error"
+            ? "screenshot retrieval failed"
+            : state.kind === "unavailable"
+              ? `screenshot ${state.label}`
+              : undefined
+      }
+      media={
+        state.kind === "ready" ? (
+          <Thumbnail src={state.url} caption={caption} />
+        ) : state.kind === "loading" ? (
+          <MediaSkeleton />
+        ) : (
+          <MediaEmpty />
+        )
+      }
+    >
+      {state.kind === "ready" ? (
+        <ScreenshotFigure src={state.url} caption={caption} />
+      ) : state.kind === "loading" ? (
+        <BodyNote>Loading the retained screenshot…</BodyNote>
+      ) : state.kind === "unavailable" ? (
+        <BodyNote>Screenshot {state.label}.</BodyNote>
+      ) : (
+        <BodyNote tone="error">Screenshot retrieval failed: {state.message}</BodyNote>
+      )}
+      {batched ? <BodyNote>batched: {batched}</BodyNote> : null}
+    </ActivityDisclosure>
+  );
+}
+
 /* ---- web_search ------------------------------------------------------------ */
 
 type WebSearchResult = { title: string; domain: string; snippet: string };
@@ -995,7 +1137,7 @@ function SecretSetRenderer({ item }: ToolRendererProps) {
         running
         preview={<RunningPreview>setting…</RunningPreview>}
       >
-        <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+        <PayloadBlock label="Arguments" value={args} />
       </ActivityDisclosure>
     );
   }
@@ -1010,7 +1152,7 @@ function SecretSetRenderer({ item }: ToolRendererProps) {
         failed
         preview={errorText ?? "variable write failed"}
       >
-        <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+        <PayloadBlock label="Arguments" value={args} />
         {errorText ? (
           <PayloadBlock label="Error" value={errorText} failed />
         ) : (
@@ -1026,10 +1168,12 @@ function SecretSetRenderer({ item }: ToolRendererProps) {
       iconTone="muted"
       title={`Set ${name}`}
       cancelled={item.status === "cancelled"}
-      preview="value write-only · never returned"
+      preview="exact value preserved"
     >
-      <PayloadBlock label="Arguments" value={redactSecrets(args)} />
-      <BodyNote>the value is a secret — redacted in every view; the API never returns it.</BodyNote>
+      <PayloadBlock label="Arguments" value={args} />
+      <BodyNote>
+        The configured value is preserved exactly and available through authorized secret reads.
+      </BodyNote>
     </ActivityDisclosure>
   );
 }
@@ -1175,7 +1319,7 @@ function ToolSearchRenderer({ item }: ToolRendererProps) {
         }
       >
         {query ? <BodyNote>capability query: {query}</BodyNote> : null}
-        <PayloadBlock label="Arguments" value={redactSecrets(parseToolArgs(item.arguments))} />
+        <PayloadBlock label="Arguments" value={parseToolArgs(item.arguments)} />
       </ActivityDisclosure>
     );
   }
@@ -1191,7 +1335,7 @@ function ToolSearchRenderer({ item }: ToolRendererProps) {
         preview={truncatePreview(outText, 80) || queryPreview || "Lookup failed"}
       >
         {query ? <BodyNote>capability query: {query}</BodyNote> : null}
-        <PayloadBlock label="Arguments" value={redactSecrets(parseToolArgs(item.arguments))} />
+        <PayloadBlock label="Arguments" value={parseToolArgs(item.arguments)} />
         <PayloadBlock label="Error" value={outText} failed />
       </ActivityDisclosure>
     );
@@ -1226,7 +1370,7 @@ function ToolSearchRenderer({ item }: ToolRendererProps) {
       ) : tools && tools.length === 0 ? (
         <BodyNote>no deferred tools matched this capability query.</BodyNote>
       ) : null}
-      <PayloadBlock label="Arguments" value={redactSecrets(parseToolArgs(item.arguments))} />
+      <PayloadBlock label="Arguments" value={parseToolArgs(item.arguments)} />
       {tools == null && outText ? <PayloadBlock label="Result" value={outText} /> : null}
     </ActivityDisclosure>
   );
@@ -1249,7 +1393,7 @@ function DocsSearchRenderer({ item }: ToolRendererProps) {
         running
         preview={<RunningPreview>Searching…</RunningPreview>}
       >
-        <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+        <PayloadBlock label="Arguments" value={args} />
       </ActivityDisclosure>
     );
   }
@@ -1264,7 +1408,7 @@ function DocsSearchRenderer({ item }: ToolRendererProps) {
         failed
         preview={truncatePreview(outText, 80) || "Search failed"}
       >
-        <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+        <PayloadBlock label="Arguments" value={args} />
         <PayloadBlock label="Error" value={outText} failed />
       </ActivityDisclosure>
     );
@@ -1300,7 +1444,7 @@ function DocsSearchRenderer({ item }: ToolRendererProps) {
           ))}
         </ul>
       ) : null}
-      <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+      <PayloadBlock label="Arguments" value={args} />
       <PayloadBlock label="Result" value={outText} />
     </ActivityDisclosure>
   );
@@ -1330,7 +1474,7 @@ function SetSessionTitleRenderer({ item }: ToolRendererProps) {
           )
         }
       >
-        <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+        <PayloadBlock label="Arguments" value={args} />
       </ActivityDisclosure>
     );
   }
@@ -1345,7 +1489,7 @@ function SetSessionTitleRenderer({ item }: ToolRendererProps) {
         failed
         preview={truncatePreview(outText, 80) || "Rename failed"}
       >
-        <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+        <PayloadBlock label="Arguments" value={args} />
         <PayloadBlock label="Error" value={outText} failed />
       </ActivityDisclosure>
     );
@@ -1371,7 +1515,7 @@ function SetSessionTitleRenderer({ item }: ToolRendererProps) {
       cancelled={item.status === "cancelled"}
       preview={item.status === "cancelled" ? undefined : settledTitle || undefined}
     >
-      <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+      <PayloadBlock label="Arguments" value={args} />
       {outText ? <PayloadBlock label="Result" value={outText} /> : null}
     </ActivityDisclosure>
   );
@@ -1431,7 +1575,7 @@ function MemoryProposeRenderer({ item }: ToolRendererProps) {
         running
         preview={<RunningPreview>Proposing…</RunningPreview>}
       >
-        <PayloadBlock label="Arguments" value={redactSecrets(args)} />
+        <PayloadBlock label="Arguments" value={args} />
       </ActivityDisclosure>
     );
   }
@@ -1493,7 +1637,7 @@ function askToolPreview(args: unknown): string | null {
 }
 
 function AskRenderer({ item }: ToolRendererProps) {
-  const args = redactSecrets(parseToolArgs(item.arguments));
+  const args = parseToolArgs(item.arguments);
   const preview = askToolPreview(args);
   const icon = <MessageCircleQuestionIcon className={ICON_SIZE} />;
   const title = "Ask";
@@ -1583,7 +1727,7 @@ function runOnOpPreview(args: Record<string, unknown>): string | null {
 
 function RunOnRenderer({ item }: ToolRendererProps) {
   const parsedArgs = parseToolArgs(item.arguments);
-  const args = redactSecrets(parsedArgs);
+  const args = parsedArgs;
   const targetName = runOnTargetName(item.output);
   const title = targetName ? `Run on ${targetName}` : "Run on";
   const opPreview = runOnOpPreview(parsedArgs);
@@ -1648,7 +1792,7 @@ function RunOnRenderer({ item }: ToolRendererProps) {
  */
 function GenericRenderer({ item }: ToolRendererProps) {
   const running = item.status === "running";
-  const args = redactSecrets(parseToolArgs(item.arguments));
+  const args = parseToolArgs(item.arguments);
   const display = toolDisplayName(item.name);
   const icon = <GenericToolIcon name={item.name} />;
   // Goal tools: surface the objective text on the collapsed row so the in-cluster

package/src/timeline/turn-summary.tsx

@@ -416,8 +416,8 @@ export function TurnSummary({
               // as a turn landmark above any nested cluster rows it groups.
               "group flex w-full items-center rounded-og-sm text-left transition-colors",
               // A folded turn is a touch target on coarse pointers: grow the row so it
-              // clears the 40px minimum without disturbing the calm desktop rhythm.
-              "pointer-coarse:py-2.5",
+              // clears the 44px minimum without disturbing the calm desktop rhythm.
+              "pointer-coarse:min-h-11 pointer-coarse:py-2.5",
               bare
                 ? "gap-2 px-1.5 py-1.5 text-og-sm text-og-fg-muted"
                 : "-mx-2 gap-2.5 px-2 py-1.5 text-og-base text-og-fg-muted",
@@ -437,8 +437,8 @@ export function TurnSummary({
               className={cn(
                 "size-3.5 shrink-0 text-og-fg-subtle transition-transform ease-og-in-out group-data-[state=open]:rotate-90",
                 settlePhase
-                  ? "duration-[var(--og-duration-disclose-settle)]"
-                  : "duration-[var(--og-duration-disclose)]",
+                  ? "duration-[var(--_og-duration-disclose-settle)]"
+                  : "duration-[var(--_og-duration-disclose)]",
               )}
             />
             {/* Completion is the quiet default and needs no repeated glyph. Failed,
@@ -646,8 +646,8 @@ const BUILT_IN_TURN_SUMMARY_FACETS: readonly TurnSummaryFacet[] = Object.freeze(
               contextCompactionCount === 1 ? "compacted" : `${contextCompactionCount} compacts`,
             ariaLabel:
               contextCompactionCount === 1
-                ? "Conversation memory compacted"
-                : `${contextCompactionCount} conversation memory compactions`,
+                ? "Conversation history compacted"
+                : `${contextCompactionCount} conversation history compactions`,
           }
         : null,
   },

package/src/timeline/types.ts

@@ -288,6 +288,10 @@ export type AuthNeededItem = {
   kind: "auth-needed";
   id: string;
   turnId: string | null;
+  /** The runtime surface that requested recovery, when the event is an MCP auth signal. */
+  serverId: string | null;
+  /** Durable event family that produced this notice. */
+  source?: "tool" | "credential" | undefined;
   /** The connection's registrable domain, e.g. "linear.app". */
   providerDomain: string;
   /** The lapsed connection to reconnect, when the row survived. */

package/src/voice-recording-store.ts

@@ -9,6 +9,8 @@ export type VoiceRecordingUploadState = "pending" | "syncing" | "retrying" | "co
 export type VoiceRecordingTranscriptionState = "pending" | "transcribing" | "retrying" | "complete";
 export type VoiceRecordingFinalizationState = "pending" | "transcript-ready" | "handed-off";
 export type VoiceRecordingChunkUploadState = "pending" | "syncing" | "complete";
+export type VoiceRecordingRecoveryMode = "automatic" | "manual";
+export type VoiceRecordingHandoffMode = "append" | "explicit";
 
 export type VoiceRecordingManifest = {
   version: 1;
@@ -22,6 +24,10 @@ export type VoiceRecordingManifest = {
   uploadState: VoiceRecordingUploadState;
   transcriptionState: VoiceRecordingTranscriptionState;
   finalizationState: VoiceRecordingFinalizationState;
+  /** Whether safe server reconciliation should continue without another user action. */
+  recoveryMode: VoiceRecordingRecoveryMode;
+  /** Delayed/recovered results require explicit insertion instead of mutating an uncertain draft. */
+  handoffMode: VoiceRecordingHandoffMode;
   /** Tab/process lease. A different owner may take over only after this heartbeat is stale. */
   ownerId: string | null;
   ownerHeartbeatAt: string | null;
@@ -91,6 +97,8 @@ export interface VoiceRecordingStore {
         | "ownerId"
         | "ownerHeartbeatAt"
         | "transcriptText"
+        | "recoveryMode"
+        | "handoffMode"
       >
     >,
     updatedAt: string,
@@ -155,6 +163,8 @@ export function createVoiceRecordingManifest(input: {
     uploadState: "pending",
     transcriptionState: "pending",
     finalizationState: "pending",
+    recoveryMode: "automatic",
+    handoffMode: "append",
     ownerId: input.ownerId ?? null,
     ownerHeartbeatAt: input.ownerId ? input.createdAt : null,
     transcriptText: null,
@@ -306,6 +316,7 @@ export class IndexedDbVoiceRecordingStore implements VoiceRecordingStore {
     const updated: VoiceRecordingManifest = {
       ...manifest,
       captureState: manifest.captureState === "capturing" ? "stopped" : manifest.captureState,
+      handoffMode: "explicit",
       ownerId,
       ownerHeartbeatAt: claimedAt,
       updatedAt: claimedAt,
@@ -370,6 +381,8 @@ export class IndexedDbVoiceRecordingStore implements VoiceRecordingStore {
         | "ownerId"
         | "ownerHeartbeatAt"
         | "transcriptText"
+        | "recoveryMode"
+        | "handoffMode"
       >
     >,
     updatedAt: string,
@@ -455,6 +468,8 @@ function normalizeManifest(manifest: VoiceRecordingManifest): VoiceRecordingMani
     ownerId: manifest.ownerId ?? null,
     ownerHeartbeatAt: manifest.ownerHeartbeatAt ?? null,
     transcriptText: manifest.transcriptText ?? null,
+    recoveryMode: manifest.recoveryMode ?? "manual",
+    handoffMode: manifest.handoffMode ?? "explicit",
   };
 }