The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(ui): defer Inbox re-sort to attention boundaries (#10623)
Dottaec84eb7342ed
diff --git a/ui/src/hooks/useInboxSortAttention.test.tsx b/ui/src/hooks/useInboxSortAttention.test.tsxnew file mode 100644index 0000000000..b4016e0dd2--- /dev/null+++ b/ui/src/hooks/useInboxSortAttention.test.tsx@@ -0,0 +1,175 @@+// @vitest-environment jsdom++import { useEffect } from "react";+import { flushSync } from "react-dom";+import { createRoot } from "react-dom/client";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import {+ INBOX_SORT_HIDDEN_COMMIT_MS,+ INBOX_SORT_IDLE_COMMIT_MS,+ type InboxSortAttention,+ type InboxSortCommitReason,+ useInboxSortAttention,+} from "./useInboxSortAttention";++type HarnessProps = {+ viewIdentity: string;+ onCommit: (reason: InboxSortCommitReason) => void;+ onReady: (attention: InboxSortAttention) => void;+};++function Harness({ viewIdentity, onCommit, onReady }: HarnessProps) {+ const attention = useInboxSortAttention({ viewIdentity, onCommit });+ useEffect(() => onReady(attention), [attention, onReady]);+ return null;+}++function setVisibility(state: "visible" | "hidden") {+ Object.defineProperty(document, "visibilityState", {+ configurable: true,+ get: () => state,+ });+}++function mountHook(viewIdentity = "mine:all:none") {+ const container = document.createElement("div");+ const root = createRoot(container);+ const onCommit = vi.fn<(reason: InboxSortCommitReason) => void>();+ let attention: InboxSortAttention | null = null;+ const onReady = (value: InboxSortAttention) => {+ attention = value;+ };++ const render = (nextViewIdentity = viewIdentity) => {+ flushSync(() => {+ root.render(+ <Harness+ viewIdentity={nextViewIdentity}+ onCommit={onCommit}+ onReady={onReady}+ />,+ );+ });+ };++ render();+ return {+ onCommit,+ render,+ attention: () => {+ if (!attention) throw new Error("Hook did not mount");+ return attention;+ },+ unmount: () => flushSync(() => root.unmount()),+ };+}++describe("useInboxSortAttention", () => {+ beforeEach(() => {+ vi.useFakeTimers();+ setVisibility("visible");+ });++ afterEach(() => {+ vi.runOnlyPendingTimers();+ vi.useRealTimers();+ setVisibility("visible");+ });++ it("commits after the visible inbox is idle for the threshold", () => {+ const hook = mountHook();+ hook.onCommit.mockClear();++ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS - 1);+ expect(hook.onCommit).not.toHaveBeenCalled();++ vi.advanceTimersByTime(1);+ expect(hook.onCommit).toHaveBeenCalledWith("idle");+ hook.unmount();+ });++ it("keeps committing every interval while the inbox stays idle", () => {+ const hook = mountHook();+ hook.onCommit.mockClear();++ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS);+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS);+ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS);+ // The idle timer re-arms after each fire, so a long-idle inbox never freezes+ // at the first snapshot.+ const idleCalls = hook.onCommit.mock.calls.filter(([reason]) => reason === "idle");+ expect(idleCalls.length).toBe(3);+ hook.unmount();+ });++ it("resets the idle threshold on inbox interaction", () => {+ const hook = mountHook();+ hook.onCommit.mockClear();++ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS - 1_000);+ hook.attention().noteInteraction();+ vi.advanceTimersByTime(1_000);+ expect(hook.onCommit).not.toHaveBeenCalled();++ vi.advanceTimersByTime(INBOX_SORT_IDLE_COMMIT_MS - 1_000);+ expect(hook.onCommit).toHaveBeenCalledWith("idle");+ hook.unmount();+ });++ it("commits after a long hide but not after a brief hide", () => {+ const hook = mountHook();+ hook.onCommit.mockClear();++ setVisibility("hidden");+ document.dispatchEvent(new Event("visibilitychange"));+ vi.advanceTimersByTime(INBOX_SORT_HIDDEN_COMMIT_MS - 1);+ setVisibility("visible");+ document.dispatchEvent(new Event("visibilitychange"));+ expect(hook.onCommit).not.toHaveBeenCalled();++ setVisibility("hidden");+ document.dispatchEvent(new Event("visibilitychange"));+ vi.advanceTimersByTime(INBOX_SORT_HIDDEN_COMMIT_MS);+ setVisibility("visible");+ document.dispatchEvent(new Event("visibilitychange"));+ expect(hook.onCommit).toHaveBeenCalledTimes(1);+ expect(hook.onCommit).toHaveBeenCalledWith("visibility");+ hook.unmount();+ });++ it("always commits when remounted", () => {+ const first = mountHook();+ expect(first.onCommit).toHaveBeenCalledWith("mount");+ first.unmount();++ const second = mountHook();+ expect(second.onCommit).toHaveBeenCalledWith("mount");+ second.unmount();+ });++ it("commits for tab, filter, and group-by identity changes", () => {+ const hook = mountHook();+ hook.onCommit.mockClear();++ hook.render("assigned:open:project");+ hook.render("assigned:closed:project");+ hook.render("assigned:closed:assignee");+ expect(hook.onCommit).toHaveBeenCalledTimes(3);+ expect(hook.onCommit).toHaveBeenNthCalledWith(1, "view-identity-change");+ expect(hook.onCommit).toHaveBeenNthCalledWith(2, "view-identity-change");+ expect(hook.onCommit).toHaveBeenNthCalledWith(3, "view-identity-change");+ hook.unmount();+ });++ it("always commits on manual refresh", () => {+ const hook = mountHook();+ hook.onCommit.mockClear();++ hook.attention().commitManualRefresh();+ hook.attention().commitManualRefresh();+ expect(hook.onCommit).toHaveBeenCalledTimes(2);+ expect(hook.onCommit).toHaveBeenNthCalledWith(1, "manual-refresh");+ expect(hook.onCommit).toHaveBeenNthCalledWith(2, "manual-refresh");+ hook.unmount();+ });+});diff --git a/ui/src/hooks/useInboxSortAttention.ts b/ui/src/hooks/useInboxSortAttention.tsnew file mode 100644index 0000000000..b6de99f0c1--- /dev/null+++ b/ui/src/hooks/useInboxSortAttention.ts@@ -0,0 +1,127 @@+import { useCallback, useEffect, useRef } from "react";++export const INBOX_SORT_IDLE_COMMIT_MS = 150_000;+export const INBOX_SORT_HIDDEN_COMMIT_MS = 30_000;++export type InboxSortCommitReason =+ | "mount"+ | "idle"+ | "visibility"+ | "view-identity-change"+ | "manual-refresh";++type UseInboxSortAttentionOptions = {+ viewIdentity: string;+ onCommit: (reason: InboxSortCommitReason) => void;+ idleCommitMs?: number;+ hiddenCommitMs?: number;+};++export type InboxSortAttention = {+ /** Call for pointer, keyboard, hover, archive, expand/collapse, or scroll activity. */+ noteInteraction: () => void;+ /** Commit immediately at an explicit refresh boundary. */+ commitManualRefresh: () => void;+};++function isDocumentVisible(): boolean {+ return typeof document === "undefined" || document.visibilityState === "visible";+}++/**+ * Owns the attention boundaries at which the inbox may safely adopt a newly+ * computed sort order. The caller owns order reconciliation and calls+ * `noteInteraction` for activity scoped to the inbox list.+ */+export function useInboxSortAttention({+ viewIdentity,+ onCommit,+ idleCommitMs = INBOX_SORT_IDLE_COMMIT_MS,+ hiddenCommitMs = INBOX_SORT_HIDDEN_COMMIT_MS,+}: UseInboxSortAttentionOptions): InboxSortAttention {+ const onCommitRef = useRef(onCommit);+ const idleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);+ const hiddenAtRef = useRef<number | null>(null);+ const committedInitialViewRef = useRef(false);+ const previousViewIdentityRef = useRef(viewIdentity);++ useEffect(() => {+ onCommitRef.current = onCommit;+ }, [onCommit]);++ const clearIdleTimer = useCallback(() => {+ if (idleTimerRef.current !== null) {+ clearTimeout(idleTimerRef.current);+ idleTimerRef.current = null;+ }+ }, []);++ const restartIdleTimer = useCallback(() => {+ clearIdleTimer();+ if (!isDocumentVisible()) return;++ // Re-arm after each idle commit so an inbox left untouched keeps adopting the+ // freshly computed order every interval, rather than freezing at the first+ // idle snapshot until the next interaction or attention boundary.+ const armIdleTimer = () => {+ idleTimerRef.current = setTimeout(() => {+ idleTimerRef.current = null;+ if (!isDocumentVisible()) return;+ onCommitRef.current("idle");+ armIdleTimer();+ }, idleCommitMs);+ };+ armIdleTimer();+ }, [clearIdleTimer, idleCommitMs]);++ const noteInteraction = useCallback(() => {+ restartIdleTimer();+ }, [restartIdleTimer]);++ const commitManualRefresh = useCallback(() => {+ onCommitRef.current("manual-refresh");+ restartIdleTimer();+ }, [restartIdleTimer]);++ useEffect(() => {+ if (!committedInitialViewRef.current) {+ committedInitialViewRef.current = true;+ onCommitRef.current("mount");+ } else if (previousViewIdentityRef.current !== viewIdentity) {+ onCommitRef.current("view-identity-change");+ }++ previousViewIdentityRef.current = viewIdentity;+ restartIdleTimer();+ return clearIdleTimer;+ }, [clearIdleTimer, restartIdleTimer, viewIdentity]);++ useEffect(() => {+ if (typeof document === "undefined") return;++ if (document.visibilityState !== "visible") {+ hiddenAtRef.current = Date.now();+ clearIdleTimer();+ }++ const handleVisibilityChange = () => {+ if (document.visibilityState !== "visible") {+ hiddenAtRef.current = Date.now();+ clearIdleTimer();+ return;+ }++ const hiddenAt = hiddenAtRef.current;+ hiddenAtRef.current = null;+ if (hiddenAt !== null && Date.now() - hiddenAt >= hiddenCommitMs) {+ onCommitRef.current("visibility");+ }+ restartIdleTimer();+ };++ document.addEventListener("visibilitychange", handleVisibilityChange);+ return () => document.removeEventListener("visibilitychange", handleVisibilityChange);+ }, [clearIdleTimer, hiddenCommitMs, restartIdleTimer]);++ return { noteInteraction, commitManualRefresh };+}diff --git a/ui/src/lib/inboxArchiveCache.ts b/ui/src/lib/inboxArchiveCache.tsindex 92b185f936..1f8dd12ffa 100644--- a/ui/src/lib/inboxArchiveCache.ts+++ b/ui/src/lib/inboxArchiveCache.ts@@ -5,7 +5,7 @@ import { queryKeys } from "./queryKeys";export type InboxIssueCacheSnapshot = Array<readonly [QueryKey, Issue[] | undefined]>;-const INBOX_ARCHIVE_CONFIRMATION_GRACE_MS = 5_000;+export const INBOX_ARCHIVE_CONFIRMATION_GRACE_MS = 5_000;const INBOX_ARCHIVE_MAX_GUARD_MS = 30_000;const EMPTY_ARCHIVED_ISSUE_IDS: ReadonlySet<string> = new Set();diff --git a/ui/src/lib/inboxOrderPin.test.ts b/ui/src/lib/inboxOrderPin.test.tsnew file mode 100644index 0000000000..30d3269d26--- /dev/null+++ b/ui/src/lib/inboxOrderPin.test.ts@@ -0,0 +1,230 @@+import type { Approval, HeartbeatRun, Issue, JoinRequest } from "@paperclipai/shared";+import { describe, expect, it } from "vitest";+import {+ getInboxWorkItemKey,+ type InboxGroupedSection,+ type InboxWorkItem,+} from "./inbox";+import { INBOX_ARCHIVE_CONFIRMATION_GRACE_MS } from "./inboxArchiveCache";+import {+ captureInboxOrderPin,+ reconcileInboxOrderPin,+} from "./inboxOrderPin";++function issue(id: string, title = id): Issue {+ return {+ id,+ title,+ status: "todo",+ } as Issue;+}++function issueItem(value: Issue, timestamp = 0): InboxWorkItem {+ return { kind: "issue", issue: value, timestamp };+}++function section(+ key: string,+ items: Issue[],+ childrenByIssueId: ReadonlyArray<readonly [string, Issue[]]> = [],+): InboxGroupedSection {+ return {+ key,+ label: key,+ displayItems: items.map((item) => issueItem(item)),+ childrenByIssueId: new Map(childrenByIssueId),+ searchSection: "none",+ };+}++function sectionKeys(sections: readonly InboxGroupedSection[]): string[] {+ return sections.map((value) => value.key);+}++function workItemSection(key: string, displayItems: InboxWorkItem[]): InboxGroupedSection {+ return {+ key,+ label: key,+ displayItems,+ childrenByIssueId: new Map(),+ searchSection: "none",+ };+}++function rowIds(value: InboxGroupedSection): string[] {+ return value.displayItems.map((item) => item.kind === "issue" ? item.issue.id : "non-issue");+}++describe("inboxOrderPin", () => {+ it("keeps a parent, its group, and neighboring groups in place when a child is archived", () => {+ const parent = issue("parent");+ const child = issue("child");+ const neighbor = issue("neighbor");+ const committed = [+ section("parent-group", [parent], [[parent.id, [child]]]),+ section("neighbor-group", [neighbor]),+ ];+ const pin = captureInboxOrderPin(committed);++ const fresh = [+ section("neighbor-group", [neighbor]),+ section("parent-group", [parent], [[parent.id, []]]),+ ];+ const result = reconcileInboxOrderPin(pin, fresh, 100);++ expect(sectionKeys(result.sections)).toEqual(["parent-group", "neighbor-group"]);+ expect(rowIds(result.sections[0]!)).toEqual([parent.id]);+ expect(result.sections[0]!.childrenByIssueId.get(parent.id)).toEqual([]);+ });++ it("removes a group in place when its last row is archived", () => {+ const archived = issue("archived");+ const neighbor = issue("neighbor");+ const pin = captureInboxOrderPin([+ section("archived-group", [archived]),+ section("neighbor-group", [neighbor]),+ ]);++ const result = reconcileInboxOrderPin(+ pin,+ [section("neighbor-group", [neighbor])],+ 200,+ );++ expect(sectionKeys(result.sections)).toEqual(["neighbor-group"]);+ expect(rowIds(result.sections[0]!)).toEqual([neighbor.id]);+ expect(result.pin.sections.map((value) => [value.key, value.missingSince])).toEqual([+ ["archived-group", 200],+ ["neighbor-group", null],+ ]);+ });++ it("restores an archived row to its original position within the tombstone grace window", () => {+ const first = issue("first");+ const restored = issue("restored");+ const last = issue("last");+ const pin = captureInboxOrderPin([section("group", [first, restored, last])]);+ const archived = reconcileInboxOrderPin(pin, [section("group", [last, first])], 1_000);++ expect(rowIds(archived.sections[0]!)).toEqual([first.id, last.id]);++ const undone = reconcileInboxOrderPin(+ archived.pin,+ [section("group", [last, restored, first])],+ 1_000 + INBOX_ARCHIVE_CONFIRMATION_GRACE_MS - 1,+ );++ expect(rowIds(undone.sections[0]!)).toEqual([first.id, restored.id, last.id]);+ expect(undone.pin.sections[0]!.rows.every((entry) => entry.missingSince === null)).toBe(true);+ });++ it("treats a row restored after the grace window as a new algorithmic insertion", () => {+ const first = issue("first");+ const expired = issue("expired");+ const last = issue("last");+ const pin = captureInboxOrderPin([section("group", [first, expired, last])]);+ const archived = reconcileInboxOrderPin(pin, [section("group", [last, first])], 1_000);++ const restored = reconcileInboxOrderPin(+ archived.pin,+ [section("group", [last, first, expired])],+ 1_000 + INBOX_ARCHIVE_CONFIRMATION_GRACE_MS,+ );++ expect(rowIds(restored.sections[0]!)).toEqual([first.id, last.id, expired.id]);+ });++ it("inserts new rows and groups algorithmically without reordering existing entries", () => {+ const first = issue("first");+ const last = issue("last");+ const inserted = issue("inserted");+ const neighbor = issue("neighbor");+ const newGroupItem = issue("new-group-item");+ const pin = captureInboxOrderPin([+ section("existing", [first, last]),+ section("neighbor", [neighbor]),+ ]);++ const result = reconcileInboxOrderPin(+ pin,+ [+ section("neighbor", [neighbor]),+ section("new-group", [newGroupItem]),+ section("existing", [last, inserted, first]),+ ],+ 300,+ );++ expect(sectionKeys(result.sections)).toEqual(["existing", "new-group", "neighbor"]);+ expect(rowIds(result.sections[0]!)).toEqual([first.id, inserted.id, last.id]);+ });++ it("uses fresh row content while retaining the pinned order", () => {+ const first = issue("first", "Old first");+ const last = issue("last", "Old last");+ const pin = captureInboxOrderPin([section("group", [first, last])]);+ const freshLast = { ...last, title: "Updated last", status: "in_progress" } as Issue;+ const freshFirst = { ...first, title: "Updated first", status: "blocked" } as Issue;++ const result = reconcileInboxOrderPin(+ pin,+ [section("group", [freshLast, freshFirst])],+ 400,+ );++ expect(rowIds(result.sections[0]!)).toEqual([first.id, last.id]);+ expect(result.sections[0]!.displayItems[0]).toBeDefined();+ expect(result.sections[0]!.displayItems[0]!.kind).toBe("issue");+ expect(result.sections[0]!.displayItems[0]).toMatchObject({+ issue: { title: "Updated first", status: "blocked" },+ });+ expect(result.sections[0]!.displayItems[1]).toMatchObject({+ issue: { title: "Updated last", status: "in_progress" },+ });+ });++ it("pins approval, failed-run, and join-request rows by their stable keys", () => {+ const approval = {+ kind: "approval",+ timestamp: 3,+ approval: { id: "approval", status: "pending" } as Approval,+ } satisfies InboxWorkItem;+ const failedRun = {+ kind: "failed_run",+ timestamp: 2,+ run: { id: "run", status: "failed" } as HeartbeatRun,+ } satisfies InboxWorkItem;+ const joinRequest = {+ kind: "join_request",+ timestamp: 1,+ joinRequest: { id: "join", status: "pending_approval" } as JoinRequest,+ } satisfies InboxWorkItem;+ const pin = captureInboxOrderPin([+ workItemSection("mixed", [approval, failedRun, joinRequest]),+ ]);++ const result = reconcileInboxOrderPin(+ pin,+ [workItemSection("mixed", [+ { ...joinRequest, timestamp: 4 },+ { ...failedRun, timestamp: 5 },+ {+ ...approval,+ timestamp: 6,+ approval: { ...approval.approval, status: "approved" } as Approval,+ },+ ])],+ 500,+ );++ expect(result.sections[0]!.displayItems.map(getInboxWorkItemKey)).toEqual([+ "approval:approval",+ "run:run",+ "join:join",+ ]);+ expect(result.sections[0]!.displayItems[0]).toMatchObject({+ timestamp: 6,+ approval: { status: "approved" },+ });+ });+});diff --git a/ui/src/lib/inboxOrderPin.ts b/ui/src/lib/inboxOrderPin.tsnew file mode 100644index 0000000000..db62c80515--- /dev/null+++ b/ui/src/lib/inboxOrderPin.ts@@ -0,0 +1,242 @@+import type { Issue } from "@paperclipai/shared";+import {+ getInboxWorkItemKey,+ type InboxGroupedSection,+ type InboxWorkItem,+} from "./inbox";+import { INBOX_ARCHIVE_CONFIRMATION_GRACE_MS } from "./inboxArchiveCache";++export interface InboxPinnedKey {+ key: string;+ missingSince: number | null;+}++export interface InboxPinnedSectionOrder extends InboxPinnedKey {+ rows: readonly InboxPinnedKey[];+ childrenByIssueId: ReadonlyMap<string, readonly InboxPinnedKey[]>;+}++export interface InboxOrderPin {+ sections: readonly InboxPinnedSectionOrder[];+}++export interface InboxOrderPinReconcileResult {+ sections: InboxGroupedSection[];+ pin: InboxOrderPin;+}++interface ReconciledKeys {+ entries: InboxPinnedKey[];+ retainedPinnedKeys: ReadonlySet<string>;+ visibleKeys: string[];+}++function inboxOrderRowKey(item: InboxWorkItem): string {+ return item.kind === "issue" ? item.issue.id : getInboxWorkItemKey(item);+}++function captureKeys(keys: Iterable<string>): InboxPinnedKey[] {+ return Array.from(keys, (key) => ({ key, missingSince: null }));+}++function captureSection(section: InboxGroupedSection): InboxPinnedSectionOrder {+ return {+ key: section.key,+ missingSince: null,+ rows: captureKeys(section.displayItems.map(inboxOrderRowKey)),+ childrenByIssueId: new Map(+ Array.from(section.childrenByIssueId, ([issueId, children]) => [+ issueId,+ captureKeys(children.map((child) => child.id)),+ ]),+ ),+ };+}++export function captureInboxOrderPin(+ sections: readonly InboxGroupedSection[],+): InboxOrderPin {+ return { sections: sections.map(captureSection) };+}++function insertionIndexForVisiblePosition(+ entries: readonly InboxPinnedKey[],+ visibleKeys: ReadonlySet<string>,+ visibleIndex: number,+): number {+ let seenVisible = 0;+ for (let index = 0; index < entries.length; index += 1) {+ if (seenVisible === visibleIndex) return index;+ if (visibleKeys.has(entries[index]!.key)) seenVisible += 1;+ }+ return entries.length;+}++function reconcileKeys(+ pinned: readonly InboxPinnedKey[],+ freshKeys: readonly string[],+ nowMs: number,+): ReconciledKeys {+ const freshKeySet = new Set(freshKeys);+ const entries = pinned.flatMap((entry): InboxPinnedKey[] => {+ if (freshKeySet.has(entry.key)) {+ return entry.missingSince === null+ || nowMs - entry.missingSince < INBOX_ARCHIVE_CONFIRMATION_GRACE_MS+ ? [{ key: entry.key, missingSince: null }]+ : [];+ }++ const missingSince = entry.missingSince ?? nowMs;+ return nowMs - missingSince < INBOX_ARCHIVE_CONFIRMATION_GRACE_MS+ ? [{ key: entry.key, missingSince }]+ : [];+ });+ const retainedPinnedKeys = new Set(entries.map((entry) => entry.key));++ const visibleKeys = new Set(+ entries+ .filter((entry) => entry.missingSince === null)+ .map((entry) => entry.key),+ );++ freshKeys.forEach((key, freshIndex) => {+ if (retainedPinnedKeys.has(key)) return;+ const insertionIndex = insertionIndexForVisiblePosition(entries, visibleKeys, freshIndex);+ entries.splice(insertionIndex, 0, { key, missingSince: null });+ visibleKeys.add(key);+ });++ return {+ entries,+ retainedPinnedKeys,+ visibleKeys: entries+ .filter((entry) => entry.missingSince === null)+ .map((entry) => entry.key),+ };+}++function reconcileChildren(+ pinned: ReadonlyMap<string, readonly InboxPinnedKey[]>,+ fresh: ReadonlyMap<string, Issue[]>,+ nowMs: number,+): {+ pin: ReadonlyMap<string, readonly InboxPinnedKey[]>;+ display: Map<string, Issue[]>;+} {+ const parentIssueIds = new Set([...pinned.keys(), ...fresh.keys()]);+ const nextPin = new Map<string, readonly InboxPinnedKey[]>();+ const display = new Map<string, Issue[]>();++ for (const parentIssueId of parentIssueIds) {+ const freshChildren = fresh.get(parentIssueId) ?? [];+ const freshChildById = new Map(freshChildren.map((child) => [child.id, child]));+ const reconciled = reconcileKeys(+ pinned.get(parentIssueId) ?? [],+ freshChildren.map((child) => child.id),+ nowMs,+ );++ if (reconciled.entries.length > 0) {+ nextPin.set(parentIssueId, reconciled.entries);+ }+ if (fresh.has(parentIssueId)) {+ display.set(+ parentIssueId,+ reconciled.visibleKeys.flatMap((key) => {+ const child = freshChildById.get(key);+ return child ? [child] : [];+ }),+ );+ }+ }++ return { pin: nextPin, display };+}++function reconcileSection(+ pinned: InboxPinnedSectionOrder | undefined,+ fresh: InboxGroupedSection,+ nowMs: number,+): { pin: InboxPinnedSectionOrder; display: InboxGroupedSection } {+ if (!pinned) {+ return { pin: captureSection(fresh), display: fresh };+ }++ const freshItemByKey = new Map(+ fresh.displayItems.map((item) => [inboxOrderRowKey(item), item]),+ );+ const rows = reconcileKeys(+ pinned.rows,+ fresh.displayItems.map(inboxOrderRowKey),+ nowMs,+ );+ const children = reconcileChildren(pinned.childrenByIssueId, fresh.childrenByIssueId, nowMs);++ return {+ pin: {+ key: fresh.key,+ missingSince: null,+ rows: rows.entries,+ childrenByIssueId: children.pin,+ },+ display: {+ ...fresh,+ displayItems: rows.visibleKeys.flatMap((key) => {+ const item = freshItemByKey.get(key);+ return item ? [item] : [];+ }),+ childrenByIssueId: children.display,+ },+ };+}++/**+ * Applies a previously committed Inbox order to freshly computed sections.+ *+ * `nowMs` is explicit so reconciliation remains pure. Callers should retain the+ * returned pin between reconciliations and replace it with `captureInboxOrderPin`+ * at an attention/refresh commit point.+ */+export function reconcileInboxOrderPin(+ pinned: InboxOrderPin,+ freshSections: readonly InboxGroupedSection[],+ nowMs: number,+): InboxOrderPinReconcileResult {+ const freshSectionByKey = new Map(freshSections.map((section) => [section.key, section]));+ const sections = reconcileKeys(+ pinned.sections,+ freshSections.map((section) => section.key),+ nowMs,+ );+ const pinnedSectionByKey = new Map(pinned.sections.map((section) => [section.key, section]));+ const reconciledByKey = new Map<string, ReturnType<typeof reconcileSection>>();++ for (const freshSection of freshSections) {+ reconciledByKey.set(+ freshSection.key,+ reconcileSection(+ sections.retainedPinnedKeys.has(freshSection.key)+ ? pinnedSectionByKey.get(freshSection.key)+ : undefined,+ freshSection,+ nowMs,+ ),+ );+ }++ const nextPinnedSections = sections.entries.flatMap((entry): InboxPinnedSectionOrder[] => {+ const reconciled = reconciledByKey.get(entry.key);+ if (reconciled) return [{ ...reconciled.pin, missingSince: entry.missingSince }];+ const previous = pinnedSectionByKey.get(entry.key);+ return previous ? [{ ...previous, missingSince: entry.missingSince }] : [];+ });++ return {+ sections: sections.visibleKeys.flatMap((key) => {+ const freshSection = freshSectionByKey.get(key);+ if (!freshSection) return [];+ return [reconciledByKey.get(key)?.display ?? freshSection];+ }),+ pin: { sections: nextPinnedSections },+ };+}diff --git a/ui/src/pages/Inbox.test.tsx b/ui/src/pages/Inbox.test.tsxindex 48a3deccea..69518d147f 100644--- a/ui/src/pages/Inbox.test.tsx+++ b/ui/src/pages/Inbox.test.tsx@@ -631,6 +631,107 @@ describe("Inbox toolbar", () => {}});+ it("holds the inbox order across a reordering poll, then re-sorts at an attention boundary (PAP-16015)", async () => {+ routerMock.location.pathname = "/inbox/mine";+ const base = new Date("2026-03-11T00:00:00.000Z").getTime();+ const issueA = createIssue({+ id: "issue-a",+ identifier: "PAP-3001",+ title: "Pin row A",+ lastActivityAt: new Date(base + 3000),+ });+ const issueB = createIssue({+ id: "issue-b",+ identifier: "PAP-3002",+ title: "Pin row B",+ lastActivityAt: new Date(base + 2000),+ });+ const issueC = createIssue({+ id: "issue-c",+ identifier: "PAP-3003",+ title: "Pin row C",+ lastActivityAt: new Date(base + 1000),+ });+ apiMocks.issuesList.mockResolvedValue([issueA, issueB, issueC]);++ const queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false, staleTime: 0, gcTime: 0 } },+ });+ const root = createRoot(container);++ // Collapse each displayed row to its A/B/C identity so we can assert order.+ const orderOf = () =>+ [...container.querySelectorAll("[data-inbox-item]")].flatMap((row) => {+ const text = row.textContent ?? "";+ if (text.includes("Pin row A")) return ["A"];+ if (text.includes("Pin row B")) return ["B"];+ if (text.includes("Pin row C")) return ["C"];+ return [];+ });++ const visibilityDescriptor = Object.getOwnPropertyDescriptor(document, "visibilityState");+ const setVisibility = (state: DocumentVisibilityState) => {+ Object.defineProperty(document, "visibilityState", { configurable: true, get: () => state });+ };+ let nowValue = base + 1_000_000;+ const nowSpy = vi.spyOn(Date, "now").mockImplementation(() => nowValue);++ try {+ await act(async () => {+ root.render(+ <QueryClientProvider client={queryClient}>+ <Inbox />+ </QueryClientProvider>,+ );+ });+ await vi.waitFor(() => {+ expect(container.querySelectorAll("[data-inbox-item]").length).toBeGreaterThanOrEqual(3);+ });+ expect(orderOf()).toEqual(["A", "B", "C"]);++ // A poll makes row C the most-recently-active: the fresh sort is now [C, A, B].+ apiMocks.issuesList.mockResolvedValue([+ { ...issueA },+ { ...issueB },+ { ...issueC, lastActivityAt: new Date(base + 9000) },+ ]);+ await act(async () => {+ await queryClient.invalidateQueries();+ });+ await vi.waitFor(() => {+ expect(container.textContent).toContain("Pin row C");+ });++ // No attention boundary has fired, so the displayed order is held, not reshuffled.+ expect(orderOf()).toEqual(["A", "B", "C"]);++ // The tab is hidden long enough to lose attention, then regains focus: that+ // visibility boundary is a commit point, so the inbox adopts the fresh order.+ await act(async () => {+ setVisibility("hidden");+ document.dispatchEvent(new Event("visibilitychange"));+ });+ nowValue += 31_000;+ await act(async () => {+ setVisibility("visible");+ document.dispatchEvent(new Event("visibilitychange"));+ });+ await vi.waitFor(() => {+ expect(orderOf()).toEqual(["C", "A", "B"]);+ });+ } finally {+ nowSpy.mockRestore();+ if (visibilityDescriptor) {+ Object.defineProperty(document, "visibilityState", visibilityDescriptor);+ } else {+ setVisibility("visible");+ }+ act(() => {+ root.unmount();+ });+ }+ });+it("keeps other issue archive controls enabled while one archive is pending", async () => {routerMock.location.pathname = "/inbox/mine";const issueA = createIssue({ id: "issue-a", identifier: "PAP-1001", title: "First inbox row" });diff --git a/ui/src/pages/Inbox.tsx b/ui/src/pages/Inbox.tsxindex b50aace18d..2cfa3569c3 100644--- a/ui/src/pages/Inbox.tsx+++ b/ui/src/pages/Inbox.tsx@@ -173,6 +173,12 @@ import {type InboxWorkItemGroupBy,} from "../lib/inbox";import { useDismissedInboxAlerts, useInboxDismissals, useReadInboxItems } from "../hooks/useInboxBadge";+import { useInboxSortAttention } from "../hooks/useInboxSortAttention";+import {+ captureInboxOrderPin,+ reconcileInboxOrderPin,+ type InboxOrderPin,+} from "../lib/inboxOrderPin";const INBOX_HEARTBEAT_RUN_LIMIT = 200;const INBOX_ISSUE_LIST_LIMIT = 500;@@ -1379,7 +1385,7 @@ export function Inbox() {return next;});}, [selectedCompanyId]);- const groupedSections = useMemo<InboxGroupedSection[]>(() => [+ const freshGroupedSections = useMemo<InboxGroupedSection[]>(() => [...buildGroupedInboxSections(filteredWorkItems, groupBy, inboxWorkspaceGrouping, { nestingEnabled }),...buildGroupedInboxSections(getInboxWorkItems({ issues: archivedSearchIssues, approvals: [] }),@@ -1402,6 +1408,79 @@ export function Inbox() {nestingEnabled,]);+ // --- Order pinning (PAP-16015) ---+ // The freshly computed sort is only *displayed* at attention boundaries. Between+ // them we reconcile the fresh sections against the last committed order so that+ // archiving mid-engagement (which drops rows from the caches, and can lower a+ // parent's subtree-max sort ts) can no longer reshuffle the list under the+ // cursor. New items still land at their algorithmic position; archived rows hold+ // their slot for the 5s undo grace before collapsing. See `inboxOrderPin.ts`.+ const orderPinRef = useRef<InboxOrderPin>({ sections: [] });+ // Bumped by an attention commit to force `groupedSections` to adopt the fresh order.+ const [orderCommitToken, setOrderCommitToken] = useState(0);+ const orderCommitRequestedRef = useRef(false);+ const commitInboxOrder = useCallback(() => {+ orderCommitRequestedRef.current = true;+ setOrderCommitToken((token) => token + 1);+ }, []);++ // Distinct view = distinct pin. Switching tab/filter/search/grouping resets the+ // held order so we never carry one view's layout into another.+ const inboxSortViewIdentity = useMemo(+ () =>+ JSON.stringify([+ selectedCompanyId,+ tab,+ groupBy,+ nestingEnabled,+ normalizedSearchQuery,+ allCategoryFilter,+ allApprovalFilter,+ issueFilters,+ ]),+ [+ allApprovalFilter,+ allCategoryFilter,+ groupBy,+ issueFilters,+ nestingEnabled,+ normalizedSearchQuery,+ selectedCompanyId,+ tab,+ ],+ );+ // Adopt the fresh order in the SAME render the view identity changes, so a+ // section key shared between the two views never briefly shows the previous+ // view's order before the hook's passive commit effect runs.+ const previousInboxSortViewIdentityRef = useRef(inboxSortViewIdentity);+ if (previousInboxSortViewIdentityRef.current !== inboxSortViewIdentity) {+ previousInboxSortViewIdentityRef.current = inboxSortViewIdentity;+ orderCommitRequestedRef.current = true;+ }++ const groupedSections = useMemo<InboxGroupedSection[]>(() => {+ const nowMs = Date.now();+ // An attention boundary (or a view change) fired: adopt the fresh order+ // wholesale and re-pin it.+ if (orderCommitRequestedRef.current) {+ orderCommitRequestedRef.current = false;+ orderPinRef.current = captureInboxOrderPin(freshGroupedSections);+ return freshGroupedSections;+ }+ const { sections, pin } = reconcileInboxOrderPin(orderPinRef.current, freshGroupedSections, nowMs);+ orderPinRef.current = pin;+ return sections;+ // orderCommitToken forces re-adoption at a commit boundary; inboxSortViewIdentity+ // forces it on a view change even when the fresh sections keep their identity.+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, [freshGroupedSections, inboxSortViewIdentity, orderCommitToken]);++ const inboxSortAttention = useInboxSortAttention({+ viewIdentity: inboxSortViewIdentity,+ onCommit: commitInboxOrder,+ });+ const noteInboxSortInteraction = inboxSortAttention.noteInteraction;+const openCreateIssueForGroup = useCallback((group: InboxGroupedSection) => {const defaults = buildInboxIssueGroupCreateDefaults(group.key,@@ -1654,13 +1733,14 @@ export function Inbox() {const hoveredNavKeyRef = useRef<string | null>(null);const setSelectedIndexFromPointer = useCallback((idx: number) => {if (!pointerMovedSinceKeyNavRef.current) return;+ noteInboxSortInteraction();hoveredIndexRef.current = idx;hoveredNavKeyRef.current = navEntryKey(flatNavItemsRef.current[idx]);// Drop any keyboard selection band the moment the mouse takes over, so we// never show two identical highlights at once. React bails out when the// value is already -1, so continuous hovering triggers no re-render.setSelectedIndex((prev) => (prev < 0 ? prev : -1));- }, []);+ }, [noteInboxSortInteraction]);const invalidateInboxIssueQueryCaches = () => {if (!selectedCompanyId) return;@@ -1670,6 +1750,8 @@ export function Inbox() {const archiveIssueMutation = useMutation({mutationFn: (id: string) => issuesApi.archiveFromInbox(id),onMutate: async (id) => {+ // Keep the sort pinned: archiving is engagement, so defer any idle re-sort.+ noteInboxSortInteraction();setActionError(null);setArchivingIssueIds((prev) => new Set(prev).add(id));@@ -1810,6 +1892,7 @@ export function Inbox() {}, [markItemRead]);const handleArchiveNonIssue = useCallback((key: string) => {+ noteInboxSortInteraction();setArchivingNonIssueIds((prev) => new Set(prev).add(key));setTimeout(() => {if (key.startsWith("alert:")) {@@ -1823,7 +1906,7 @@ export function Inbox() {return next;});}, 200);- }, [dismissAlert, dismissInboxItem]);+ }, [dismissAlert, dismissInboxItem, noteInboxSortInteraction]);const nonIssueUnreadState = (key: string): NonIssueUnreadState => {if (!canArchiveFromTab) return null;@@ -1973,6 +2056,9 @@ export function Inbox() {const navCount = navItems.length;if (navCount === 0) return;+ // Any inbox keystroke (nav, archive, undo) is engagement: hold the sort.+ noteInboxSortInteraction();+/** Resolve the nav entry at an index to an issue (for child entries) or work item. */const resolveNavEntry = (idx: number): { issue?: Issue; item?: InboxWorkItem } => {const entry = navItems[idx];@@ -2115,7 +2201,7 @@ export function Inbox() {};window.addEventListener("keydown", handleKeyDown);return () => window.removeEventListener("keydown", handleKeyDown);- }, [issueLinkState, keyboardShortcutsEnabled]);+ }, [issueLinkState, keyboardShortcutsEnabled, noteInboxSortInteraction]);// Scroll selected item into viewuseEffect(() => {@@ -2544,7 +2630,12 @@ export function Inbox() {<>{showSeparatorBefore("work_items") && <Separator />}<div>- <div ref={listRef} className="overflow-hidden">+ <div+ ref={listRef}+ className="overflow-hidden"+ onPointerDownCapture={noteInboxSortInteraction}+ onWheelCapture={noteInboxSortInteraction}+ >{(() => {const renderInboxIssue = ({issue,