/**
 * GoingsOn - Tasks Module
 * Task CRUD, subtasks, annotations, event handlers.
 * Form definitions live in task-forms.js.
 * Board/view mode live in task-board.js.
 * Filter/sort/pagination/selection live in tasks-filter.js.
 * Row rendering lives in tasks-render.js.
 */

// ============ Tasks Module ============

(function() {
    'use strict';
    const esc = GoingsOn.utils.escapeHtml;
    const escAttr = GoingsOn.utils.escapeAttrValue;
    const escArg = GoingsOn.utils.escapeHandlerArg;

    // ============ Task Selection & Pagination ============

    const taskSelection = new GoingsOn.SelectionManager('task', '#task-list-container', 'task-bulk-actions');
    const taskPagination = new GoingsOn.PaginationManager('task', GoingsOn.state.itemsPerPage);

    // Virtual scroller instance
    let taskScroller = null;

    // CHRONIC-E structural fix (ultra-fuzz Run #28 S3/S4). The state pub/sub was
    // dead — not one subscriber existed, so optimistic mutations that called
    // state.set('tasks', …) never re-rendered, and handlers fell back to a full
    // reload (refetch page 1, scroll to top) on every single-item edit. Wire
    // exactly one subscriber so any task-state change refreshes the scroller in
    // place. `suppressTaskRender` gates it during the full rebuild in
    // renderFilteredTasks: that path sets state to raw (un-decorated) rows mid-way
    // and (re)creates the scroller on the next line, so a subscriber-driven
    // refresh there would render half-built rows — the re-entrancy trap flagged in
    // the GO todo. Outside that window, set() is the render trigger.
    let suppressTaskRender = false;
    GoingsOn.state.subscribe('tasks', () => {
        if (suppressTaskRender) return;
        if (taskScroller) taskScroller.refresh();
    });

    // Incremental pagination state. The task list streams in pages as the user
    // scrolls (via the scroller's onNeedMore hook) instead of capping at a fixed
    // row count, so a large task set is fully reachable. baseFilters holds the
    // current filter/sort so each page request is consistent.
    const TASK_PAGE_SIZE = 200;
    const taskPaging = { loadedCount: 0, total: 0, baseFilters: null };

    /** Attach the display-only fields the row renderer expects. */
    function _decorateTasks(tasks) {
        return tasks.map(t => ({ ...t, displayDescription: t.description }));
    }

    /**
     * Fetch and append the next page of tasks. Wired to the scroller's
     * onNeedMore hook. No-ops once every task is loaded (leaving the trigger
     * disarmed); on error it surfaces a toast and stops paging rather than
     * spinning.
     */
    async function loadMoreTasks() {
        if (taskPaging.loadedCount >= taskPaging.total || !taskPaging.baseFilters) return;
        let response;
        try {
            response = await GoingsOn.api.tasks.listFiltered({
                ...taskPaging.baseFilters,
                offset: taskPaging.loadedCount,
                limit: TASK_PAGE_SIZE,
            });
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to load more tasks'), 'error');
            return;
        }
        const all = (GoingsOn.state.tasks || []).concat(_decorateTasks(response.tasks));
        GoingsOn.state.set('tasks', all);
        taskPaging.loadedCount = all.length;
        taskPaging.total = response.total;
        taskSelection.setItems(all);
        _updateTaskCount(taskPaging.total, taskPaging.loadedCount);
        // Re-arms the onNeedMore trigger so the next page can load on further scroll.
        if (taskScroller) taskScroller.refresh();
    }

    // ============ Delegated references ============

    const getTaskFormFields = (...args) => GoingsOn.taskForms.getTaskFormFields(...args);
    const setupMilestoneSelect = (...args) => GoingsOn.taskForms.setupMilestoneSelect(...args);
    const renderTaskBadges = (...args) => GoingsOn.tasksRender.renderTaskBadges(...args);
    const formatRecurrence = (...args) => GoingsOn.tasksRender.formatRecurrence(...args);
    const renderTaskRow = (...args) => GoingsOn.tasksRender.renderTaskRow(...args);
    const renderSubtasksModal = (...args) => GoingsOn.tasksRender.renderSubtasksModal(...args);
    const renderStatusTokensModal = (...args) => GoingsOn.tasksRender.renderStatusTokensModal(...args);

    // ============ Core Functions ============

    /**
     * Load and render the task list for the current view mode (list or board).
     */
    async function load() {
        if (GoingsOn.cache.isFresh('tasks')) return;

        GoingsOn.tasksFilter.populateProjectFilter();
        // Phase 7 Tier 4 — restore filter state from URL on every load. This
        // makes reload, deep-link, and back-button preserve the user's view.
        // populateProjectFilter must run first so the project <option> exists.
        GoingsOn.tasksFilter.restoreFiltersFromUrl();

        if (GoingsOn.taskBoard.getViewMode() === 'board') {
            await GoingsOn.taskBoard.renderBoard();
        } else {
            await renderFilteredTasks();
        }

        GoingsOn.cache.markLoaded('tasks');
    }

    /**
     * Fetch filtered/sorted tasks from backend and render via virtual scroller.
     */
    /**
     * Update the "N tasks" count chip in the filter bar. While pages are still
     * streaming in (shown < total) it reads "X of N"; once everything is loaded
     * it reads the plain total.
     */
    function _updateTaskCount(total, shown) {
        const el = document.getElementById('task-count');
        if (!el) return;
        if (typeof total !== 'number' || total < 0) {
            el.textContent = '';
            el.classList.remove('filter-count--capped');
            return;
        }
        const noun = total === 1 ? 'task' : 'tasks';
        if (shown < total) {
            el.textContent = `${shown} of ${total} ${noun}`;
            el.classList.add('filter-count--capped');
        } else {
            el.textContent = `${total} ${noun}`;
            el.classList.remove('filter-count--capped');
        }
    }

    async function renderFilteredTasks() {
        const container = document.getElementById('task-list-container');
        const uiFilters = GoingsOn.tasksFilter.getFilters();

        // Build the filter/sort query for the backend. Offset/limit are added
        // per page — the list streams in via the scroller's onNeedMore hook.
        const backendFilters = {
            showSnoozed: uiFilters.showSnoozed,
            waitingOnly: uiFilters.waitingOnly,
        };

        // Status: UI uses lowercase ('pending'), backend expects capitalized ('Pending')
        if (uiFilters.status) {
            backendFilters.status = uiFilters.status.charAt(0).toUpperCase() + uiFilters.status.slice(1);
        }

        // Project ID
        if (uiFilters.projectId) {
            backendFilters.projectId = uiFilters.projectId;
        }

        // Milestone ID
        if (uiFilters.milestoneId) {
            backendFilters.milestoneId = uiFilters.milestoneId;
        }

        // Priority: UI uses 'H', 'M', 'L', backend expects 'High', 'Medium', 'Low'
        if (uiFilters.priority) {
            const priorityMap = { H: 'High', M: 'Medium', L: 'Low' };
            backendFilters.priority = priorityMap[uiFilters.priority] || uiFilters.priority;
        }

        // Add sorting parameters (backend handles sorting)
        backendFilters.sortColumn = GoingsOn.tasksFilter.getSortColumn();
        backendFilters.sortDirection = GoingsOn.tasksFilter.getSortDirection();

        // Reset paging for the new filter/sort and fetch the first page.
        taskPaging.baseFilters = backendFilters;
        taskPaging.loadedCount = 0;
        taskPaging.total = 0;

        // Suppress the state subscriber for the whole rebuild — see the subscribe()
        // wiring above. The finally restores it so later optimistic edits re-render.
        suppressTaskRender = true;
        try {
        let response;
        try {
            // Fetch the first page of filtered/sorted tasks from the backend.
            response = await GoingsOn.api.tasks.listFiltered({
                ...backendFilters,
                offset: 0,
                limit: TASK_PAGE_SIZE,
            });
            // Update cache with the first page.
            GoingsOn.state.set('tasks', response.tasks);
        } catch (err) {
            container.innerHTML = `<div class="loading loading--error">Failed to load tasks. <button class="btn-link" data-act="tasks.renderFilteredTasks">Try again</button></div>`;
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to load tasks'), 'error', {
                action: { label: 'Retry', fn: renderFilteredTasks },
                duration: 8000,
            });
            return;
        }

        if (response.total === 0) {
            _updateTaskCount(0, 0);
            const isDefaultFilter = uiFilters.status === 'pending' && !uiFilters.projectId && !uiFilters.priority && !uiFilters.waitingOnly;
            let emptyHtml;
            if (isDefaultFilter) {
                // Check if user has any tasks at all (completed or otherwise)
                let hasAnyTasks = false;
                try {
                    const allResp = await GoingsOn.api.tasks.listFiltered({ offset: 0, limit: 1 });
                    hasAnyTasks = allResp.total > 0;
                } catch (_) { /* fall through */ }

                if (hasAnyTasks) {
                    // All tasks done — celebration!
                    emptyHtml = GoingsOn.ui.renderEmptyState('All clear. No pending tasks.', null, null, 'tasks');
                } else {
                    // Brand new user — onboarding
                    emptyHtml = GoingsOn.ui.renderEmptyState('No tasks yet.', 'New Task', 'tasks.openNew', 'tasks');
                }
            } else {
                emptyHtml = GoingsOn.ui.renderEmptyState('No tasks match the current filters.', 'New Task', 'tasks.openNew');
            }
            container.innerHTML = emptyHtml;
            // Hide pagination when using virtual scrolling
            const paginationEl = document.getElementById('task-pagination');
            if (paginationEl) paginationEl.classList.add('hidden');
            // Destroy existing scroller
            if (taskScroller) {
                taskScroller.destroy();
                taskScroller = null;
            }
            return;
        }

        // Backend already returns tasks sorted by sortColumn/sortDirection.
        const displayTasks = _decorateTasks(response.tasks);
        taskPaging.loadedCount = displayTasks.length;
        taskPaging.total = response.total;

        // Phase 7 Tier 2 #9 — surface the count so users can see "247 tasks";
        // reads "X of N" while later pages stream in on scroll.
        _updateTaskCount(taskPaging.total, taskPaging.loadedCount);

        // Update state with sorted tasks (already sorted by backend)
        GoingsOn.state.set('tasks', displayTasks);

        // Update selection manager with current items for data-based range selection
        taskSelection.setItems(displayTasks);

        // Update sort arrow UI
        GoingsOn.tasksFilter.updateSortArrows();

        // Hide pagination - virtual scrolling replaces it
        const paginationEl = document.getElementById('task-pagination');
        if (paginationEl) paginationEl.classList.add('hidden');

        // Initialize or refresh virtual scroller. onNeedMore streams later pages
        // in as the user scrolls toward the tail.
        if (!taskScroller) {
            taskScroller = new GoingsOn.VirtualScroller({
                container: container,
                renderItem: renderTaskRow,
                getItems: () => GoingsOn.state.tasks || [],
                rowHeight: { estimated: 52, measure: true },
                overscan: 5,
                onNeedMore: loadMoreTasks,
            });
        } else {
            taskScroller.refresh();
        }
        } finally {
            suppressTaskRender = false;
        }
    }

    function openNew() {
        GoingsOn.ui.openFormModal({
            title: 'New Task',
            entityType: 'task',
            isEdit: false,
            fields: getTaskFormFields(),
            onSubmit: create,
        });
        setupMilestoneSelect('task', 'new');
        GoingsOn.taskForms.initRecurrenceConfig('task', 'recurrence');
    }

    /**
     * Open the new task form modal pre-filled for a specific project.
     * @param {string} projectId - Project to pre-select in the form
     */
    function openNewForProject(projectId) {
        GoingsOn.ui.openFormModal({
            title: 'New Task',
            entityType: 'task',
            isEdit: false,
            fields: getTaskFormFields(null, projectId),
            onSubmit: create,
        });
        setupMilestoneSelect('task', 'new', projectId);
    }

    /**
     * Create a new task from form data.
     * @param {Object} data - Form data with description, project_id, priority, due, tags, etc.
     */
    async function create(data) {
        const tagsValue = data.tags?.trim() || '';
        const form = document.querySelector('.modal-content form');
        const recurrenceRule = form ? GoingsOn.taskForms.collectRecurrenceRule(form, 'task', data.recurrence) : null;
        const input = {
            description: data.description,
            projectId: data.project_id || null,
            priority: data.priority,
            due: data.due ? new Date(data.due).toISOString() : null,
            tags: tagsValue ? tagsValue.split(',').map(t => t.trim()).filter(t => t) : [],
            recurrence: data.recurrence,
            recurrenceRule,
            contactId: data.contact_id || null,
            milestoneId: data.milestone_id || null,
            estimatedMinutes: data.estimated_minutes ? parseInt(data.estimated_minutes, 10) : null,
        };

        const reloadFns = [load];
        const currentProjectId = GoingsOn.getCurrentProjectId();
        if (currentProjectId) {
            reloadFns.push(() => GoingsOn.projects.loadDashboard(currentProjectId));
        }

        await GoingsOn.ui.apiCall(GoingsOn.api.tasks.create(input), {
            successMessage: 'Task created!',
            errorMessage: 'Failed to create task',
            onSuccess: () => GoingsOn.cache.invalidate('tasks'),
            reload: reloadFns,
        });
    }

    /**
     * Open the task actions modal with start, complete, edit, snooze, etc.
     * @param {string} id - Task ID
     */
    async function openActions(id) {
        const task = await GoingsOn.api.tasks.get(id);
        const isSnoozed = task && task.isSnoozed;

        const content = `
            <div class="stack stack-2">
                <button class="btn btn-secondary" data-act="tasks.start" data-a1="${escAttr(id)}">Start Task</button>
                <button class="btn btn-secondary" data-act="tasks.complete" data-a1="${escAttr(id)}">Complete Task</button>
                <button class="btn btn-secondary" data-act="tasks.openEdit" data-a1="${escAttr(id)}">Edit Task</button>
                <button class="btn btn-secondary" data-act="tasks.openSubtasks" data-a1="${escAttr(id)}">Manage Subtasks</button>
                <button class="btn btn-secondary" data-act="tasks.addAnnotation" data-a1="${escAttr(id)}">Add Note</button>
                <button class="btn btn-secondary" data-act="attachments.openPanel" data-a1="${escAttr(id)}" data-args='["@a1", null]'>Attachments</button>
                <hr class="hr-soft">
                ${isSnoozed
                    ? `<button class="btn btn-secondary" data-act="snooze.unsnooze" data-a1="task" data-a2="${escAttr(id)}">Unsnooze Task</button>`
                    : `<button class="btn btn-secondary" data-act="snooze.openModal" data-a1="task" data-a2="${escAttr(id)}">Snooze Task</button>`
                }
                <button class="btn btn-secondary" data-act="dayPlan.openScheduleTaskModal" data-a1="${escAttr(id)}">Schedule Time Block</button>
                <button class="btn btn-secondary" data-act="ui.closeModalThen" data-a1="timeTracking.startTimer" data-a2="${escAttr(id)}">Track Time</button>
                <button class="btn btn-secondary" data-act="ui.closeModalThen" data-a1="focusTimer.start" data-a2="${escAttr(id)}">Focus Mode (25/5)</button>
                <hr class="hr-soft">
                <button class="btn btn-secondary text-accent-red" data-act="tasks.delete" data-a1="${escAttr(id)}">Delete Task</button>
            </div>
        `;
        GoingsOn.ui.openModal('Task Actions', content);
    }

    /**
     * Fetch a task and open the edit form modal.
     * @param {string} id - Task ID to edit
     */
    async function openEdit(id) {
        try {
            const task = await GoingsOn.api.tasks.get(id);
            if (!task) {
                GoingsOn.ui.showToast('Task not found', 'error');
                return;
            }

            const extraContent = task.source_email_id ? `
                <div class="form-group source-email-link">
                    <label class="form-label">Source Email</label>
                    <button type="button" class="btn btn-secondary" data-act="ui.closeModalThen" data-a1="emails.open" data-a2="${escAttr(task.source_email_id)}">
                        View Related Email
                    </button>
                </div>
            ` : '';

            GoingsOn.ui.openFormModal({
                title: 'Edit Task',
                entityType: 'task',
                isEdit: true,
                entityId: id,
                fields: getTaskFormFields(task),
                onSubmit: (data) => update(id, data),
                extraContent,
            });
            setupMilestoneSelect('task', 'edit', task.projectId, task.milestoneId);
            GoingsOn.taskForms.initRecurrenceConfig('task', 'recurrence');
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to load task'), 'error');
        }
    }

    /**
     * Update an existing task from form data.
     * @param {string} id - Task ID to update
     * @param {Object} data - Form data with description, project_id, status, priority, etc.
     */
    async function update(id, data) {
        const tagsValue = data.tags?.trim() || '';
        const form = document.querySelector('.modal-content form');
        const recurrenceRule = form ? GoingsOn.taskForms.collectRecurrenceRule(form, 'task', data.recurrence) : null;
        const input = {
            description: data.description,
            projectId: data.project_id || null,
            status: data.status,
            priority: data.priority,
            due: data.due ? new Date(data.due).toISOString() : null,
            tags: tagsValue ? tagsValue.split(',').map(t => t.trim()).filter(t => t) : [],
            recurrence: data.recurrence,
            recurrenceRule,
            contactId: data.contact_id || null,
            milestoneId: data.milestone_id || null,
            estimatedMinutes: data.estimated_minutes ? parseInt(data.estimated_minutes, 10) : null,
        };

        const reloadFns = [load];
        const currentProjectId = GoingsOn.getCurrentProjectId();
        if (currentProjectId) {
            reloadFns.push(() => GoingsOn.projects.loadDashboard(currentProjectId));
        }

        await GoingsOn.ui.apiCall(GoingsOn.api.tasks.update(id, input), {
            successMessage: 'Task updated!',
            errorMessage: 'Failed to update task',
            onSuccess: () => GoingsOn.cache.invalidate('tasks'),
            reload: reloadFns,
        });
    }

    /**
     * Fetch a task's subtasks and open the subtasks management modal.
     * @param {string} taskId - Task ID to manage subtasks for
     */
    async function openSubtasks(taskId) {
        try {
            const task = await GoingsOn.api.tasks.get(taskId);
            if (!task) {
                GoingsOn.ui.showToast('Task not found', 'error');
                return;
            }

            renderSubtasksModal(taskId, task.subtasks || []);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to load task'), 'error');
        }
    }

    /**
     * Open a picker modal to link another task as a subtask.
     * @param {string} parentTaskId - Parent task to link a subtask to
     */
    async function openLinkTaskPicker(parentTaskId) {
        // Get all pending/started tasks (excluding the parent task)
        const filters = { status: 'Pending', limit: 100 };
        const response = await GoingsOn.api.tasks.listFiltered(filters);
        const availableTasks = response.tasks.filter(t => t.id !== parentTaskId);

        if (availableTasks.length === 0) {
            GoingsOn.ui.showToast('No other tasks available to link', 'info');
            return;
        }

        const taskOptions = availableTasks.map(t => `
            <div class="link-task-item" data-act="tasks.linkTask" data-a1="${escAttr(parentTaskId)}" data-a2="${escAttr(t.id)}">
                <span class="link-task-desc">${esc(t.description)}</span>
                ${t.projectName ? `<span class="link-task-project">${esc(t.projectName)}</span>` : ''}
            </div>
        `).join('');

        const content = `
            <p class="link-task-prompt">Select a task to link as a subtask. The linked task's completion will sync with this subtask.</p>
            <div class="link-task-list">
                ${taskOptions}
            </div>
            <div class="form-actions form-actions--top-spaced">
                <button type="button" class="btn btn-secondary" data-act="tasks.openSubtasks" data-a1="${escAttr(parentTaskId)}">Cancel</button>
            </div>
        `;
        GoingsOn.ui.openModal('Link Task', content);
    }

    /**
     * Link an existing task as a subtask of the parent task.
     * @param {string} parentTaskId - Parent task ID
     * @param {string} linkedTaskId - Task ID to link as subtask
     */
    async function linkTask(parentTaskId, linkedTaskId) {
        try {
            await GoingsOn.api.subtasks.addLink(parentTaskId, linkedTaskId);
            GoingsOn.ui.showToast('Task linked!', 'success');
            // Reload subtasks modal
            const task = await GoingsOn.api.tasks.get(parentTaskId);
            renderSubtasksModal(parentTaskId, task.subtasks || []);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to link task'), 'error');
        }
    }

    function closeSubtasksAndRefresh() {
        GoingsOn.ui.closeModal();
        // Refresh task list if we're on the tasks view
        const currentView = GoingsOn.getCurrentView();
        if (currentView === 'tasks') {
            load();
        }
        // Refresh project dashboard if we're viewing one
        const currentProjectId = GoingsOn.getCurrentProjectId();
        if (currentProjectId) {
            GoingsOn.projects.loadDashboard(currentProjectId);
        }
    }

    async function addSubtask(e, taskId) {
        e.preventDefault();
        const form = e.target;
        const text = form.subtask_text.value.trim();
        if (!text) return;

        try {
            await GoingsOn.api.subtasks.add(taskId, text);
            form.subtask_text.value = '';
            // Reload the subtasks modal
            const task = await GoingsOn.api.tasks.get(taskId);
            renderSubtasksModal(taskId, task.subtasks || []);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to add subtask'), 'error');
        }
    }

    async function toggleSubtask(taskId, subtaskId) {
        try {
            await GoingsOn.api.subtasks.toggle(taskId, subtaskId);
            // Reload the subtasks modal
            const task = await GoingsOn.api.tasks.get(taskId);
            renderSubtasksModal(taskId, task.subtasks || []);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to toggle subtask'), 'error');
        }
    }

    async function deleteSubtask(taskId, subtaskId) {
        const confirmed = await GoingsOn.ui.confirmDelete('subtask');
        if (!confirmed) return;

        try {
            await GoingsOn.api.subtasks.delete(taskId, subtaskId);
            // Reload the subtasks modal
            const task = await GoingsOn.api.tasks.get(taskId);
            renderSubtasksModal(taskId, task.subtasks || []);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to delete subtask'), 'error');
        }
    }

    // ============ Status tokens (commits) ============

    /**
     * Fetch a task's status tokens and open the commits manager modal.
     * @param {string} taskId - Task ID
     */
    async function openStatusTokens(taskId) {
        try {
            const task = await GoingsOn.api.tasks.get(taskId);
            if (!task) {
                GoingsOn.ui.showToast('Task not found', 'error');
                return;
            }
            renderStatusTokensModal(taskId, task.statusTokens || []);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to load task'), 'error');
        }
    }

    /** Re-fetch the task and re-render the open commits modal. */
    async function reloadStatusTokens(taskId) {
        const task = await GoingsOn.api.tasks.get(taskId);
        renderStatusTokensModal(taskId, task.statusTokens || []);
    }

    /**
     * Add a commit reference to a task (starts Pending / not-primary).
     * @param {Event} e - Submit event
     * @param {string} taskId - Task ID
     */
    async function addStatusToken(e, taskId) {
        e.preventDefault();
        const form = e.target;
        const reference = form.commit_ref.value.trim();
        if (!reference) return;

        try {
            // Only the `commit` kind exists today; the add form is commit-specific.
            await GoingsOn.api.statusTokens.record(taskId, { kind: 'commit', reference, state: 'Pending', isPrimary: false });
            form.commit_ref.value = '';
            await reloadStatusTokens(taskId);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to add commit'), 'error');
        }
    }

    /**
     * Record a token with an explicit (pushed, primary) state — the toggle path.
     * `record` is idempotent in (kind, reference), so this updates in place.
     * @param {string} taskId
     * @param {string} kind
     * @param {string} reference
     * @param {string} pushedStr - "1" for pushed (Complete), else Pending
     * @param {string} primaryStr - "1" for primary
     */
    async function setStatusToken(taskId, kind, reference, pushedStr, primaryStr) {
        try {
            await GoingsOn.api.statusTokens.record(taskId, {
                kind,
                reference,
                state: pushedStr === '1' ? 'Complete' : 'Pending',
                isPrimary: primaryStr === '1',
            });
            await reloadStatusTokens(taskId);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to update commit'), 'error');
        }
    }

    /**
     * Remove a status token from a task.
     * @param {string} taskId
     * @param {string} tokenId
     */
    async function deleteStatusToken(taskId, tokenId) {
        try {
            await GoingsOn.api.statusTokens.delete(tokenId);
            await reloadStatusTokens(taskId);
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to remove commit'), 'error');
        }
    }

    /**
     * Open a form modal to add an annotation note to a task.
     * @param {string} taskId - Task ID to annotate
     */
    function addAnnotation(taskId) {
        GoingsOn.ui.openFormModal({
            title: 'Add Annotation',
            entityType: 'annotation',
            isEdit: false,
            fields: [
                {
                    name: 'note',
                    type: 'textarea',
                    label: 'Note',
                    placeholder: 'Enter annotation note...',
                    required: true,
                    validate: (v) => v && v.length > 2000 ? 'Maximum 2000 characters' : null,
                },
            ],
            onSubmit: async (data) => {
                await GoingsOn.ui.apiCall(GoingsOn.api.annotations.add(taskId, data.note.trim()), {
                    successMessage: 'Annotation added!',
                    errorMessage: 'Failed to add annotation',
                });
            },
        });
    }

    /**
     * Open a modal to assign or change a task's milestone.
     * @param {string} taskId - Task ID to set milestone on
     */
    async function openSetMilestone(taskId) {
        try {
            const task = await GoingsOn.api.tasks.get(taskId);
            if (!task) {
                GoingsOn.ui.showToast('Task not found', 'error');
                return;
            }

            if (!task.projectId) {
                GoingsOn.ui.showToast('Task must be in a project first', 'error');
                return;
            }

            const milestones = await GoingsOn.api.milestones.list(task.projectId);
            if (milestones.length === 0) {
                GoingsOn.ui.showToast('No milestones in this project', 'info');
                return;
            }

            const milestoneOptions = [
                { value: '', label: 'None' },
                ...milestones.map(m => ({
                    value: m.id,
                    label: m.name,
                    selected: m.id === task.milestoneId,
                })),
            ];

            GoingsOn.ui.openFormModal({
                title: 'Set Milestone',
                entityType: 'set-milestone',
                isEdit: false,
                fields: [
                    { name: 'milestone_id', type: 'select', label: 'Milestone', options: milestoneOptions, value: task.milestoneId || '' },
                ],
                onSubmit: async (data) => {
                    const input = {
                        description: task.description,
                        projectId: task.projectId,
                        status: task.status,
                        priority: task.priority,
                        due: task.due,
                        tags: task.tags,
                        recurrence: task.recurrence,
                        contactId: task.contactId || null,
                        milestoneId: data.milestone_id || null,
                    };

                    const reloadFns = [load];
                    const currentProjectId = GoingsOn.getCurrentProjectId();
                    if (currentProjectId) {
                        reloadFns.push(() => GoingsOn.projects.loadDashboard(currentProjectId));
                    }

                    await GoingsOn.ui.apiCall(GoingsOn.api.tasks.update(taskId, input), {
                        successMessage: 'Milestone updated!',
                        errorMessage: 'Failed to set milestone',
                        reload: reloadFns,
                    });
                },
            });
        } catch (err) {
            GoingsOn.ui.showToast(GoingsOn.utils.getErrorMessage(err, 'Failed to load task'), 'error');
        }
    }

    /**
     * Transition a task from Pending to Started status.
     * @param {string} id - Task ID to start
     */
    /**
     * Surgically reflect a single task's status change in the streamed list. If
     * the active status filter no longer matches the new status, the row leaves
     * the view; otherwise it is patched in place. Either way the state subscriber
     * refreshes the scroller — no full-window refetch + scroll-to-top (ultra-fuzz
     * Run #28 S4). Genuine re-sorts (priority/due edits) still reload; a status
     * transition does not move a task within the urgency sort.
     * @param {string} id - Task ID
     * @param {string} newStatus - Capitalized backend status ('Started', etc.)
     */
    function _applyTaskStatusChange(id, newStatus) {
        const filterStatus = GoingsOn.tasksFilter.getFilters().status; // '' = all
        const tasks = GoingsOn.state.tasks || [];
        const stillMatches = !filterStatus || filterStatus.toLowerCase() === newStatus.toLowerCase();
        if (stillMatches) {
            GoingsOn.state.set('tasks', tasks.map(t => t.id === id ? { ...t, status: newStatus } : t));
        } else {
            GoingsOn.state.set('tasks', tasks.filter(t => t.id !== id));
        }
    }

    async function start(id) {
        await GoingsOn.ui.apiCall(GoingsOn.api.tasks.start(id), {
            successMessage: 'Task started!',
            errorMessage: 'Failed to start task',
            onSuccess: () => {
                GoingsOn.cache.invalidate('tasks');
                _applyTaskStatusChange(id, 'Started');
            },
        });
    }

    /**
     * Mark a task as completed. Spawns next instance for recurring tasks.
     * @param {string} id - Task ID to complete
     */
    async function complete(id) {
        GoingsOn.cache.invalidate('tasks');

        // Animate row out before removing from state
        const row = document.querySelector(`.task-row[data-id="${id}"]`);
        if (row) row.classList.add('task-row-removing');

        const cachedTasks = GoingsOn.state.tasks;
        const removedIndex = cachedTasks.findIndex(t => t.id === id);
        const removedTask = removedIndex > -1 ? cachedTasks[removedIndex] : null;

        // Optimistic surgical removal once the row has animated out. The state
        // subscriber refreshes the scroller in place — no full-window refetch
        // (ultra-fuzz Run #28 S4). The completed task leaves the pending view.
        setTimeout(() => {
            GoingsOn.state.set('tasks', GoingsOn.state.tasks.filter(t => t.id !== id));
        }, 250);

        GoingsOn.ui.showUndoToast('Task completed', {
            onConfirm: async () => {
                try {
                    await GoingsOn.api.tasks.complete(id);
                    // A recurring task spawns its next instance on completion, so
                    // refetch to surface it. A plain task is already reflected by the
                    // optimistic removal — no full-window refetch (ultra-fuzz #28 S4).
                    if (removedTask && removedTask.recurrence && removedTask.recurrence !== 'None') {
                        load();
                    }
                } catch (err) {
                    GoingsOn.ui.showToast('Failed to complete task', 'error');
                    load(); // restore truth after a failed commit
                }
            },
            onUndo: () => {
                if (removedTask) {
                    // Restore at the original position so the undo doesn't drop the
                    // row to the list tail (ultra-fuzz Run #28 S3).
                    const restored = GoingsOn.state.tasks.slice();
                    restored.splice(Math.min(removedIndex, restored.length), 0, removedTask);
                    GoingsOn.state.set('tasks', restored);
                }
            },
        });
    }

    /**
     * Delete a task with confirmation and undo support.
     * Optimistically removes from UI; actual deletion happens after undo window.
     * @param {string} id - Task ID to delete
     */
    async function deleteTask(id) {
        // No hard confirm (GO-13): this is an optimistic delete whose API call is
        // deferred until the undo window expires, so the undo toast IS the
        // recovery. A "this cannot be undone" modal here would be both redundant
        // and false. Confirms are reserved for immediate, non-undoable deletes.
        GoingsOn.cache.invalidate('tasks');
        // Hide task from UI immediately. The state subscriber refreshes the
        // scroller in place — no full-window refetch (ultra-fuzz Run #28 S3/S4).
        const cachedTasks = GoingsOn.state.tasks;
        const removedIndex = cachedTasks.findIndex(t => t.id === id);
        const removedTask = removedIndex > -1 ? cachedTasks[removedIndex] : null;
        GoingsOn.state.set('tasks', cachedTasks.filter(t => t.id !== id));

        GoingsOn.ui.showUndoToast('Task deleted', {
            onConfirm: async () => {
                // Actually delete after undo window expires
                try {
                    await GoingsOn.api.tasks.delete(id);
                } catch (err) {
                    GoingsOn.ui.showToast('Failed to delete task', 'error');
                    load();
                }
            },
            onUndo: () => {
                // Restore at the original position (ultra-fuzz Run #28 S3).
                if (removedTask) {
                    const restored = GoingsOn.state.tasks.slice();
                    restored.splice(Math.min(removedIndex, restored.length), 0, removedTask);
                    GoingsOn.state.set('tasks', restored);
                }
            },
        });
    }

    // ============ Populate GoingsOn.tasks Namespace ============

    GoingsOn.tasks = {
        load,
        renderFilteredTasks,
        setViewMode: (...a) => GoingsOn.taskBoard.setViewMode(...a),
        renderBoard: (...a) => GoingsOn.taskBoard.renderBoard(...a),
        openNew,
        openNewForProject,
        create,
        openActions,
        openEdit,
        update,
        openSubtasks,
        openStatusTokens,
        addStatusToken,
        setStatusToken,
        deleteStatusToken,
        renderSubtasksModal,
        closeSubtasksAndRefresh,
        addSubtask,
        toggleSubtask,
        deleteSubtask,
        addAnnotation,
        openSetMilestone,
        openLinkTaskPicker,
        linkTask,
        start,
        complete,
        delete: deleteTask,
        // Delegated to tasksFilter
        populateProjectFilter: (...a) => GoingsOn.tasksFilter.populateProjectFilter(...a),
        populateMilestoneFilter: (...a) => GoingsOn.tasksFilter.populateMilestoneFilter(...a),
        getFilters: (...a) => GoingsOn.tasksFilter.getFilters(...a),
        applyFilters: (...a) => GoingsOn.tasksFilter.applyFilters(...a),
        clearFilters: (...a) => GoingsOn.tasksFilter.clearFilters(...a),
        goToPage: (...a) => GoingsOn.tasksFilter.goToPage(...a),
        toggleSelection: (...a) => GoingsOn.tasksFilter.toggleSelection(...a),
        selectAll: (...a) => GoingsOn.tasksFilter.selectAll(...a),
        getSelected: (...a) => GoingsOn.tasksFilter.getSelected(...a),
        clearSelected: (...a) => GoingsOn.tasksFilter.clearSelected(...a),
        sort: (...a) => GoingsOn.tasksFilter.sort(...a),
        toggleMobileFilters: (...a) => GoingsOn.tasksFilter.toggleMobileFilters(...a),
        mobileSortChange: (...a) => GoingsOn.tasksFilter.mobileSortChange(...a),
        // Helpers
        renderTaskBadges,
        renderTaskRow,
        formatRecurrence,
        getFormFields: getTaskFormFields,
        // Expose managers
        selection: taskSelection,
        pagination: taskPagination,
        // Virtual scroller getter
        getScroller: () => taskScroller,
    };

})();