@taskforcehq/taskforce 0.3.301 → 0.3.303

package/dist/core/Taskforce.mcpAuth.test.js

@@ -27,7 +27,6 @@ function setupWorkspace(core, userId = 'owner-1', workspaceId = 'workspace-1') {
             hasEntitlement: true,
             canAccessApp: true,
             canAccessPlans: true,
-            signupMonetizationStrategy: 'none',
             planSelectionRequired: false,
             message: null,
             entitlement: null
@@ -328,7 +327,6 @@ describe('TaskforceCore MCP auth invalidation', () => {
                     hasEntitlement: false,
                     canAccessApp: false,
                     canAccessPlans: true,
-                    signupMonetizationStrategy: 'none',
                     planSelectionRequired: false,
                     message: 'Suspended for test',
                     entitlement: null

package/dist/core/UserProfileAvatarDrafts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/UserProfileAvatarDrafts.test.js

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { TaskforceCore } from './Taskforce';
+function makeProjectRoot() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-user-avatar-'));
+}
+function seedPlans(core) {
+    core.upsertPlanCatalog({ planId: 'starter', displayName: 'Starter', status: 'active' });
+    core.updatePlanVersion({
+        planId: 'starter',
+        versionNumber: 1,
+        seatLimit: 1
+    });
+    const db = core.db;
+    const now = new Date().toISOString();
+    db.prepare(`
+        INSERT OR IGNORE INTO billing_price_mappings (
+            tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(core.getTenantId(), 'starter-v1', 'month', 'free:starter-v1:month', 'free', 1, 0, null, now, now);
+    core.updateGlobalSettings({
+        billing: {
+            onboardingPolicy: {
+                mode: 'auto_grant_free',
+                planVersionId: 'starter-v1'
+            }
+        }
+    });
+}
+function openCore(projectRoot) {
+    const core = new TaskforceCore({
+        projectRoot,
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    seedPlans(core);
+    return core;
+}
+describe('TaskforceCore user profile avatar drafts', () => {
+    it('persists avatarUrl on profile updates and exposes it in resolved identity', () => {
+        const projectRoot = makeProjectRoot();
+        const core = openCore(projectRoot);
+        try {
+            const created = core.registerPasswordUser({
+                email: 'avatar-user@example.com',
+                password: 'password123'
+            });
+            const updated = core.updateUserProfile(created.userId, {
+                displayName: 'Avatar User',
+                avatarUrl: `/api/taskforce/context/${encodeURIComponent(`users/${created.userId}/profile/avatar/headshot.png`)}`
+            });
+            expect(updated).toMatchObject({
+                userId: created.userId,
+                displayName: 'Avatar User',
+                avatarUrl: `/api/taskforce/context/${encodeURIComponent(`users/${created.userId}/profile/avatar/headshot.png`)}`
+            });
+            expect(core.resolveUserIdentity(created.userId)?.avatarUrl).toBe(`/api/taskforce/context/${encodeURIComponent(`users/${created.userId}/profile/avatar/headshot.png`)}`);
+        }
+        finally {
+            core.close();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('tracks, finalizes, discards, and cleans up stale avatar upload drafts', () => {
+        const projectRoot = makeProjectRoot();
+        const core = openCore(projectRoot);
+        try {
+            const created = core.registerPasswordUser({
+                email: 'draft-user@example.com',
+                password: 'password123'
+            });
+            const draft = core.createUserAvatarUploadDraft({
+                userId: created.userId,
+                draftId: 'avatar-draft-1',
+                storageKey: `users/${created.userId}/profile/avatar/avatar-draft-1-headshot.png`,
+                mimeType: 'image/png',
+                originalFilename: 'headshot.png',
+                sizeBytes: 1024,
+                storageProvider: 'r2'
+            });
+            expect(draft.finalizedAt).toBeNull();
+            expect(core.markUserAvatarUploadDraftFinalized(created.userId, draft.draftId)?.finalizedAt).toEqual(expect.any(String));
+            expect(core.markUserAvatarUploadDraftConsumed(created.userId, draft.draftId)?.consumedAt).toEqual(expect.any(String));
+            expect(core.discardUserAvatarUploadDraft(created.userId, draft.draftId)?.discardedAt).toEqual(expect.any(String));
+            core.createUserAvatarUploadDraft({
+                userId: created.userId,
+                draftId: 'avatar-draft-stale',
+                storageKey: `users/${created.userId}/profile/avatar/avatar-draft-stale-headshot.png`,
+                mimeType: 'image/png',
+                originalFilename: 'stale.png',
+                sizeBytes: 512,
+                storageProvider: 'r2'
+            });
+            const db = core.db;
+            db.prepare(`
+                UPDATE user_avatar_upload_drafts
+                SET created_at = ?, updated_at = ?
+                WHERE tenant_id = ? AND user_id = ? AND draft_id = ?
+            `).run('2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z', core.getTenantId(), created.userId, 'avatar-draft-stale');
+            const stale = core.cleanupStaleUserAvatarUploadDrafts(created.userId, '2026-02-01T00:00:00.000Z');
+            expect(stale).toHaveLength(1);
+            expect(stale[0]?.draftId).toBe('avatar-draft-stale');
+            expect(core.getUserAvatarUploadDraft(created.userId, 'avatar-draft-stale')?.discardedAt).toEqual(expect.any(String));
+        }
+        finally {
+            core.close();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+});

package/dist/core/taskReferencePolicy.d.ts

@@ -0,0 +1,28 @@
+import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
+import type { TaskItem } from './Taskforce.js';
+interface TaskReferencePolicyDeps<TTask> {
+    db: DatabaseAdapter;
+    tenantId: string;
+    normalizeWorkspaceId: (workspaceId?: string) => string;
+    sanitizeTaskReferenceNumber: (value: unknown) => number | null;
+    rowToTask: (row: any) => TTask;
+    getTask: (id: string, workspaceId?: string) => TTask | null;
+}
+export declare function getTaskReferenceSequenceValue<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string): number;
+export declare function getLocalTaskReferenceSequenceValue<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string): number;
+export declare function getMaxTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function getMaxLocalTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function persistTaskReferenceSequence<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, referenceNumber: number): void;
+export declare function persistLocalTaskReferenceSequence<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, referenceNumber: number): void;
+export declare function allocateNextTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function allocateNextLocalTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function relocateTaskReferenceConflict<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, referenceNumber: number, claimantTaskId?: string | null, updatedAt?: string | null): {
+    taskId: string;
+    referenceNumber: number;
+} | null;
+export declare function reserveTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, preferredReferenceNumber?: number | null, currentTaskId?: string | null): number;
+export declare function getTaskByReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, referenceNumber: number, workspaceId?: string): TTask | null;
+export declare function getTaskByLocalReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, referenceNumber: number, workspaceId?: string): TTask | null;
+export declare function resolveTaskIdentifier(deps: TaskReferencePolicyDeps<TaskItem>, value: string, workspaceId?: string): TaskItem | null;
+export declare function deriveTaskReferenceLabel(task: Pick<TaskItem, 'referenceNumber' | 'localReferenceNumber'>): string;
+export {};

package/dist/core/taskReferencePolicy.js

@@ -0,0 +1,189 @@
+import { formatLocalTaskReference, parseLocalTaskReference, parseTaskReference, } from '../utils/taskReferences.js';
+export function getTaskReferenceSequenceValue(deps, workspaceId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT next_reference_number
+        FROM workspace_task_reference_sequences
+        WHERE tenant_id = ? AND workspace_id = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.next_reference_number) || 0;
+}
+export function getLocalTaskReferenceSequenceValue(deps, workspaceId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT next_reference_number
+        FROM workspace_local_task_reference_sequences
+        WHERE tenant_id = ? AND workspace_id = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.next_reference_number) || 0;
+}
+export function getMaxTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedExcludeTaskId = String(excludeTaskId || '').trim();
+    const row = normalizedExcludeTaskId
+        ? deps.db.prepare(`
+            SELECT MAX(reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND id != ?
+        `).get(deps.tenantId, normalizedWorkspaceId, normalizedExcludeTaskId)
+        : deps.db.prepare(`
+            SELECT MAX(reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ?
+        `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.max_reference_number) || 0;
+}
+export function getMaxLocalTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedExcludeTaskId = String(excludeTaskId || '').trim();
+    const row = normalizedExcludeTaskId
+        ? deps.db.prepare(`
+            SELECT MAX(local_reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND id != ?
+        `).get(deps.tenantId, normalizedWorkspaceId, normalizedExcludeTaskId)
+        : deps.db.prepare(`
+            SELECT MAX(local_reference_number) AS max_reference_number
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ?
+        `).get(deps.tenantId, normalizedWorkspaceId);
+    return deps.sanitizeTaskReferenceNumber(row?.max_reference_number) || 0;
+}
+export function persistTaskReferenceSequence(deps, workspaceId, referenceNumber) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return;
+    deps.db.prepare(`
+        INSERT INTO workspace_task_reference_sequences (tenant_id, workspace_id, next_reference_number)
+        VALUES (?, ?, ?)
+        ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+            next_reference_number = CASE
+                WHEN workspace_task_reference_sequences.next_reference_number < EXCLUDED.next_reference_number
+                    THEN EXCLUDED.next_reference_number
+                ELSE workspace_task_reference_sequences.next_reference_number
+            END
+    `).run(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+}
+export function persistLocalTaskReferenceSequence(deps, workspaceId, referenceNumber) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return;
+    deps.db.prepare(`
+        INSERT INTO workspace_local_task_reference_sequences (tenant_id, workspace_id, next_reference_number)
+        VALUES (?, ?, ?)
+        ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
+            next_reference_number = CASE
+                WHEN workspace_local_task_reference_sequences.next_reference_number < EXCLUDED.next_reference_number
+                    THEN EXCLUDED.next_reference_number
+                ELSE workspace_local_task_reference_sequences.next_reference_number
+            END
+    `).run(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+}
+export function allocateNextTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const nextReferenceNumber = Math.max(getTaskReferenceSequenceValue(deps, normalizedWorkspaceId), getMaxTaskReferenceNumber(deps, normalizedWorkspaceId, excludeTaskId)) + 1;
+    persistTaskReferenceSequence(deps, normalizedWorkspaceId, nextReferenceNumber);
+    return nextReferenceNumber;
+}
+export function allocateNextLocalTaskReferenceNumber(deps, workspaceId, excludeTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const nextReferenceNumber = Math.max(getLocalTaskReferenceSequenceValue(deps, normalizedWorkspaceId), getMaxLocalTaskReferenceNumber(deps, normalizedWorkspaceId, excludeTaskId)) + 1;
+    persistLocalTaskReferenceSequence(deps, normalizedWorkspaceId, nextReferenceNumber);
+    return nextReferenceNumber;
+}
+export function relocateTaskReferenceConflict(deps, workspaceId, referenceNumber, claimantTaskId, updatedAt) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return null;
+    const normalizedClaimantTaskId = String(claimantTaskId || '').trim();
+    const incumbent = deps.db.prepare(`
+        SELECT id
+        FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ? AND id != ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber, normalizedClaimantTaskId);
+    const incumbentTaskId = String(incumbent?.id || '').trim();
+    if (!incumbentTaskId)
+        return null;
+    const nextReferenceNumber = allocateNextTaskReferenceNumber(deps, normalizedWorkspaceId, incumbentTaskId);
+    deps.db.prepare(`
+        UPDATE tasks
+        SET reference_number = ?, updated_at = ?
+        WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+    `).run(nextReferenceNumber, String(updatedAt || new Date().toISOString()), deps.tenantId, normalizedWorkspaceId, incumbentTaskId);
+    return { taskId: incumbentTaskId, referenceNumber: nextReferenceNumber };
+}
+export function reserveTaskReferenceNumber(deps, workspaceId, preferredReferenceNumber, currentTaskId) {
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const preferred = deps.sanitizeTaskReferenceNumber(preferredReferenceNumber);
+    const normalizedCurrentTaskId = String(currentTaskId || '').trim();
+    if (preferred) {
+        const existing = deps.db.prepare(`
+            SELECT id
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ?
+            LIMIT 1
+        `).get(deps.tenantId, normalizedWorkspaceId, preferred);
+        if (!existing?.id || existing.id === normalizedCurrentTaskId) {
+            persistTaskReferenceSequence(deps, normalizedWorkspaceId, preferred);
+            return preferred;
+        }
+    }
+    return allocateNextTaskReferenceNumber(deps, normalizedWorkspaceId, normalizedCurrentTaskId || undefined);
+}
+export function getTaskByReferenceNumber(deps, referenceNumber, workspaceId) {
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return null;
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT * FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+    if (!row)
+        return null;
+    return deps.rowToTask(row);
+}
+export function getTaskByLocalReferenceNumber(deps, referenceNumber, workspaceId) {
+    const normalizedReferenceNumber = deps.sanitizeTaskReferenceNumber(referenceNumber);
+    if (!normalizedReferenceNumber)
+        return null;
+    const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
+    const row = deps.db.prepare(`
+        SELECT * FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ? AND local_reference_number = ?
+        LIMIT 1
+    `).get(deps.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
+    if (!row)
+        return null;
+    return deps.rowToTask(row);
+}
+export function resolveTaskIdentifier(deps, value, workspaceId) {
+    const normalizedValue = String(value || '').trim();
+    if (!normalizedValue)
+        return null;
+    const referenceNumber = parseTaskReference(normalizedValue);
+    if (referenceNumber) {
+        const exactReferenceMatch = getTaskByReferenceNumber(deps, referenceNumber, workspaceId);
+        if (exactReferenceMatch)
+            return exactReferenceMatch;
+    }
+    const localReferenceNumber = parseLocalTaskReference(normalizedValue);
+    if (localReferenceNumber) {
+        const exactLocalReferenceMatch = getTaskByLocalReferenceNumber(deps, localReferenceNumber, workspaceId);
+        if (exactLocalReferenceMatch)
+            return exactLocalReferenceMatch;
+    }
+    return deps.getTask(normalizedValue, workspaceId);
+}
+export function deriveTaskReferenceLabel(task) {
+    return task.referenceNumber
+        ? `T-${task.referenceNumber}`
+        : formatLocalTaskReference(task.localReferenceNumber);
+}

package/dist/core/types.d.ts

@@ -27,6 +27,7 @@ export type TaskAssignee = string;
 export interface TaskItem {
     id: string;
     referenceNumber?: number | null;
+    localReferenceNumber?: number | null;
     referenceLabel?: string;
     title: string;
     description: string | null;
@@ -267,8 +268,9 @@ export interface GlobalTaskforceSettings {
         authRateLimitEnabled?: boolean;
         authRateLimitMaxRequests?: number;
         authRateLimitWindowMs?: number;
-        signupMonetizationStrategy?: 'auto_assign_default' | 'plan_selection_required';
-        defaultSignupPlanVersionId?: string | null;
+    };
+    billing?: {
+        onboardingPolicy?: OnboardingPolicy;
     };
     site?: {
         showRunTaskforceLocally?: boolean;
@@ -298,14 +300,14 @@ export interface UserGlobalSyncSettings {
         weekStartsOn?: 'sunday' | 'monday';
     };
 }
-export type SignupMonetizationStrategy = 'auto_assign_default' | 'plan_selection_required';
-export interface SignupMonetizationSettings {
-    strategy: SignupMonetizationStrategy;
-    defaultSignupPlanVersionId: string | null;
+export type OnboardingPolicyMode = 'require_plan_selection' | 'auto_grant_free' | 'auto_start_trial';
+export interface OnboardingPolicy {
+    mode: OnboardingPolicyMode;
+    planVersionId: string | null;
 }
-export interface SignupMonetizationValidationResult {
+export interface OnboardingPolicyValidationResult {
     valid: boolean;
-    code?: 'SIGNUP_PLAN_VERSION_REQUIRED' | 'SIGNUP_PLAN_VERSION_NOT_FOUND' | 'SIGNUP_PLAN_NOT_ENABLED';
+    code?: 'ONBOARDING_PLAN_VERSION_REQUIRED' | 'ONBOARDING_PLAN_VERSION_NOT_FOUND' | 'ONBOARDING_PLAN_NOT_ENABLED' | 'ONBOARDING_PLAN_MUST_BE_FREE' | 'ONBOARDING_PLAN_TRIAL_REQUIRED';
     message?: string;
     details?: Record<string, unknown>;
 }
@@ -330,6 +332,7 @@ export interface UserIdentityRecord {
     userId: string;
     email: string;
     displayName?: string | null;
+    avatarUrl?: string | null;
     systemRole?: SystemRole;
     betaAccess?: boolean;
 }
@@ -439,7 +442,7 @@ export interface McpAuditLogRecord {
     reasonCode: string | null;
     details: Record<string, unknown>;
 }
-export type EntitlementState = 'active' | 'trialing' | 'grace' | 'suspended' | 'canceled';
+export type EntitlementState = 'pending_plan_selection' | 'checkout_pending' | 'active' | 'trialing' | 'grace' | 'suspended' | 'canceled';
 export type PlanFeatureAccess = 'enabled' | 'disabled' | 'limited';
 export interface PlanFeatureSnapshot {
     featureKey: string;
@@ -497,17 +500,15 @@ export interface AccountAccessStatus_Ok {
     hasEntitlement: true;
     canAccessApp: true;
     canAccessPlans: true;
-    signupMonetizationStrategy: SignupMonetizationStrategy;
     planSelectionRequired: false;
     message: null;
     entitlement: AccountEntitlementSnapshot;
 }
 export interface AccountAccessStatus_Blocked {
-    gate: 'plan_selection_required' | 'misconfigured' | 'missing_entitlement';
+    gate: 'plan_selection_required' | 'checkout_pending' | 'misconfigured' | 'missing_entitlement';
     hasEntitlement: boolean;
     canAccessApp: false;
     canAccessPlans: true;
-    signupMonetizationStrategy: SignupMonetizationStrategy;
     planSelectionRequired: boolean;
     message: string;
     entitlement: AccountEntitlementSnapshot | null;

package/dist/hooks/tasks/useTaskFormActions.js

@@ -130,6 +130,9 @@ export function useTaskFormActions(input) {
             if (!editingTaskId || attachmentsDirty) {
                 body.attachments = attachments;
             }
+            if (editingTaskId) {
+                body.saveSource = source;
+            }
             const res = await fetch(url, {
                 method,
                 headers: { 'Content-Type': 'application/json' },

package/dist/hooks/useSyncOrchestrator.js

@@ -1571,7 +1571,12 @@ export function useSyncOrchestrator(input) {
                     status: 'error',
                     statusCode: pullResult.status,
                     errorMessage: message,
-                    requestMs: pullResult.pullRequestMs
+                    requestMs: pullResult.pullRequestMs,
+                    details: {
+                        pages: pullResult.pages,
+                        applyMs: pullResult.applyMs,
+                        ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                    }
                 });
                 if (pullResult.transient || pullResult.hasTransientApplyFailure || isTransientWorkspaceSyncStatus(pullResult.status)) {
                     scheduleWorkspaceSyncRetry(pullResult.retryAfterMs);
@@ -1638,7 +1643,12 @@ export function useSyncOrchestrator(input) {
                 eventType: workspaceSyncPhase === 'attach-cloud' ? 'bootstrap' : 'pull',
                 status: 'success',
                 changeCount: pullResult.appliedChanges,
-                requestMs: pullResult.pullRequestMs
+                requestMs: pullResult.pullRequestMs,
+                details: {
+                    pages: pullResult.pages,
+                    applyMs: pullResult.applyMs,
+                    ...(pullResult.serverDiagnostics ? { serverPullDiagnostics: pullResult.serverDiagnostics } : {})
+                }
             });
             if (workspaceSyncPhase === 'attach-cloud') {
                 await refreshWorkspaceSyncMarkdownDocumentsSnapshot();
@@ -1727,8 +1737,11 @@ export function useSyncOrchestrator(input) {
         const eventId = String(signal?.eventId || '').trim();
         if (eventId && realtimeSuppressedEventIdsRef.current.delete(eventId))
             return;
-        if (isWorkspaceRetryPending() || workspacePullInFlightRef.current)
+        if (workspacePullInFlightRef.current)
             return;
+        if (isWorkspaceRetryPending()) {
+            clearWorkspaceRetry();
+        }
         if (realtimePullDebounceRef.current !== null) {
             window.clearTimeout(realtimePullDebounceRef.current);
         }
@@ -1742,6 +1755,7 @@ export function useSyncOrchestrator(input) {
         workspaceCloudSyncEnabled,
         workspaceSyncPhase,
         isWorkspaceRetryPending,
+        clearWorkspaceRetry,
         workspacePullInFlightRef,
         pullWorkspaceChangesFromCloud
     ]);

package/dist/hooks/useSyncOrchestrator.retry-closure.test.js

@@ -3,19 +3,44 @@ import { act, renderHook, waitFor } from '@testing-library/react';
 import { useSyncOrchestrator } from './useSyncOrchestrator';
 class MockWebSocket {
     static instances = [];
+    static OPEN = 1;
+    static CLOSED = 3;
     url;
+    readyState = 0;
+    sent = [];
+    listeners = new Map();
     constructor(url) {
         this.url = url;
         MockWebSocket.instances.push(this);
     }
     close() {
-        // noop for orchestration gating tests
+        this.readyState = MockWebSocket.CLOSED;
+        this.emit('close', {});
     }
-    addEventListener() {
-        // noop for orchestration gating tests
+    addEventListener(type, listener) {
+        const bucket = this.listeners.get(type) || new Set();
+        bucket.add(listener);
+        this.listeners.set(type, bucket);
     }
-    send() {
-        // noop for orchestration gating tests
+    send(payload) {
+        if (typeof payload === 'string') {
+            this.sent.push(payload);
+        }
+    }
+    emit(type, event) {
+        const bucket = this.listeners.get(type);
+        if (!bucket)
+            return;
+        for (const listener of bucket) {
+            listener(event);
+        }
+    }
+    open() {
+        this.readyState = MockWebSocket.OPEN;
+        this.emit('open', {});
+    }
+    message(payload) {
+        this.emit('message', { data: JSON.stringify(payload) });
     }
 }
 const { ensureCloudWorkspaceReadyForSyncServiceMock, runWorkspacePullSyncServiceMock, runWorkspacePushSyncServiceMock, syncUserGlobalSettingsServiceMock } = vi.hoisted(() => ({
@@ -206,6 +231,73 @@ describe('useSyncOrchestrator', () => {
         expect(MockWebSocket.instances[0]?.url).toBe('wss://api.example.com/taskforce-ws');
         unmount();
     });
+    it('lets a realtime signal break transient retry backoff and pull immediately', async () => {
+        vi.useFakeTimers();
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        runWorkspacePullSyncServiceMock
+            .mockResolvedValueOnce({
+            success: false,
+            kind: 'pull_http',
+            status: 502,
+            transient: true,
+            retryAfterMs: 60_000,
+            cursor: null,
+            pages: 0,
+            appliedChanges: 0,
+            pullRequestMs: 1,
+            applyMs: 0,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: false,
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        })
+            .mockResolvedValueOnce({
+            success: true,
+            syncedAt: '2026-03-15T18:05:00.000Z',
+            cursor: null,
+            pages: 1,
+            appliedChanges: 1,
+            pullRequestMs: 1,
+            applyMs: 0,
+            pulledDeleteTaskIds: new Set(),
+            pulledActiveUpserts: true,
+            pulledArchivedUpserts: false,
+            documentDecryptFailures: []
+        });
+        const { result, unmount } = renderHook((props) => useSyncOrchestrator(props), {
+            initialProps: buildInput({ realtimeSyncEnabled: true })
+        });
+        act(() => {
+            result.current.applyWorkspaceSyncStateSnapshot({
+                enabled: true,
+                phase: 'active',
+                pullCursor: null
+            });
+        });
+        await act(async () => {
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(result.current.workspaceRetryAt).not.toBeNull();
+        expect(MockWebSocket.instances).toHaveLength(1);
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(1);
+        act(() => {
+            MockWebSocket.instances[0]?.open();
+            MockWebSocket.instances[0]?.message({
+                type: 'taskforce:update',
+                workspaceId: 'workspace-local-active'
+            });
+        });
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+            await Promise.resolve();
+            await Promise.resolve();
+        });
+        expect(runWorkspacePullSyncServiceMock).toHaveBeenCalledTimes(2);
+        expect(result.current.workspaceRetryAt).toBeNull();
+        expect(result.current.workspaceLastPullAt).toBe('2026-03-15T18:05:00.000Z');
+        unmount();
+    });
     it('retries transient push failures automatically', async () => {
         runWorkspacePushSyncServiceMock
             .mockResolvedValueOnce({

package/dist/hooks/useTaskData.js

@@ -152,10 +152,11 @@ export function useTaskData({ tasks, archivedTasks, setTasks, setArchivedTasks,
             console.error('[Taskforce] Failed to fetch tasks:', err);
         }
         finally {
-            if (tasksAbortRef.current === abortController) {
+            const isCurrentRequest = tasksAbortRef.current === abortController;
+            if (isCurrentRequest) {
                 tasksAbortRef.current = null;
             }
-            if (!isSilent)
+            if (!isSilent && isCurrentRequest)
                 setLoadingTasks(false);
         }
     }, [