@opengeni/react 0.23.0 → 0.25.5

package/dist/use-file-attachments-C0kpHrs9.d.ts

@@ -0,0 +1,76 @@
+import { FileAsset, FileResourceRef } from '@opengeni/sdk';
+import { C as ClientOverride } from './session-context-rgrfElMl.js';
+
+type UseFileAttachmentsOptions = ClientOverride & {
+    /**
+     * Only files matching this predicate are accepted by {@link
+     * UseFileAttachmentsResult.addFromPaste} (the clipboard path). Defaults to
+     * `image/*` — the console's historical paste filter. {@link
+     * UseFileAttachmentsResult.addFiles} (the explicit picker / drop path)
+     * bypasses it.
+     */
+    pasteFilter?: ((file: File) => boolean) | undefined;
+};
+type FileAttachment = {
+    id: string;
+    name: string;
+    contentType: string;
+    sizeBytes: number;
+    status: "uploading" | "ready" | "failed";
+    /** The SDK `FileAsset` once the upload finishes. */
+    file?: FileAsset | undefined;
+    /** Object-URL for an inline preview; minted for `image/*` files only. */
+    previewUrl?: string | undefined;
+    error?: string | undefined;
+};
+type UseFileAttachmentsResult = {
+    attachments: FileAttachment[];
+    /**
+     * `FileResourceRef[]` for every attachment that finished uploading — feed
+     * straight into `useComposer`'s `sendExtras.resources`.
+     */
+    readyResources: FileResourceRef[];
+    /** True while any attachment is still uploading (drives progress UI). */
+    uploading: boolean;
+    /**
+     * True while any attachment still needs an explicit outcome: wait for an
+     * upload, retry a failure, or remove it. This is the loss-prevention send
+     * gate; failed cards must never be silently omitted from a message.
+     */
+    hasUnresolved: boolean;
+    /** Explicit picker / drop path — uploads every file, no filter. */
+    addFiles: (files: Iterable<File>) => void;
+    /** Clipboard path — applies `pasteFilter` (default `image/*`) then uploads. */
+    addFromPaste: (event: {
+        clipboardData: DataTransfer | null;
+    }) => void;
+    /** Restore already-ready server assets without recreating browser-local bytes. */
+    restoreReadyFiles: (files: Iterable<FileAsset>) => void;
+    /**
+     * Re-run the upload for a `failed` attachment, in place (same id, same
+     * source file). No-op for an id that isn't a known failed upload.
+     */
+    retry: (id: string) => void;
+    /** Remove one attachment; revokes its object-URL. */
+    remove: (id: string) => void;
+    /**
+     * Remove only finalized files whose durable ids were accepted by a send.
+     * Attachments added while that request was in flight remain queued for the
+     * next message.
+     */
+    removeReadyFiles: (fileIds: Iterable<string>) => void;
+    /** Remove all attachments and revoke every object-URL. */
+    clear: () => void;
+};
+/**
+ * Upload-and-track state for files attached to the next message. Owns the
+ * full client-side upload layer: a per-file `uploading | ready | failed`
+ * status machine driven by the SDK's `client.uploadFile`, object-URL image
+ * previews with create/revoke lifecycle, the `image/*` clipboard paste filter,
+ * and a `FileResourceRef[]` projection that drops straight into a message's
+ * `resources`. Workspace-scoped, so it resolves both client and workspace from
+ * the {@link OpenGeniProvider} (or a per-call `{ client, workspaceId }`).
+ */
+declare function useFileAttachments(options?: UseFileAttachmentsOptions): UseFileAttachmentsResult;
+
+export { type FileAttachment as F, type UseFileAttachmentsResult as U, type UseFileAttachmentsOptions as a, useFileAttachments as u };

package/dist/use-turn-queue-3rkJwjFv.d.ts

@@ -0,0 +1,290 @@
+import { ToolAuthNeededPayload, ResourceRef, ToolRef, SessionStatus, SessionQueueSnapshot, SessionTurn, EffectiveSessionControl, ComposerDraft, SessionEvent } from '@opengeni/sdk';
+import { E as EmbeddedSessionClientOverride } from './session-context-rgrfElMl.js';
+import { S as SessionEventFeedOptions } from './use-composer-BnEzheSk.js';
+
+type UserMessageItem = {
+    kind: "user-message";
+    id: string;
+    text: string;
+    /** Resources attached to this message (file uploads, repositories). */
+    resources: ResourceRef[];
+    /** Tools requested for the turn this message starts. */
+    tools: ToolRef[];
+    occurredAt: string;
+};
+type AgentMessageItem = {
+    kind: "agent-message";
+    id: string;
+    turnId: string | null;
+    text: string;
+    /** Still receiving deltas (no completed/turn-end seen yet). */
+    streaming: boolean;
+    occurredAt: string;
+};
+type ReasoningItem = {
+    kind: "reasoning";
+    id: string;
+    turnId: string | null;
+    text: string;
+    streaming: boolean;
+    occurredAt: string;
+};
+type ToolCallItem = {
+    kind: "tool-call";
+    id: string;
+    turnId: string | null;
+    callId: string | null;
+    name: string;
+    arguments: unknown;
+    output: unknown;
+    /**
+     * The provider-native tool item (`agent.toolCall.created.payload.raw`). Carries
+     * `type` (e.g. `apply_patch_call`, `computer_call`, `hosted_tool_call`) and the
+     * tool-specific fields the per-tool renderers read (`operation`, `action`,
+     * `providerData`, …). `undefined` for first-party MCP tools, which carry their
+     * payload in `arguments`/`output` instead.
+     */
+    raw: unknown;
+    status: "running" | "complete" | "failed" | "cancelled";
+    occurredAt: string;
+};
+/**
+ * An orchestration call against another session — the manager spawning or
+ * messaging a worker. Rendered as a first-class "worker" row, not a generic
+ * tool call.
+ */
+type WorkerItem = {
+    kind: "worker";
+    id: string;
+    turnId: string | null;
+    callId: string | null;
+    action: "spawn" | "message";
+    /** The worker's initial message / the message sent to it, when parseable. */
+    prompt: string | null;
+    /** The target/spawned worker session id, when parseable from args/output. */
+    workerSessionId: string | null;
+    status: "running" | "complete" | "failed" | "cancelled";
+    occurredAt: string;
+};
+type WorkerCompletionItem = {
+    kind: "worker-completion";
+    id: string;
+    turnId: string | null;
+    occurredAt: string;
+    childSessionId: string;
+    childStatus: string;
+    goalStatus: string | null;
+    goalText: string | null;
+    evidence: string | null;
+    pausedReason: string | null;
+    text: string;
+};
+type SandboxItem = {
+    kind: "sandbox";
+    id: string;
+    turnId: string | null;
+    name: string;
+    command: string | null;
+    output: string;
+    origin?: "created" | "restored" | "resumed" | null;
+    status: "running" | "complete" | "failed" | "cancelled";
+    occurredAt: string;
+};
+/**
+ * A first-party workspace-memory write the agent made mid-turn — a `memory.saved`
+ * (it committed a new preference / fact / procedure / decision / history) or a
+ * `memory.corrected` (it updated or archived an existing one). A settled save is
+ * ordinary progress, not an exceptional state, so it renders as a calm NEUTRAL
+ * step on the rail (never accent/color). When the host app supplies an
+ * `onMemoryClick` handler the row also deep-links to the record in its memory
+ * pane; without one it is non-interactive rich content.
+ */
+type MemoryItem = {
+    kind: "memory";
+    id: string;
+    turnId: string | null;
+    variant: "saved" | "corrected";
+    /** The memory's kind enum (`"preference" | "semantic" | …`); mapped to a human label at render. */
+    memoryKind: string;
+    /** The memory text, ellipsized to ≤120 chars server-side. For a supersede this is the OLD text. */
+    preview: string;
+    /** The save collapsed into an existing memory (no new row was written). Saved variant only. */
+    deduped?: boolean;
+    /** The NEW text when a correction superseded the memory with a replacement; absent = updated-in-place or archived. */
+    replacementPreview?: string;
+    /**
+     * What a `memory.corrected` did: `"superseded"` (replaced by a new record, see
+     * `replacementPreview`), `"updated"` (edited in place — the record lives on), or
+     * `"archived"` (retired). Distinguishes updated-in-place from archived when there
+     * is no replacement. Corrected variant only; read defensively (may be absent).
+     */
+    action?: string;
+    /** The saved / corrected memory's id — the deep-link target for a save. */
+    memoryId: string;
+    /** The replacement memory's id when a correction produced one — the LIVE record the deep-link targets. */
+    replacementMemoryId?: string;
+    occurredAt: string;
+};
+type FleetDecisionScoreItem = {
+    candidateKey: string;
+    eligible: boolean;
+    rejectionReason: "allocator_disabled" | "unavailable" | "cooling" | "quota_ceiling" | "overlay_isolation" | null;
+    total: number;
+    confidence: "unknown" | "low" | "medium" | "high";
+};
+/**
+ * One production-vs-shadow placement explanation. Candidate keys are
+ * event-local aliases only; no credential/account identity reaches this item.
+ */
+type FleetDecisionItem = {
+    kind: "fleet-decision";
+    id: string;
+    turnId: string | null;
+    policyVersion: "adaptive-shadow-v1";
+    actualOutcome: "selected" | "waiting" | "none";
+    actualCandidateKey: string | null;
+    actualReason: "lease_reused" | "pin" | "rotation" | "active" | "all_capped" | "none";
+    shadowOutcome: "selected" | "paced" | "none";
+    shadowCandidateKey: string | null;
+    shadowReason: "fenced_in_flight" | "fenced_candidate_missing" | "admission_paced" | "no_eligible_candidate" | "overlay_isolated_empty" | "best_score" | "affinity_best" | "hysteresis_hold";
+    comparison: "match" | "different_candidate" | "different_outcome" | "not_comparable_truncated";
+    confidence: "unknown" | "low" | "medium" | "high";
+    admissionOutcome: "admit" | "pace";
+    admissionReason: "fenced_in_flight" | "pacing_disabled" | "capacity_unknown" | "capacity_available" | "work_conserving_borrow" | "manager_priority" | "standard_starvation_bound" | "capacity_saturated" | "emergency_fuse";
+    borrowedIdleCapacity: boolean;
+    borrowedOverlayCapacity: boolean;
+    strandedEligibleCount: number;
+    candidateCount: number;
+    truncatedCandidateCount: number;
+    scoreRowsTruncatedCount: number;
+    scores: FleetDecisionScoreItem[];
+    occurredAt: string;
+};
+type SessionStatusItem = {
+    kind: "session-status";
+    id: string;
+    status: SessionStatus;
+    occurredAt: string;
+};
+type GoalItem = {
+    kind: "goal";
+    id: string;
+    action: "set" | "updated" | "completed" | "paused" | "resumed" | "cleared" | "continuation";
+    text: string | null;
+    occurredAt: string;
+};
+type NoticeItem = {
+    kind: "notice";
+    id: string;
+    tone: "waiting" | "cancelled" | "failed";
+    text: string;
+    /** Optional evidence kept inspectable without overwhelming the main rail. */
+    details?: {
+        label: string;
+        value: unknown;
+    };
+    action?: {
+        label: string;
+        url: string;
+    };
+    occurredAt: string;
+};
+/**
+ * A tool call hit a missing or lapsed connection. The broker reports that
+ * condition as a tool error and the turn continues; reconnecting never resumes
+ * or replays the original call. Carries the structured `tool.auth_needed`
+ * payload so the renderer can draw a clean inline recovery affordance (provider
+ * logo + one human line + a Connect/Reconnect button) and the app can start the
+ * right flow (OAuth reconnect for the surviving connection, or credential
+ * re-entry for an api-key one). The `reason` shapes the human copy but is never
+ * shown raw.
+ */
+type AuthNeededItem = {
+    kind: "auth-needed";
+    id: string;
+    turnId: string | null;
+    /** The connection's registrable domain, e.g. "linear.app". */
+    providerDomain: string;
+    /** The lapsed connection to reconnect, when the row survived. */
+    connectionId: string | null;
+    reason: ToolAuthNeededPayload["reason"] | null;
+    /** Scopes the provider now needs; may inform the copy, never shown as a raw label. */
+    scopes: string[];
+    /** The OAuth `resource` (RFC 8707) the reconnect should target, when supplied. */
+    resource: string | null;
+    /** The tool whose call triggered the reauth, for context. */
+    toolName: string | null;
+    /** A pre-minted authorization URL, when the broker already produced one. */
+    authorizationUrl: string | null;
+    occurredAt: string;
+};
+type TurnOutcome = "complete" | "failed" | "cancelled";
+type TurnEndItem = {
+    kind: "turn-end";
+    id: string;
+    turnId: string | null;
+    outcome: TurnOutcome;
+    failureText: string | null;
+    occurredAt: string;
+};
+type TimelineItem = UserMessageItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | WorkerCompletionItem | SandboxItem | SessionStatusItem | GoalItem | NoticeItem | AuthNeededItem | MemoryItem | FleetDecisionItem | TurnEndItem;
+/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox, memory). */
+type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | MemoryItem | FleetDecisionItem;
+type TimelineGroup = {
+    kind: "item";
+    item: TimelineItem;
+} | {
+    kind: "activity";
+    id: string;
+    items: ActivityItem[];
+    outcome?: TurnOutcome;
+    failureText?: string;
+} | {
+    kind: "turn";
+    id: string;
+    outcome: TurnOutcome;
+    failureText?: string;
+    startedAt: string;
+    endedAt: string;
+    groups: TimelineGroup[];
+};
+
+/** Events that can change the authoritative prompt queue or effective control. */
+declare function isTurnQueueEvent(event: Pick<SessionEvent, "type">): boolean;
+type QueueMutationKind = "move" | "edit" | "steer" | "delete";
+type UseTurnQueueOptions = EmbeddedSessionClientOverride & SessionEventFeedOptions & {
+    pollIntervalMs?: number | undefined;
+};
+type UseTurnQueueResult = {
+    snapshot: SessionQueueSnapshot | null;
+    /** Human/API prompts exactly in server execution order. Never client-sorted. */
+    queue: SessionTurn[];
+    effectiveControl: EffectiveSessionControl | null;
+    /** The latest interrupted attempt has not yet durably proved physical quiescence. */
+    stoppingPreviousAttempt: boolean;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    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 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.
+ */
+declare function useTurnQueue(sessionId: string | null | undefined, options?: UseTurnQueueOptions): UseTurnQueueResult;
+
+export { type ActivityItem as A, type GoalItem as G, type MemoryItem as M, type NoticeItem as N, type QueueMutationKind as Q, type ReasoningItem as R, type SandboxItem as S, type TurnOutcome as T, type UseTurnQueueOptions as U, type WorkerItem as W, type AgentMessageItem as a, type AuthNeededItem as b, type SessionStatusItem as c, type TimelineGroup as d, type TimelineItem as e, type ToolCallItem as f, type TurnEndItem as g, type UseTurnQueueResult as h, type UserMessageItem as i, isTurnQueueEvent as j, type WorkerCompletionItem as k, useTurnQueue as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/react",
-  "version": "0.23.0",
+  "version": "0.25.5",
   "description": "React hooks and styled components for OpenGeni: live session streaming, chat composer, message timeline, session status, and fleet views — token-themed (CSS variables), dark-first, built on Tailwind v4 + Radix + Motion.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,6 +31,10 @@
       "types": "./dist/session.d.ts",
       "import": "./dist/session.js"
     },
+    "./session-ui": {
+      "types": "./dist/session-ui.d.ts",
+      "import": "./dist/session-ui.js"
+    },
     "./machines": {
       "types": "./dist/machines.d.ts",
       "import": "./dist/machines.js"
@@ -62,7 +66,7 @@
     "@dnd-kit/utilities": "3.2.2",
     "@fontsource-variable/noto-sans-arabic": "5.2.10",
     "@fontsource-variable/noto-sans-jp": "5.2.10",
-    "@opengeni/sdk": "^0.23.0",
+    "@opengeni/sdk": "^0.25.5",
     "clsx": "^2.1.1",
     "lucide-react": "^1.8.0",
     "motion": "^12.0.0",

package/src/components/composer.tsx

@@ -199,7 +199,7 @@ export const defaultChatComposerMessages: ChatComposerMessages = {
 export type ComposerSubmitMode = "queue" | "steer";
 export type ComposerSubmitBlocker =
   | "disabled"
-  | "uploading"
+  | "attachment"
   | "sending"
   | "command"
   | "empty"
@@ -292,7 +292,7 @@ export function useChatComposerController({
     return () => document.removeEventListener(OPEN_WORKSTREAM_CONTROL_EVENT, openControl);
   }, [id, paused]);
 
-  const blockedByUpload = attachments?.uploading === true;
+  const blockedByAttachment = attachments?.hasUnresolved === true;
   const hasReadyAttachment = (attachments?.readyResources.length ?? 0) > 0;
 
   const [dragging, setDragging] = useState(false);
@@ -386,8 +386,8 @@ export function useChatComposerController({
 
   const submitBlocker: ComposerSubmitBlocker = disabled
     ? "disabled"
-    : blockedByUpload
-      ? "uploading"
+    : blockedByAttachment
+      ? "attachment"
       : delivery.sending || submitting
         ? "sending"
         : commandDraftBlocked
@@ -404,7 +404,8 @@ export function useChatComposerController({
         delivery.clearError();
         return false;
       }
-      if (disabled || blockedByUpload || delivery.sending || submittingRef.current) return false;
+      if (disabled || blockedByAttachment || delivery.sending || submittingRef.current)
+        return false;
       if (!delivery.canSend && !hasReadyAttachment) return false;
       submittingRef.current = true;
       setSubmitting(true);
@@ -416,7 +417,7 @@ export function useChatComposerController({
       }
     },
     [
-      blockedByUpload,
+      blockedByAttachment,
       commandDraftBlocked,
       delivery,
       disabled,

package/src/components/message-timeline.tsx

@@ -150,18 +150,23 @@ export function MessageTimeline({
   // structurally impossible — the reader only ever sees it already at the
   // bottom. An empty timeline reveals immediately (there is nothing to anchor).
   const [revealed, setRevealed] = useState(false);
-  // Our own scrollTop assignments echo back as scroll events; those must never
-  // UNPIN the reader (they are not reader intent). Marked around every
-  // programmatic assignment and consumed by onScroll. When an assignment is a
-  // NO-OP (already at the target) no scroll event will fire, so the mark must
-  // self-clear — a stale mark would eat the reader's next real scroll-up.
-  const programmaticScrollRef = useRef(false);
+  // Our own scrollTop assignments echo back as delayed scroll events. Keep the
+  // ordered, clamped targets rather than only the latest one: successive
+  // ResizeObserver corrections can queue several echoes before the browser
+  // dispatches them. If reader input lands at a different position, its value
+  // wins and clears the pending echoes. A matching echo must not recapture the
+  // visual anchor while progressive prepend is still mounting older rows.
+  const programmaticScrollTargetsRef = useRef<number[]>([]);
   const assignScrollTop = useCallback((node: HTMLElement, value: number) => {
     const previous = node.scrollTop;
-    programmaticScrollRef.current = true;
     node.scrollTop = value;
     if (node.scrollTop === previous) {
-      programmaticScrollRef.current = false;
+      return;
+    }
+    const pending = programmaticScrollTargetsRef.current;
+    pending.push(node.scrollTop);
+    if (pending.length > 32) {
+      pending.splice(0, pending.length - 32);
     }
   }, []);
   // Mirror `pinned` into a ref so the ResizeObserver callback (a stable closure)
@@ -187,9 +192,12 @@ export function MessageTimeline({
     allGroups.length > 0 && (bulkActive || firstKeyChangedForBulk || mountingOlderGroups);
 
   // Snapshot the topmost visible element and where it sits in the viewport, so a
-  // later reflow can restore it to the same spot. Transient chrome (the backfill
-  // sentinel and shimmer) is skipped — anchoring to a row that unmounts when the
-  // older window lands would drop the correction mid-prepend.
+  // later reflow can restore it to the same spot. Prefer durable row wrappers
+  // over their containing group: an older activity item can merge into the
+  // existing group, leaving that outer group in place while shifting every row
+  // after the insertion. Transient chrome (the backfill sentinel and shimmer) is
+  // skipped — anchoring to a row that unmounts when the older window lands would
+  // drop the correction mid-prepend.
   const captureAnchor = useCallback(() => {
     const node = scrollRef.current;
     const inner = node?.firstElementChild;
@@ -198,31 +206,63 @@ export function MessageTimeline({
       return;
     }
     const containerTop = node.getBoundingClientRect().top;
-    for (const child of Array.from(inner.children)) {
-      if (child instanceof HTMLElement && child.dataset.ogTimelineChrome !== undefined) {
-        continue;
-      }
-      const rect = child.getBoundingClientRect();
-      if (rect.bottom > containerTop + 1) {
-        anchorRef.current = { el: child, top: rect.top - containerTop };
-        return;
+    const findVisible = (selector: string): Element | null => {
+      for (const candidate of inner.querySelectorAll(selector)) {
+        if (candidate instanceof HTMLElement && candidate.dataset.ogTimelineChrome !== undefined) {
+          continue;
+        }
+        const rect = candidate.getBoundingClientRect();
+        if (rect.bottom > containerTop + 1 && rect.height > 0) {
+          return candidate;
+        }
       }
+      return null;
+    };
+    const anchor =
+      findVisible("[data-og-timeline-row-anchor]") ??
+      findVisible("[data-og-timeline-group-anchor]");
+    if (anchor) {
+      const rect = anchor.getBoundingClientRect();
+      anchorRef.current = { el: anchor, top: rect.top - containerTop };
+      return;
     }
     anchorRef.current = null;
   }, []);
 
-  // Follow the stream while pinned to the bottom; never fight the reader.
+  // Restore the user-owned anchor synchronously after React commits a frame.
+  // ResizeObserver remains a late-measurement fallback, but progressive history
+  // frames must be corrected before the browser can paint an intermediate jump.
+  const restoreAnchor = useCallback(
+    (node: HTMLElement) => {
+      if (autoFollow && pinnedRef.current) {
+        assignScrollTop(node, node.scrollHeight);
+        return;
+      }
+      const anchor = anchorRef.current;
+      if (!anchor || !anchor.el.isConnected) {
+        return;
+      }
+      const containerTop = node.getBoundingClientRect().top;
+      const now = anchor.el.getBoundingClientRect().top - containerTop;
+      const diff = now - anchor.top;
+      if (diff !== 0) {
+        assignScrollTop(node, node.scrollTop + diff);
+      }
+    },
+    [assignScrollTop, autoFollow],
+  );
+
   // A LAYOUT effect so the very first paint of a freshly loaded session is
   // already anchored at the bottom — no visible traversal down the history.
   useLayoutEffect(() => {
     const node = scrollRef.current;
-    if (node && autoFollow && pinned) {
-      assignScrollTop(node, node.scrollHeight);
+    if (node) {
+      restoreAnchor(node);
     }
     if (!revealed && groups.length > 0) {
       setRevealed(true);
     }
-  }, [resolvedItems, working, autoFollow, pinned, revealed, groups.length, assignScrollTop]);
+  }, [resolvedItems, working, revealed, groups.length, restoreAnchor]);
 
   // A cleared timeline (stream identity change) re-arms the reveal so the next
   // session also first paints at its bottom.
@@ -297,32 +337,26 @@ export function MessageTimeline({
       if (!current) {
         return;
       }
-      if (autoFollow && pinnedRef.current) {
-        assignScrollTop(current, current.scrollHeight);
-      } else {
-        const anchor = anchorRef.current;
-        if (anchor && anchor.el.isConnected) {
-          const containerTop = current.getBoundingClientRect().top;
-          const now = anchor.el.getBoundingClientRect().top - containerTop;
-          const diff = now - anchor.top;
-          if (diff !== 0) {
-            assignScrollTop(current, current.scrollTop + diff);
-          }
-        }
-      }
-      captureAnchor();
+      restoreAnchor(current);
     });
     observer.observe(inner);
     return () => observer.disconnect();
-  }, [autoFollow, captureAnchor, assignScrollTop]);
+  }, [restoreAnchor]);
 
   const onScroll = () => {
     const node = scrollRef.current;
     if (!node) {
       return;
     }
-    const programmatic = programmaticScrollRef.current;
-    programmaticScrollRef.current = false;
+    const pending = programmaticScrollTargetsRef.current;
+    const programmaticIndex = pending.findIndex((target) => Math.abs(node.scrollTop - target) <= 1);
+    const programmatic = programmaticIndex >= 0;
+    if (programmatic) {
+      pending.splice(0, programmaticIndex + 1);
+    } else {
+      // A real reader scroll supersedes every delayed programmatic echo.
+      pending.length = 0;
+    }
     const nextPinned = node.scrollHeight - node.scrollTop - node.clientHeight < 48;
     // Echoes of our own assignments may PIN but never UNPIN — only the reader
     // scrolling away releases the bottom-follow.
@@ -330,7 +364,12 @@ export function MessageTimeline({
       pinnedRef.current = nextPinned;
       setPinned(nextPinned);
     }
-    captureAnchor();
+    // The assignment site already captured the corrected anchor. Recapturing
+    // it from a delayed echo can observe the next prepended row before that
+    // row's ResizeObserver correction and make the viewport walk up the page.
+    if (!programmatic) {
+      captureAnchor();
+    }
   };
 
   return (
@@ -366,17 +405,18 @@ export function MessageTimeline({
                 </div>
               ) : null}
               {groups.map(({ group, key }, index) => (
-                <TimelineGroupView
-                  key={key}
-                  group={group}
-                  renderMessageText={renderMessageText}
-                  onOpenSession={onOpenSession}
-                  onMemoryClick={onMemoryClick}
-                  onReconnect={onReconnect}
-                  resolveProviderLogo={resolveProviderLogo}
-                  toolRegistry={toolRegistry}
-                  foldLiveCluster={isAgentProgress(groups[index + 1]?.group)}
-                />
+                <div key={key} data-og-timeline-group-anchor="">
+                  <TimelineGroupView
+                    group={group}
+                    renderMessageText={renderMessageText}
+                    onOpenSession={onOpenSession}
+                    onMemoryClick={onMemoryClick}
+                    onReconnect={onReconnect}
+                    resolveProviderLogo={resolveProviderLogo}
+                    toolRegistry={toolRegistry}
+                    foldLiveCluster={isAgentProgress(groups[index + 1]?.group)}
+                  />
+                </div>
               ))}
               {working ? (
                 <div className="flex items-center gap-2 text-sm">
@@ -731,8 +771,8 @@ function clusterIsSettled(group: Extract<TimelineGroup, { kind: "activity" }>):
     if (item.kind === "reasoning") {
       return !item.streaming;
     }
-    // A memory write is a discrete, already-settled event — it has no running state.
-    if (item.kind === "memory") {
+    // Memory writes and fleet observations are discrete, already-settled events.
+    if (item.kind === "memory" || item.kind === "fleet-decision") {
       return true;
     }
     return item.status !== "running";