Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(web): quiet offline refresh errors for cached sidebars (#7516)

Sean Aye6e0ad170da8b
diff --git a/apps/web/src/features/projects/queries/project-soup.test.ts b/apps/web/src/features/projects/queries/project-soup.test.ts
index 8cead1e373..3659ed48e0 100644
--- a/apps/web/src/features/projects/queries/project-soup.test.ts
+++ b/apps/web/src/features/projects/queries/project-soup.test.ts
@@ -21,6 +21,7 @@ vi.mock('@entity/extractors-property/property-helpers', () => ({
}));
import type { SoupQuery } from '@service-storage/graphql/generated/graphql';
+import type { ProjectFilters } from '../core/project';
import {
createProjectSoupSource,
projectSoupInput,
@@ -103,6 +104,106 @@ describe('project Soup source', () => {
expect(second.rows()?.[0].project.id).toBe('cached');
refresh.resolve();
});
+ function offlineFixture(empty = false) {
+ let failure: CombinedError | undefined;
+ const [filters, setFilters] = createSignal<ProjectFilters>({
+ sort: 'updated',
+ });
+ const exchange: Exchange = () => (operations) =>
+ pipe(
+ operations,
+ mergeMap((operation) =>
+ fromPromise(
+ Promise.resolve({
+ operation,
+ error: failure,
+ data: failure
+ ? undefined
+ : {
+ user: {
+ id: 'viewer',
+ soup: {
+ items: empty ? [] : [initiative('cached')],
+ nextCursor: 'next',
+ },
+ },
+ },
+ stale: false,
+ hasNext: false,
+ })
+ )
+ )
+ );
+ const client = createClient({
+ url: 'http://test.invalid/graphql',
+ exchanges: [cacheExchange, exchange],
+ });
+ const source = createRoot((cleanup) => {
+ dispose = cleanup;
+ return createProjectSoupSource(
+ () => client,
+ filters,
+ () => true
+ );
+ });
+ return {
+ source,
+ setFilters,
+ fail: (error: CombinedError) => {
+ failure = error;
+ },
+ };
+ }
+
+ it.each([false, true])(
+ 'keeps a cached collection quiet on refresh failure (empty=%s)',
+ async (empty) => {
+ const f = offlineFixture(empty);
+ await vi.waitFor(() =>
+ expect(f.source.rows()).toHaveLength(empty ? 0 : 1)
+ );
+ const error = new CombinedError({
+ networkError: new TypeError('Failed to fetch'),
+ });
+ f.fail(error);
+ await expect(f.source.refresh()).rejects.toBe(error);
+ expect(f.source.rows()).toHaveLength(empty ? 0 : 1);
+ expect(f.source.error()).toBeUndefined();
+ }
+ );
+
+ it('keeps errors for uncached filters and pagination visible', async () => {
+ const f = offlineFixture();
+ await vi.waitFor(() => expect(f.source.rows()).toHaveLength(1));
+ const error = new CombinedError({
+ networkError: new TypeError('Failed to fetch'),
+ });
+ f.fail(error);
+ await f.source.loadMore();
+ expect(f.source.rows()).toHaveLength(1);
+ expect(f.source.error()).toBe(error);
+ f.setFilters({ query: 'not cached' });
+ await vi.waitFor(() => expect(f.source.error()).toBe(error));
+ expect(f.source.rows()).toBeUndefined();
+ });
+
+ it.each([
+ new CombinedError({ graphQLErrors: ['Forbidden'] }),
+ ...[401, 403, 503].map(
+ (status) =>
+ new CombinedError({
+ networkError: new Error('HTTP failure'),
+ response: { status },
+ })
+ ),
+ ])('preserves server errors alongside cached projects: %s', async (error) => {
+ const f = offlineFixture();
+ await vi.waitFor(() => expect(f.source.rows()).toHaveLength(1));
+ f.fail(error);
+ await expect(f.source.refresh()).rejects.toBe(error);
+ expect(f.source.error()).toBe(error);
+ });
+
it('scopes all filters to initiatives and excludes folders and task documents', () => {
const input = projectSoupInput({
query: 'Roadmap',
diff --git a/apps/web/src/features/projects/queries/project-soup.ts b/apps/web/src/features/projects/queries/project-soup.ts
index 9c32e6364d..d82974960b 100644
--- a/apps/web/src/features/projects/queries/project-soup.ts
+++ b/apps/web/src/features/projects/queries/project-soup.ts
@@ -1,4 +1,5 @@
import { createUrqlInfiniteQuery } from '@app/lib/urql-solid';
+import { isResponseFreeNetworkError } from '@core/util/request-error';
import { SYSTEM_PROPERTY_IDS } from '@property/identifiers';
import { registerActivityRevalidator } from '@queries/activity/push-registry';
import {
@@ -188,7 +189,19 @@ export function createProjectSoupSource(
: undefined;
},
loading: () => enabled() && query.isPending,
- error: () => (enabled() ? (query.error ?? undefined) : undefined),
+ error: () => {
+ if (!enabled()) return undefined;
+ // keepPreviousData=false fences filter changes. A complete cached page,
+ // including an empty one, remains usable when only its refresh failed.
+ if (
+ isResponseFreeNetworkError(query.error) &&
+ query.data !== undefined &&
+ !query.isFetchNextPageError
+ ) {
+ return undefined;
+ }
+ return query.error ?? undefined;
+ },
hasMore: () => enabled() && query.hasNextPage,
loadingMore: () => enabled() && query.isFetchingNextPage,
loadMore: async () => {
diff --git a/apps/web/src/features/projects/views/projects-sidebar.test.tsx b/apps/web/src/features/projects/views/projects-sidebar.test.tsx
index 16397a9da7..951ee1a94d 100644
--- a/apps/web/src/features/projects/views/projects-sidebar.test.tsx
+++ b/apps/web/src/features/projects/views/projects-sidebar.test.tsx
@@ -5,6 +5,7 @@ import {
screen,
waitFor,
} from '@solidjs/testing-library';
+import { CombinedError } from '@urql/core';
import {
type Accessor,
createResource,
@@ -139,6 +140,75 @@ it('keeps the heading and create action available while rows suspend', async ()
}
});
+it.each([false, true])(
+ 'does not resurrect a response-free refresh error with cached rows (empty=%s)',
+ async (empty) => {
+ const [error, setError] = createSignal<Error | undefined>(
+ new Error('Previous failure')
+ );
+ const { onOpen } = setup({
+ ...(empty ? { rows: () => [] } : {}),
+ error,
+ hasMore: () => !empty,
+ refresh: vi.fn(async () => {
+ setError(undefined);
+ throw new CombinedError({
+ networkError: new TypeError('Failed to fetch'),
+ });
+ }),
+ });
+ fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+ await waitFor(() => expect(screen.queryByRole('alert')).toBeNull());
+ if (empty) {
+ expect(screen.getByText('No projects yet')).toBeTruthy();
+ } else {
+ fireEvent.click(screen.getByRole('button', { name: 'Launch' }));
+ expect(onOpen).toHaveBeenCalled();
+ expect(
+ screen.getByRole('button', { name: 'Load more projects' })
+ ).toBeTruthy();
+ }
+ }
+);
+
+it.each([
+ new Error('Unexpected application failure'),
+ new CombinedError({ graphQLErrors: ['Forbidden'] }),
+ new CombinedError({
+ networkError: new Error('HTTP error'),
+ response: { status: 403 },
+ }),
+])(
+ 'keeps a rejected refresh visible when it is not a transport-only failure: %s',
+ async (failure) => {
+ const [error, setError] = createSignal<Error | undefined>(
+ new Error('Previous failure')
+ );
+ const refresh = vi.fn(async () => {
+ setError(undefined);
+ throw failure;
+ });
+ setup({ error, refresh });
+ fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+ await waitFor(() => expect(refresh).toHaveBeenCalledOnce());
+ expect(await screen.findByRole('alert')).toBeTruthy();
+ }
+);
+
+it('keeps transport failures visible without cached rows', async () => {
+ const [error, setError] = createSignal<Error | undefined>(
+ new Error('Previous failure')
+ );
+ const refresh = vi.fn(async () => {
+ setError(undefined);
+ throw new CombinedError({ networkError: new TypeError('Failed to fetch') });
+ });
+ setup({ rows: () => undefined, error, refresh });
+ fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+ await waitFor(() => expect(refresh).toHaveBeenCalledOnce());
+ expect(await screen.findByRole('alert')).toBeTruthy();
+});
+
it('guards pagination while pending and supports retry after a failed read', async () => {
const request = Promise.withResolvers<void>();
const { source } = setup({
diff --git a/apps/web/src/features/projects/views/projects-sidebar.tsx b/apps/web/src/features/projects/views/projects-sidebar.tsx
index b969b6fa2f..cd5ab26bb3 100644
--- a/apps/web/src/features/projects/views/projects-sidebar.tsx
+++ b/apps/web/src/features/projects/views/projects-sidebar.tsx
@@ -1,4 +1,5 @@
import { CollapsibleSection, ViewSidebar } from '@app/components/view-shell';
+import { isResponseFreeNetworkError } from '@core/util/request-error';
import PlusIcon from '@phosphor/plus.svg';
import StackIcon from '@phosphor/stack.svg';
import { createSignal, For, Show, Suspense } from 'solid-js';
@@ -20,17 +21,31 @@ export function ProjectsSidebar(props: ProjectsSidebarProps) {
() => props.open
);
const [pending, setPending] = createSignal(false);
- const [readError, setReadError] = createSignal(false);
- const failed = () => readError() || Boolean(source.error());
+ const [readFailure, setReadFailure] = createSignal<{
+ action: 'more' | 'refresh';
+ cause: unknown;
+ }>();
+ const failed = () => {
+ if (source.error()) return true;
+ const failure = readFailure();
+ if (!failure) return false;
+ // Refresh actions still reject on transport failure; do not resurrect the
+ // warning that the source suppressed for its usable cached rows.
+ return !(
+ failure.action === 'refresh' &&
+ isResponseFreeNetworkError(failure.cause) &&
+ source.rows() !== undefined
+ );
+ };
const readProjects = async (action: 'more' | 'refresh') => {
if (pending() || source.loadingMore()) return;
setPending(true);
- setReadError(false);
+ setReadFailure(undefined);
try {
if (action === 'more') await source.loadMore();
else await source.refresh();
- } catch {
- setReadError(true);
+ } catch (cause) {
+ setReadFailure({ action, cause });
} finally {
setPending(false);
}
diff --git a/apps/web/src/lib/core/util/request-error.test.ts b/apps/web/src/lib/core/util/request-error.test.ts
index 12782233a9..a829c0310b 100644
--- a/apps/web/src/lib/core/util/request-error.test.ts
+++ b/apps/web/src/lib/core/util/request-error.test.ts
@@ -1,8 +1,62 @@
import { CombinedError } from '@urql/core';
import { describe, expect, it } from 'vitest';
-import { isTransientRequestError } from './request-error';
+import {
+ isResponseFreeNetworkError,
+ isTransientRequestError,
+} from './request-error';
import { ThrownResultError } from './result';
+describe('isResponseFreeNetworkError', () => {
+ it('accepts a known response-free GraphQL transport failure', () => {
+ expect(
+ isResponseFreeNetworkError(
+ new CombinedError({ networkError: new TypeError('Failed to fetch') })
+ )
+ ).toBe(true);
+ });
+
+ it.each([401, 403, 404, 500, 503])('rejects HTTP %s responses', (status) => {
+ expect(
+ isResponseFreeNetworkError(
+ new CombinedError({
+ networkError: new Error('Request failed'),
+ response: new Response(null, { status }),
+ })
+ )
+ ).toBe(false);
+ });
+
+ it.each([undefined, new TypeError('Failed to fetch')])(
+ 'preserves GraphQL errors with or without a transport failure',
+ (networkError) => {
+ expect(
+ isResponseFreeNetworkError(
+ new CombinedError({ networkError, graphQLErrors: ['Denied'] })
+ )
+ ).toBe(false);
+ }
+ );
+
+ it.each([
+ { codes: ['NETWORK_ERROR'], expected: true },
+ { codes: ['NETWORK_ERROR', 'NETWORK_ERROR'], expected: true },
+ { codes: ['NETWORK_ERROR', 'SERVER_ERROR'], expected: false },
+ { codes: ['FORBIDDEN'], expected: false },
+ { codes: [], expected: false },
+ ])('classifies structured REST errors $codes', ({ codes, expected }) => {
+ expect(
+ isResponseFreeNetworkError(
+ new ThrownResultError(codes.map((code) => ({ code, message: code })))
+ )
+ ).toBe(expected);
+ });
+
+ it.each([undefined, null, new Error('Application failed'), 'offline'])(
+ 'does not hide an unknown error: %s',
+ (error) => expect(isResponseFreeNetworkError(error)).toBe(false)
+ );
+});
+
describe('isTransientRequestError', () => {
it.each([null, undefined])('does not classify %s as a failure', (error) => {
expect(isTransientRequestError(error)).toBe(false);
diff --git a/apps/web/src/lib/core/util/request-error.ts b/apps/web/src/lib/core/util/request-error.ts
index a5e59913aa..66507115bb 100644
--- a/apps/web/src/lib/core/util/request-error.ts
+++ b/apps/web/src/lib/core/util/request-error.ts
@@ -1,6 +1,28 @@
import { CombinedError } from '@urql/core';
import { ThrownResultError } from './result';
+/**
+ * A known transport failure with no server response. Cached reads may stay
+ * visible for these failures; HTTP, GraphQL and unknown application errors
+ * must still surface. This is deliberately narrower than retry eligibility.
+ */
+export function isResponseFreeNetworkError(error: unknown): boolean {
+ if (error instanceof CombinedError) {
+ return (
+ !error.response &&
+ error.graphQLErrors.length === 0 &&
+ error.networkError != null
+ );
+ }
+ if (error instanceof ThrownResultError) {
+ return (
+ error.errors.length > 0 &&
+ error.errors.every(({ code }) => code === 'NETWORK_ERROR')
+ );
+ }
+ return false;
+}
+
/**
* Classifies transport/server failures shared by cached reads and retries.
* Structured application errors take precedence; untyped errors are treated as
diff --git a/apps/web/src/lib/queries/soup/graphql/items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.ts
index e9d1491c75..7214d5f8f8 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.test.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts
@@ -96,7 +96,8 @@ type FakeExecution = {
source: 'live-network' | 'normalized-cache-hit' | 'affected-cache-reread';
revision?: string;
persistence?: Promise<string | undefined>;
- }
+ },
+ error?: CombinedError
): void;
};
@@ -143,11 +144,13 @@ function makeFakeClient(): {
subject.next({ operation, error, stale: false, hasNext: false }),
next: (
data,
- metadata = { source: 'live-network', revision: REVISION_1 }
+ metadata = { source: 'live-network', revision: REVISION_1 },
+ error
) =>
subject.next({
operation,
data,
+ error,
extensions: { __macroNormalizedCache: metadata },
stale: false,
hasNext: false,
@@ -186,6 +189,146 @@ describe('createGraphqlSoupAstItemsQuery', () => {
});
});
+ describe('cached response errors before local reconciliation', () => {
+ function fixture() {
+ const fake = makeFakeClient();
+ getGraphqlSoupClientMock.mockReturnValue(fake.client);
+ const local = deferred<unknown>();
+ let resetGeneration = () => {};
+ getGraphqlSoupCacheHostMock.mockReturnValue({
+ currentRevision: async () => REVISION_0,
+ entityFilter: entityFilterMock,
+ onCacheChanged: () => () => {},
+ onCacheGenerationChanged: (callback: () => void) => {
+ resetGeneration = callback;
+ return () => {};
+ },
+ });
+ entityFilterMock.mockReturnValue(local.promise);
+ const [limit, setLimit] = createSignal(50);
+ makeGraphqlSoupInputMock.mockImplementation(({ cursor }) =>
+ cursor ? { continuation: { cursor } } : { initial: { limit: limit() } }
+ );
+ const root = createRoot((dispose) => ({
+ dispose,
+ query: createGraphqlSoupAstItemsQuery(
+ () => ({ params: {}, body: {} }),
+ () => ({
+ enabled: true,
+ projection: 'channel-list',
+ keepPreviousData: true,
+ })
+ ),
+ }));
+ const error = new CombinedError({
+ networkError: new TypeError('Failed to fetch'),
+ });
+ return {
+ ...root,
+ fake,
+ error,
+ setLimit,
+ resetGeneration: () => resetGeneration(),
+ cached(empty = false, failure?: CombinedError) {
+ fake.executions.at(-1)!.next(
+ graphqlSoupPage({
+ items: empty ? [] : [{ id: 'cached-channel' }],
+ next_cursor: 'next',
+ }),
+ { source: 'normalized-cache-hit', revision: REVISION_0 },
+ failure
+ );
+ },
+ dispose() {
+ root.dispose();
+ local.resolve({ kind: 'unsupported' });
+ },
+ };
+ }
+
+ it.each([false, true])(
+ 'keeps cached results quiet while reconciliation is pending (empty=%s)',
+ (empty) => {
+ const f = fixture();
+ try {
+ f.cached(empty);
+ f.fake.executions[0].fail(f.error);
+ expect(f.query.data()?.entities).toHaveLength(empty ? 0 : 1);
+ expect(f.query.error()).toBeUndefined();
+ } finally {
+ f.dispose();
+ }
+ }
+ );
+
+ it('clears an early failure when a delayed cache hit carries the same error', () => {
+ const f = fixture();
+ try {
+ f.fake.executions[0].fail(f.error);
+ expect(f.query.error()).toBe(f.error);
+ expect(f.query.data()).toBeUndefined();
+ f.cached(false, f.error);
+ expect(f.query.data()?.entities).toHaveLength(1);
+ expect(f.query.error()).toBeUndefined();
+ } finally {
+ f.dispose();
+ }
+ });
+
+ it('does not use retained data from other filters or a reset cache generation', () => {
+ const f = fixture();
+ try {
+ f.cached();
+ f.setLimit(20);
+ f.fake.executions.at(-1)!.fail(f.error);
+ expect(f.query.error()).toBe(f.error);
+ f.cached(false, f.error);
+ expect(f.query.error()).toBeUndefined();
+ f.resetGeneration();
+ expect(f.query.error()).toBe(f.error);
+ } finally {
+ f.dispose();
+ }
+ });
+
+ it('keeps a failed load-more request visible despite cached earlier pages', async () => {
+ const f = fixture();
+ try {
+ f.cached();
+ const more = f.query.fetchNextPage();
+ f.fake.executions.at(-1)!.fail(f.error);
+ await more;
+ expect(f.query.data()?.entities).toHaveLength(1);
+ expect(f.query.error()).toBe(f.error);
+ } finally {
+ f.dispose();
+ }
+ });
+
+ it.each([
+ new CombinedError({ graphQLErrors: ['Forbidden'] }),
+ new CombinedError({
+ networkError: new TypeError('Failed to fetch'),
+ graphQLErrors: ['Resolver failed'],
+ }),
+ ...[401, 403, 503].map(
+ (status) =>
+ new CombinedError({
+ networkError: new Error('HTTP failure'),
+ response: { status },
+ })
+ ),
+ ])('does not suppress server errors with cached data: %s', (error) => {
+ const f = fixture();
+ try {
+ f.cached(false, error);
+ expect(f.query.error()).toBe(error);
+ } finally {
+ f.dispose();
+ }
+ });
+ });
+
describe('mixed folder contents', () => {
const excludedId = '00000000-0000-0000-0000-000000000000';
const item = (id: string, __typename = 'GraphqlSoupDocument') => ({
@@ -610,7 +753,8 @@ describe('createGraphqlSoupAstItemsQuery', () => {
expect(delegateChannelNotificationRefresh(fake.client, page)).toBe(true);
await vi.advanceTimersByTimeAsync(100);
expect(refresh).toHaveBeenCalledOnce();
- expect(query.error()).toBe(error);
+ // The refresh still retries, but its failure does not warn over a cached page.
+ expect(query.error()).toBeUndefined();
await vi.advanceTimersByTimeAsync(1000);
expect(refresh).toHaveBeenCalledTimes(2);
expect(refresh).toHaveBeenLastCalledWith(page.document, page.variables, {
diff --git a/apps/web/src/lib/queries/soup/graphql/items.ts b/apps/web/src/lib/queries/soup/graphql/items.ts
index 636af14879..81927b767b 100644
--- a/apps/web/src/lib/queries/soup/graphql/items.ts
+++ b/apps/web/src/lib/queries/soup/graphql/items.ts
@@ -16,7 +16,7 @@ import {
type UrqlInfiniteData,
} from '@app/lib/urql-solid';
import { createBrowserOfflineSignal } from '@core/util/connectivity';
-import { isTransientRequestError } from '@core/util/request-error';
+import { isResponseFreeNetworkError } from '@core/util/request-error';
import { Telemetry } from '@macro-inc/observability';
import { useInstructionsMdIdQuery } from '@queries/storage/instructions-md';
import type { SoupApiItem } from '@service-storage/generated/schemas';
@@ -146,6 +146,9 @@ export function createGraphqlSoupAstItemsQuery(
const firstPageInput = createMemo(() => inputForCursor(null));
const isSupported = () => firstPageInput() !== undefined;
+ const inputKey = createMemo(() =>
+ JSON.stringify([options().projection, firstPageInput()])
+ );
type ServerProjection = {
pageParams: readonly (string | null)[];
data: SoupAstItemsData;
@@ -202,6 +205,7 @@ export function createGraphqlSoupAstItemsQuery(
disposed = true;
});
const [baselineGeneration, setBaselineGeneration] = createSignal<number>();
+ const [baselineInputKey, setBaselineInputKey] = createSignal<string>();
let previousInitialInput: GraphqlSoupInput | undefined;
let networkAuthorityInput: GraphqlSoupInput | undefined;
let staleFallbackSpan: ReturnType<typeof Telemetry.span> | undefined;
@@ -619,6 +623,7 @@ export function createGraphqlSoupAstItemsQuery(
ServerProjection
>(() => {
const firstInput = firstPageInput();
+ const firstInputKey = inputKey();
const queryOptions = options();
return {
@@ -644,7 +649,10 @@ export function createGraphqlSoupAstItemsQuery(
keepPreviousData: queryOptions.keepPreviousData ?? false,
onResult: (result, page) => {
if (!result.data) return;
- setBaselineGeneration(cacheGeneration);
+ batch(() => {
+ setBaselineGeneration(cacheGeneration);
+ setBaselineInputKey(firstInputKey);
+ });
const metadata = normalizedCacheResultMetadata(result);
if (metadata?.source !== 'live-network') {
// An affected/cache result already reflects local state. Its pending
@@ -826,13 +834,18 @@ export function createGraphqlSoupAstItemsQuery(
const error = query.error;
// A background transport failure must not replace usable current-query
// cache results (including an empty result) with the full-screen error state.
- // Keep server responses (including HTTP auth failures), GraphQL errors,
- // and failures without current-query local proof visible.
+ // A normalized page is usable before local reconciliation finishes. Keep
+ // server responses, uncached queries and failed continuation reads visible;
+ // previous-filter or previous-generation pages are not fallback evidence.
if (
- error &&
- isTransientRequestError(error) &&
- !error.response &&
- displayLocalProjection()
+ isResponseFreeNetworkError(error) &&
+ options().enabled &&
+ isSupported() &&
+ !query.isFetchNextPageError &&
+ (displayLocalProjection() ||
+ (query.data !== undefined &&
+ baselineGeneration() === cacheGeneration &&
+ baselineInputKey() === inputKey()))
) {
return undefined;
}
diff --git a/docs/AGENT_GUIDE/channels.md b/docs/AGENT_GUIDE/channels.md
index b7c4da1f19..af2033a9b9 100644
--- a/docs/AGENT_GUIDE/channels.md
+++ b/docs/AGENT_GUIDE/channels.md
@@ -491,6 +491,14 @@ Deferred navigation waits until the destination is applied; an unavailable split
must leave unread state unchanged. Join-only channels remain
blocked after hydration, including on mobile.
+With GraphQL caching enabled, a current-query cached Channels or DMs page
+(including an empty page) remains quiet on a response-free refresh failure.
+Hold or fail the refresh before local filtering finishes: cached rows must not
+flash **Couldn’t load conversations** while awaiting reconciliation. Changing
+filters or resetting the cache must not use older rows to hide a new-query error.
+Cache misses, HTTP/GraphQL failures, and failures to load an uncached continuation
+still show errors and retry controls; background refresh retries continue.
+
Right-clicking a favorite opens the same menu as its channel's row in the
sections below — `Mark Read`, `Unfavorite`, `Mute notifications`, `Copy Link`,
and the label actions when channel labels are enabled — and focuses the
diff --git a/docs/AGENT_GUIDE/tasks.md b/docs/AGENT_GUIDE/tasks.md
index d7b20d3002..c0e6116aa9 100644
--- a/docs/AGENT_GUIDE/tasks.md
+++ b/docs/AGENT_GUIDE/tasks.md
@@ -27,6 +27,12 @@ preference persists. `Load more projects` fetches the next page when available.
The plus button beside `My projects` opens the project composer, even while the
section is collapsed or loading. Its rows use the shared project query/cache and
load inside a local Suspense boundary, leaving sidebar controls available.
+Once a current-query project page is cached, an offline/background refresh failure
+must not show **Could not load projects** beside those rows (or a cached empty
+result). Retrying a refresh must not reintroduce that warning merely because the
+refresh promise rejects; the cached project links remain available. Cache misses,
+server/permission errors, and failed **Load more projects** requests still show
+failure and retry controls. Verify both background refresh and manual retry.
Opening a project shows a content-shaped skeleton while its data loads: title,
wrapping property pills, description, and discussion for Overview; toolbar and
rows for Tasks. The mobile skeleton uses the same compact insets as the content.