@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/hooks/tasks/useTaskFormActions.js

@@ -1,22 +1,67 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { DEFAULT_TYPE_VALUE } from '../../shared/taxonomyDefaults.js';
 import { normalizeTaskFromApi } from '../../utils/taskNormalization.js';
+import { createCloudTaskHttpMutationClient, fetchTaskHttpMutation, isConclusiveTaskHttpResponse, } from './taskHttpMutation.js';
+import { canonicalWorkspaceSyncJson } from '../../sync/v3/canonicalWorkspaceSyncJson.js';
 export function useTaskFormActions(input) {
-    const { activeCategories, activeTab, apiEndpoint, approach, assignee, attachments, attachmentsDirty, category, checklistItems, comments, complexity, description, dueDate, editingTaskId, fetchTasks, formTaxonomies, getPreferredCategoryValue, mergeTaskFromServer, workstreamInput, priority, pushNotice, queueWorkspaceSyncFromAuthoritativeTaskState, relationshipTasks, resetForm, resolveWorkstreamIdInput, scheduledDate, setActiveTab, setAttachmentsDirty, setComments, setError, setLastUsedCategory, setLoading, setNewCommentText, status, title, taxonomies, type } = input;
+    const { activeCategories, activeTab, apiEndpoint, assignee, attachments, attachmentsDirty, category, checklistItems, comments, complexity, description, dueDate, createTaskDurably, durableTaskHttpRootActivationEnabled = false, workspaceId, taskHttpMutationClient, updateTask, editingTaskId, fetchTasks, formTaxonomies, getAttachmentsDraft: getAttachmentsDraftInput, getDescriptionDraft: getDescriptionDraftInput, getPreferredCategoryValue, getTitleDraft: getTitleDraftInput, awaitPendingDescriptionImageUpload: awaitPendingDescriptionImageUploadInput, mergeTaskFromServer, onTaskCreated, onTaskCreateAccepted, workstreamInput, priority, pushNotice, queueWorkspaceSyncFromAuthoritativeTaskState, relationshipTasks, supplementalTasks = [], resetForm, resolveWorkstreamIdInput, scheduledDate, setActiveTab, setAttachmentsDirty, setComments, setError, setLastUsedCategory, setLoading, setNewCommentText, status, title, taxonomies, textDraftOccupied, type } = input;
+    const getTitleDraft = getTitleDraftInput || (() => title);
+    const getDescriptionDraft = getDescriptionDraftInput || (() => description);
+    const getAttachmentsDraft = getAttachmentsDraftInput || (() => attachments);
+    const getTitleDraftRef = useRef(getTitleDraft);
+    const getDescriptionDraftRef = useRef(getDescriptionDraft);
+    const getAttachmentsDraftRef = useRef(getAttachmentsDraft);
+    const awaitPendingDescriptionImageUploadRef = useRef(awaitPendingDescriptionImageUploadInput);
+    getTitleDraftRef.current = getTitleDraft;
+    getDescriptionDraftRef.current = getDescriptionDraft;
+    getAttachmentsDraftRef.current = getAttachmentsDraft;
+    awaitPendingDescriptionImageUploadRef.current = awaitPendingDescriptionImageUploadInput;
+    const readTextDraft = useCallback(() => ({
+        title: getTitleDraftRef.current(),
+        description: getDescriptionDraftRef.current(),
+    }), []);
     const [scheduleWarningPrompt, setScheduleWarningPrompt] = useState(null);
     const [autoSaveState, setAutoSaveState] = useState('idle');
     const [lastSavedDraftSignature, setLastSavedDraftSignature] = useState(null);
     const autoSaveTimerRef = useRef(null);
-    const buildTaskDraftSignature = useCallback(() => JSON.stringify({
-        title: title.trim(),
-        description: description || '',
+    const queuedAutoSaveRef = useRef(null);
+    const activeAutoSaveSignatureRef = useRef(null);
+    const autoSaveDrainRef = useRef(null);
+    const suppressNextCreateSuccessNoticeRef = useRef(false);
+    const createdTaskRef = useRef(null);
+    const taskHttpMutationClientRef = useRef(null);
+    const createDraftOccupiedRef = useRef(false);
+    const pendingCommentMutationRef = useRef(null);
+    const editingTask = editingTaskId
+        ? relationshipTasks.find((task) => task.id === editingTaskId)
+            || supplementalTasks.find((task) => task.id === editingTaskId)
+            || null
+        : null;
+    const editingReadOnlyMode = editingTask?.isDeleted
+        ? 'deleted'
+        : editingTask?.isArchived
+            ? 'archived'
+            : null;
+    const createDraftOccupied = activeTab === 'add' && !editingTaskId && ((textDraftOccupied ?? (title.trim() !== '' || description.trim() !== ''))
+        || checklistItems.length > 0
+        || (comments?.length || 0) > 0
+        || attachments.length > 0);
+    useEffect(() => {
+        if (createDraftOccupiedRef.current && !createDraftOccupied) {
+            taskHttpMutationClientRef.current?.resetCreateDraft(workspaceId);
+            createTaskDurably?.resetDraft?.();
+        }
+        createDraftOccupiedRef.current = createDraftOccupied;
+    }, [createDraftOccupied, createTaskDurably, workspaceId]);
+    const buildTaskDraftSignature = useCallback((textDraft = readTextDraft(), attachmentDraft = getAttachmentsDraftRef.current()) => JSON.stringify({
+        title: textDraft.title.trim(),
+        description: textDraft.description,
         category: typeof category === 'string'
             ? category
             : category.label || getPreferredCategoryValue(activeCategories),
         type: typeof type === 'string' ? type : type.label || DEFAULT_TYPE_VALUE,
         priority: Number(priority),
         complexity: Number(complexity) || 3,
-        approach: approach || 'default',
         assignee: assignee || 'agent',
         scheduledDate: scheduledDate || '',
         dueDate: dueDate || '',
@@ -24,12 +69,10 @@ export function useTaskFormActions(input) {
         checklistItems,
         comments,
         taxonomies: formTaxonomies,
-        attachments,
+        attachments: attachmentDraft,
     }), [
         activeCategories,
-        approach,
         assignee,
-        attachments,
         category,
         checklistItems,
         comments,
@@ -39,6 +82,7 @@ export function useTaskFormActions(input) {
         formTaxonomies,
         getPreferredCategoryValue,
         priority,
+        readTextDraft,
         scheduledDate,
         title,
         type,
@@ -50,10 +94,67 @@ export function useTaskFormActions(input) {
             autoSaveTimerRef.current = null;
         }
     }, []);
+    const enqueueAutoSave = useCallback((request) => {
+        if (activeAutoSaveSignatureRef.current === request.signature
+            && queuedAutoSaveRef.current === null
+            && autoSaveDrainRef.current) {
+            return autoSaveDrainRef.current;
+        }
+        queuedAutoSaveRef.current = request;
+        if (autoSaveDrainRef.current)
+            return autoSaveDrainRef.current;
+        const drain = async () => {
+            let latestResult = true;
+            while (queuedAutoSaveRef.current) {
+                const current = queuedAutoSaveRef.current;
+                queuedAutoSaveRef.current = null;
+                activeAutoSaveSignatureRef.current = current.signature;
+                latestResult = await current.save();
+                if (latestResult) {
+                    setLastSavedDraftSignature(current.signature);
+                }
+            }
+            activeAutoSaveSignatureRef.current = null;
+            return latestResult;
+        };
+        const drainPromise = drain().finally(() => {
+            activeAutoSaveSignatureRef.current = null;
+            autoSaveDrainRef.current = null;
+        });
+        autoSaveDrainRef.current = drainPromise;
+        return drainPromise;
+    }, []);
     const saveTask = useCallback(async (options) => {
         const quiet = options?.quiet ?? false;
         const source = options?.source ?? 'manual';
-        if (!title.trim()) {
+        if (!editingTaskId && source === 'manual') {
+            try {
+                await awaitPendingDescriptionImageUploadRef.current?.();
+            }
+            catch (error) {
+                console.error('Description image upload did not settle before task creation.', error);
+                const message = 'Wait for the Description image upload to finish, then try again.';
+                setError(message);
+                if (!quiet)
+                    pushNotice(message, 'error');
+                return false;
+            }
+        }
+        const textDraft = options?.textDraft ?? readTextDraft();
+        const draftTitle = textDraft.title;
+        const draftDescription = textDraft.description;
+        const draftAttachments = getAttachmentsDraftRef.current();
+        if (!editingTaskId) {
+            createdTaskRef.current = null;
+        }
+        if (editingReadOnlyMode) {
+            setError(editingReadOnlyMode === 'deleted'
+                ? 'Deleted tasks are read-only. Restore first to make changes.'
+                : 'Archived tasks are read-only. Unarchive first to make changes.');
+            setAutoSaveState(source === 'autosave' ? 'error' : 'idle');
+            return false;
+        }
+        if (!draftTitle.trim()) {
             setError('Title is required');
             if (editingTaskId) {
                 setAutoSaveState(source === 'autosave' ? 'error' : 'idle');
@@ -78,14 +179,6 @@ export function useTaskFormActions(input) {
             }
             return false;
         }
-        if (editingTaskId) {
-            const existing = relationshipTasks.find((task) => task.id === editingTaskId);
-            if (existing?.isArchived) {
-                setError('Archived tasks are read-only. Unarchive first to make changes.');
-                setAutoSaveState(source === 'autosave' ? 'error' : 'idle');
-                return false;
-            }
-        }
         setLoading(true);
         setError('');
         if (editingTaskId) {
@@ -103,44 +196,154 @@ export function useTaskFormActions(input) {
             const resolvedWorkstream = workstreamInput.trim()
                 ? resolveWorkstreamIdInput(workstreamInput)
                 : null;
+            const existingTask = editingTaskId
+                ? relationshipTasks.find((task) => task.id === editingTaskId)
+                : null;
+            const checklistChanged = !editingTaskId || !existingTask
+                || canonicalWorkspaceSyncJson(existingTask.checklistItems || [])
+                    !== canonicalWorkspaceSyncJson(checklistItems);
             const body = {
-                title,
-                description: description || null,
+                title: draftTitle,
+                description: draftDescription || null,
                 category: sanitizedCategory || getPreferredCategoryValue(activeCategories),
                 type: sanitizedType,
                 priority,
                 complexity: Number(complexity) || 3,
                 status: editingTaskId ? undefined : status,
                 completedAt: editingTaskId ? undefined : (status === 'done' ? new Date().toISOString() : null),
-                approach: approach || 'default',
                 assignee: assignee || 'agent',
                 scheduledDate: scheduledDate || null,
                 dueDate: dueDate || null,
                 workstreamId: workstreamInput.trim()
                     ? (resolvedWorkstream?.id || workstreamInput.trim())
                     : null,
-                checklistItems,
-                comments,
                 taxonomies: formTaxonomies,
                 ...(!editingTaskId ? {
                     createdAt: new Date().toISOString(),
                     createdBy: 'user',
                 } : {}),
             };
+            if (editingTaskId && existingTask) {
+                for (const [key, value] of Object.entries(body)) {
+                    if (value === undefined || canonicalWorkspaceSyncJson(value ?? null)
+                        === canonicalWorkspaceSyncJson(existingTask[key] ?? null)) {
+                        delete body[key];
+                    }
+                }
+            }
+            if (checklistChanged)
+                body.checklistItems = checklistItems;
+            if (!editingTaskId)
+                body.comments = comments;
             if (!editingTaskId || attachmentsDirty) {
-                body.attachments = attachments;
+                body.attachments = draftAttachments;
             }
-            if (editingTaskId) {
+            if (editingTaskId && Object.keys(body).length > 0) {
                 body.saveSource = source;
             }
-            const res = await fetch(url, {
+            if (editingTaskId && updateTask) {
+                const saved = await updateTask(editingTaskId, body);
+                setLoading(false);
+                setAutoSaveState(saved === false ? 'error' : 'saved');
+                if (saved === false)
+                    return false;
+                setLastUsedCategory(sanitizedCategory);
+                setAttachmentsDirty(false);
+                return true;
+            }
+            if (!editingTaskId && createTaskDurably) {
+                let durableResult;
+                try {
+                    durableResult = await createTaskDurably(body);
+                }
+                catch (error) {
+                    console.error('Durable task create failed before a conclusive result.', error);
+                    const message = 'Task creation confirmation was interrupted. Retry the same task to confirm it safely.';
+                    setError(message);
+                    if (!quiet)
+                        pushNotice(message, 'error');
+                    setLoading(false);
+                    return false;
+                }
+                if (durableResult) {
+                    if (durableResult.state === 'failed'
+                        || durableResult.state === 'rejected'
+                        || durableResult.state === 'ambiguous'
+                        || durableResult.state === 'disabled') {
+                        const message = durableResult.state === 'disabled'
+                            ? 'Task was not created because durable capture became unavailable. Reload before retrying.'
+                            : durableResult.state === 'failed'
+                                ? 'Task was not created because durable local preparation failed. Retry the task.'
+                                : durableResult.state === 'rejected'
+                                    ? `Task was not created because durable capture rejected it${durableResult.errorCode ? ` (${durableResult.errorCode})` : ''}.`
+                                    : 'Task creation confirmation was interrupted. Retry the same task to confirm it safely.';
+                        setError(message);
+                        if (!quiet)
+                            pushNotice(message, 'error');
+                        setLoading(false);
+                        return false;
+                    }
+                    if (durableResult.task) {
+                        const createdTask = normalizeTaskFromApi(durableResult.task);
+                        createdTaskRef.current = createdTask;
+                        mergeTaskFromServer(createdTask);
+                    }
+                    if (durableResult.recoveredChangedInput) {
+                        suppressNextCreateSuccessNoticeRef.current = true;
+                        pushNotice('Recovered the previously interrupted task. Changes made after the interrupted submission were not applied.', 'info');
+                    }
+                    if (durableResult.state === 'pending') {
+                        if (durableResult.pendingReason !== 'queued') {
+                            suppressNextCreateSuccessNoticeRef.current = true;
+                            pushNotice(durableResult.pendingReason === 'auth'
+                                ? 'Task created locally. Sign in to finish cloud sync.'
+                                : durableResult.pendingReason === 'sync-disabled'
+                                    ? 'Task created locally. Turn on sync to send it to cloud.'
+                                    : 'Task created locally. Cloud sync will retry automatically.', 'info');
+                        }
+                        setError('');
+                    }
+                    else if (durableResult.state === 'blocked') {
+                        suppressNextCreateSuccessNoticeRef.current = true;
+                        const message = `Task created locally, but cloud sync is blocked${durableResult.errorCode ? ` (${durableResult.errorCode})` : ''}.`;
+                        setError(message);
+                        pushNotice(message, 'error');
+                    }
+                    else {
+                        setError('');
+                    }
+                    setLastUsedCategory(sanitizedCategory);
+                    setAttachmentsDirty(false);
+                    setLoading(false);
+                    return true;
+                }
+            }
+            let recoveredChangedHttpCreate = false;
+            let operationId = null;
+            let requestBody = body;
+            if (durableTaskHttpRootActivationEnabled && !editingTaskId) {
+                if (!taskHttpMutationClientRef.current) {
+                    taskHttpMutationClientRef.current = taskHttpMutationClient || createCloudTaskHttpMutationClient();
+                }
+                const attempt = await taskHttpMutationClientRef.current.prepareCreate(workspaceId, body);
+                operationId = attempt.operationId;
+                requestBody = attempt.body;
+                recoveredChangedHttpCreate = attempt.recoveredChangedInput;
+            }
+            const requestInit = {
                 method,
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(body),
-            });
+                body: JSON.stringify(requestBody),
+            };
+            const res = operationId
+                ? await fetchTaskHttpMutation(url, requestInit, operationId)
+                : await fetch(url, requestInit);
             if (!res.ok) {
+                if (!editingTaskId && operationId && await isConclusiveTaskHttpResponse(res)) {
+                    await taskHttpMutationClientRef.current?.confirmCreate(workspaceId, operationId);
+                }
                 const data = await res.json();
-                const message = data.message || `Failed to ${editingTaskId ? 'update' : 'save'} task`;
+                const message = data.error || data.message || `Failed to ${editingTaskId ? 'update' : 'save'} task`;
                 setError(message);
                 if (!quiet) {
                     pushNotice(message, 'error');
@@ -152,9 +355,27 @@ export function useTaskFormActions(input) {
                 return false;
             }
             const updatedTask = await res.json().catch(() => null);
-            if (editingTaskId && updatedTask && typeof updatedTask === 'object') {
-                mergeTaskFromServer(updatedTask);
-                queueWorkspaceSyncFromAuthoritativeTaskState();
+            if (!editingTaskId
+                && operationId
+                && (!updatedTask || typeof updatedTask !== 'object' || String(updatedTask.id || '') !== String(requestBody.id || ''))) {
+                throw new Error('Durable cloud task create returned an invalid authoritative task identity.');
+            }
+            if (!editingTaskId && operationId) {
+                await taskHttpMutationClientRef.current?.confirmCreate(workspaceId, operationId);
+            }
+            if (recoveredChangedHttpCreate) {
+                suppressNextCreateSuccessNoticeRef.current = true;
+                pushNotice('Recovered the previously interrupted task. Changes made after the interrupted submission were not applied.', 'info');
+            }
+            if (updatedTask && typeof updatedTask === 'object') {
+                const normalizedTask = normalizeTaskFromApi(updatedTask);
+                mergeTaskFromServer(normalizedTask);
+                if (editingTaskId) {
+                    queueWorkspaceSyncFromAuthoritativeTaskState();
+                }
+                else {
+                    createdTaskRef.current = normalizedTask;
+                }
             }
             setLastUsedCategory(sanitizedCategory);
             setAttachmentsDirty(false);
@@ -164,7 +385,8 @@ export function useTaskFormActions(input) {
             }
             return true;
         }
-        catch {
+        catch (error) {
+            console.error('Failed to save task.', error);
             setError('Failed to connect to server');
             if (!quiet) {
                 pushNotice('Failed to connect to server', 'error');
@@ -178,17 +400,20 @@ export function useTaskFormActions(input) {
     }, [
         activeCategories,
         apiEndpoint,
-        approach,
         assignee,
-        attachments,
         attachmentsDirty,
         category,
         checklistItems,
         comments,
         complexity,
-        description,
         dueDate,
+        createTaskDurably,
+        durableTaskHttpRootActivationEnabled,
+        workspaceId,
+        taskHttpMutationClient,
+        updateTask,
         editingTaskId,
+        editingReadOnlyMode,
         formTaxonomies,
         getPreferredCategoryValue,
         mergeTaskFromServer,
@@ -196,6 +421,7 @@ export function useTaskFormActions(input) {
         priority,
         pushNotice,
         queueWorkspaceSyncFromAuthoritativeTaskState,
+        readTextDraft,
         resolveWorkstreamIdInput,
         setAttachmentsDirty,
         setError,
@@ -203,25 +429,40 @@ export function useTaskFormActions(input) {
         setLoading,
         scheduledDate,
         status,
-        title,
         taxonomies,
         type
     ]);
     const runSaveFlow = useCallback(async () => {
         const success = await saveTask({ source: 'manual' });
         if (success) {
-            if (!editingTaskId) {
+            if (!editingTaskId && !suppressNextCreateSuccessNoticeRef.current) {
                 pushNotice('Task added successfully', 'success');
             }
+            suppressNextCreateSuccessNoticeRef.current = false;
             if (activeTab === 'add' && !editingTaskId) {
+                const createdTask = createdTaskRef.current;
+                if (createdTask && onTaskCreateAccepted) {
+                    try {
+                        await onTaskCreateAccepted(createdTask);
+                    }
+                    catch (error) {
+                        console.warn('Task create draft upload promotion failed.', error);
+                        pushNotice('Task created successfully. Temporary image cleanup will retry automatically.', 'info');
+                    }
+                }
+                if (createdTask && onTaskCreated) {
+                    onTaskCreated(createdTask);
+                    return;
+                }
                 resetForm();
                 setActiveTab('tasks');
                 await fetchTasks();
             }
         }
-    }, [activeTab, editingTaskId, fetchTasks, pushNotice, resetForm, saveTask, setActiveTab]);
+    }, [activeTab, editingTaskId, fetchTasks, onTaskCreateAccepted, onTaskCreated, pushNotice, resetForm, saveTask, setActiveTab]);
     useEffect(() => {
         clearAutoSaveTimer();
+        queuedAutoSaveRef.current = null;
         if (!editingTaskId) {
             setLastSavedDraftSignature(null);
             setAutoSaveState('idle');
@@ -232,39 +473,47 @@ export function useTaskFormActions(input) {
     }, [clearAutoSaveTimer, editingTaskId]);
     const flushAutoSave = useCallback(async () => {
         clearAutoSaveTimer();
+        if (editingReadOnlyMode) {
+            return true;
+        }
         if (!editingTaskId || lastSavedDraftSignature === null) {
-            return;
+            return true;
         }
-        const draftSignature = buildTaskDraftSignature();
+        const textDraft = readTextDraft();
+        const draftSignature = buildTaskDraftSignature(textDraft);
         if (draftSignature === lastSavedDraftSignature) {
-            return;
-        }
-        if (!title.trim() || (dueDate && scheduledDate && dueDate < scheduledDate)) {
-            return;
+            return true;
         }
-        const success = await saveTask({ quiet: true, source: 'autosave' });
-        if (success) {
-            setLastSavedDraftSignature(draftSignature);
+        if (!textDraft.title.trim() || (dueDate && scheduledDate && dueDate < scheduledDate)) {
+            return false;
         }
+        const success = await enqueueAutoSave({
+            signature: draftSignature,
+            save: () => saveTask({ quiet: true, source: 'autosave', textDraft }),
+        });
+        return success && buildTaskDraftSignature() === draftSignature;
     }, [
         buildTaskDraftSignature,
         clearAutoSaveTimer,
         dueDate,
         editingTaskId,
+        editingReadOnlyMode,
+        enqueueAutoSave,
         lastSavedDraftSignature,
+        readTextDraft,
         saveTask,
         scheduledDate,
-        title
     ]);
     useEffect(() => {
-        if (!editingTaskId || lastSavedDraftSignature === null) {
+        if (!editingTaskId || editingReadOnlyMode || lastSavedDraftSignature === null) {
             return;
         }
-        const draftSignature = buildTaskDraftSignature();
+        const textDraft = readTextDraft();
+        const draftSignature = buildTaskDraftSignature(textDraft);
         if (draftSignature === lastSavedDraftSignature) {
             return;
         }
-        if (!title.trim()) {
+        if (!textDraft.title.trim()) {
             setAutoSaveState('idle');
             return;
         }
@@ -274,24 +523,36 @@ export function useTaskFormActions(input) {
         }
         setAutoSaveState((current) => current === 'error' ? 'error' : 'idle');
         clearAutoSaveTimer();
-        autoSaveTimerRef.current = window.setTimeout(async () => {
-            const success = await saveTask({ quiet: true, source: 'autosave' });
-            if (success) {
-                setLastSavedDraftSignature(draftSignature);
+        const savedAssignee = (() => {
+            try {
+                return String(JSON.parse(lastSavedDraftSignature).assignee || '');
             }
-        }, 700);
+            catch {
+                return '';
+            }
+        })();
+        const saveDelay = savedAssignee !== String(assignee || 'agent') ? 0 : 1400;
+        autoSaveTimerRef.current = window.setTimeout(async () => {
+            await enqueueAutoSave({
+                signature: draftSignature,
+                save: () => saveTask({ quiet: true, source: 'autosave', textDraft }),
+            });
+        }, saveDelay);
         return () => {
             clearAutoSaveTimer();
         };
     }, [
         buildTaskDraftSignature,
+        assignee,
         clearAutoSaveTimer,
         dueDate,
         editingTaskId,
+        editingReadOnlyMode,
+        enqueueAutoSave,
         lastSavedDraftSignature,
+        readTextDraft,
         saveTask,
         scheduledDate,
-        title
     ]);
     const handleSubmit = useCallback(async (event) => {
         event.preventDefault();
@@ -312,20 +573,39 @@ export function useTaskFormActions(input) {
         if (!editingTaskId || !text.trim())
             return;
         const nextText = text.trim();
+        const pending = pendingCommentMutationRef.current;
+        const attempt = pending?.taskId === editingTaskId && pending.text === nextText
+            ? pending
+            : {
+                taskId: editingTaskId,
+                text: nextText,
+                operationId: globalThis.crypto?.randomUUID?.() || `comment-operation-${Date.now()}`,
+                commentId: `comment-${globalThis.crypto?.randomUUID?.() || Date.now()}`,
+                timestamp: new Date().toISOString(),
+            };
+        pendingCommentMutationRef.current = attempt;
         try {
             const res = await fetch(`/api/taskforce/task/${editingTaskId}/comment`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ text: nextText, author: 'user' })
+                headers: { 'Content-Type': 'application/json', 'x-taskforce-operation-id': attempt.operationId },
+                body: JSON.stringify({
+                    text: nextText,
+                    commentId: attempt.commentId,
+                    timestamp: attempt.timestamp,
+                })
             });
             if (!res.ok) {
+                const conclusive = await isConclusiveTaskHttpResponse(res);
                 const data = await res.json().catch(() => ({}));
                 const message = data.error || 'Failed to add comment.';
+                if (conclusive)
+                    pendingCommentMutationRef.current = null;
                 setError(message);
                 pushNotice(message, 'error');
                 return;
             }
             const updatedTask = await res.json().catch(() => null);
+            pendingCommentMutationRef.current = null;
             setNewCommentText('');
             if (updatedTask && typeof updatedTask === 'object') {
                 const normalizedTask = normalizeTaskFromApi(updatedTask);

package/dist/hooks/tasks/useTaskReferenceContract.d.ts

@@ -0,0 +1,5 @@
+import type { TaskItem } from '../../types';
+import { type TaskReferenceContract } from '../../utils/taskReferences';
+type TaskReferenceSource = Pick<TaskItem, 'id' | 'referenceNumber' | 'referenceLabel' | 'localReferenceNumber'>;
+export declare function useTaskReferenceContract(tasks: TaskReferenceSource[], activate: (taskId: string) => void): TaskReferenceContract;
+export {};

package/dist/hooks/tasks/useTaskReferenceContract.js

@@ -0,0 +1,17 @@
+import { useLayoutEffect, useMemo, useRef } from 'react';
+import { createTaskReferenceIndex, } from '../../utils/taskReferences';
+export function useTaskReferenceContract(tasks, activate) {
+    const activateRef = useRef(activate);
+    useLayoutEffect(() => {
+        activateRef.current = activate;
+    }, [activate]);
+    const nextReferenceIndex = useMemo(() => createTaskReferenceIndex(tasks), [tasks]);
+    const referenceIndex = useMemo(() => nextReferenceIndex, 
+    // The revision represents the complete token-to-task mapping. Retain the
+    // previous index when task content changes without changing that mapping.
+    [nextReferenceIndex.revision]);
+    return useMemo(() => ({
+        resolve: referenceIndex.resolve,
+        activate: (taskId) => activateRef.current(taskId),
+    }), [referenceIndex]);
+}

package/dist/hooks/tasks/useTaskRelationships.d.ts

@@ -1,14 +1,12 @@
 import type { TaskItem, WorkstreamItem } from '../../types';
 interface UseTaskRelationshipsInput {
     editingTaskId: string | null;
-    mergeTaskFromServer: (task: unknown) => void;
     workstreamInput: string;
     pushNotice: (message: string, level?: 'success' | 'error' | 'info') => void;
-    queueWorkspaceSyncFromAuthoritativeTaskState: () => void;
     relationshipTasks: TaskItem[];
     resolveWorkstreamIdInput: (value: string) => WorkstreamItem | null;
     setError: (value: string) => void;
-    fetchTasks: (isSilent?: boolean) => Promise<void>;
+    updateTask: (taskId: string, updates: Partial<TaskItem>) => Promise<boolean | void>;
 }
 export declare function useTaskRelationships(input: UseTaskRelationshipsInput): {
     handleSetWorkstreamForCurrentTask: (workstreamIdOverride?: string | null) => Promise<void>;