discoclaw 0.1.0

package/dist/tasks/task-sync-phase-apply.js

@@ -0,0 +1,171 @@
+import { withTaskLifecycleLock } from './task-lifecycle.js';
+import { closeTaskThread, createTaskThread, ensureUnarchived, findExistingThreadForTask, isTaskThreadAlreadyClosed, isThreadArchived, updateTaskStarterMessage, updateTaskThreadName, updateTaskThreadTags, } from './thread-ops.js';
+import { getThreadIdFromTask } from './thread-helpers.js';
+function sleep(ms) {
+    const n = ms ?? 0;
+    if (n <= 0)
+        return Promise.resolve();
+    return new Promise((r) => setTimeout(r, n));
+}
+async function applyPhase1CreateMissingThreads(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        await withTaskLifecycleLock(task.id, async () => {
+            const latestTask = ctx.store.get(task.id) ?? task;
+            if (getThreadIdFromTask(latestTask) ||
+                latestTask.status === 'closed' ||
+                (latestTask.labels ?? []).includes('no-thread')) {
+                return;
+            }
+            try {
+                const existing = await findExistingThreadForTask(ctx.forum, latestTask.id, { archivedLimit: ctx.archivedDedupeLimit });
+                if (existing) {
+                    try {
+                        ctx.taskService.update(latestTask.id, { externalRef: `discord:${existing}` });
+                        ctx.log?.info({ taskId: latestTask.id, threadId: existing }, 'task-sync:phase1 external-ref backfilled');
+                    }
+                    catch (err) {
+                        ctx.log?.warn({ err, taskId: latestTask.id, threadId: existing }, 'task-sync:phase1 external-ref backfill failed');
+                        ctx.counters.warnings++;
+                    }
+                    return;
+                }
+                const threadId = await createTaskThread(ctx.forum, latestTask, ctx.tagMap, ctx.mentionUserId);
+                try {
+                    ctx.taskService.update(latestTask.id, { externalRef: `discord:${threadId}` });
+                }
+                catch (err) {
+                    ctx.log?.warn({ err, taskId: latestTask.id }, 'task-sync:phase1 external-ref update failed');
+                    ctx.counters.warnings++;
+                }
+                ctx.counters.threadsCreated++;
+                ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase1 thread created');
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id }, 'task-sync:phase1 failed');
+                ctx.counters.warnings++;
+            }
+        });
+        await sleep(ctx.throttleMs);
+    }
+}
+async function applyPhase2FixBlockedStatus(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        try {
+            ctx.taskService.update(task.id, { status: 'blocked' });
+            task.status = 'blocked';
+            ctx.counters.statusesUpdated++;
+            ctx.log?.info({ taskId: task.id }, 'task-sync:phase2 status updated to blocked');
+        }
+        catch (err) {
+            ctx.log?.warn({ err, taskId: task.id }, 'task-sync:phase2 failed');
+            ctx.counters.warnings++;
+        }
+        await sleep(ctx.throttleMs);
+    }
+}
+async function applyPhase3SyncActiveThreads(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        await withTaskLifecycleLock(task.id, async () => {
+            const latestTask = ctx.store.get(task.id) ?? task;
+            const threadId = getThreadIdFromTask(latestTask);
+            if (!threadId || latestTask.status === 'closed') {
+                return;
+            }
+            if (await isThreadArchived(ctx.client, threadId)) {
+                return;
+            }
+            try {
+                await ensureUnarchived(ctx.client, threadId);
+            }
+            catch { }
+            try {
+                const changed = await updateTaskThreadName(ctx.client, threadId, latestTask);
+                if (changed) {
+                    ctx.counters.emojisUpdated++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase3 name updated');
+                }
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase3 failed');
+                ctx.counters.warnings++;
+            }
+            try {
+                const starterChanged = await updateTaskStarterMessage(ctx.client, threadId, latestTask, ctx.mentionUserId);
+                if (starterChanged) {
+                    ctx.counters.starterMessagesUpdated++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase3 starter updated');
+                }
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase3 starter update failed');
+                ctx.counters.warnings++;
+            }
+            try {
+                const tagChanged = await updateTaskThreadTags(ctx.client, threadId, latestTask, ctx.tagMap);
+                if (tagChanged) {
+                    ctx.counters.tagsUpdated++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase3 tags updated');
+                }
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase3 tag update failed');
+                ctx.counters.warnings++;
+            }
+        });
+        await sleep(ctx.throttleMs);
+    }
+}
+async function applyPhase4ArchiveClosedThreads(ctx, tasksById, plannedTaskIds) {
+    for (const taskId of plannedTaskIds) {
+        const task = tasksById.get(taskId);
+        if (!task)
+            continue;
+        await withTaskLifecycleLock(task.id, async () => {
+            const latestTask = ctx.store.get(task.id) ?? task;
+            const threadId = getThreadIdFromTask(latestTask);
+            if (!threadId || latestTask.status !== 'closed') {
+                return;
+            }
+            try {
+                if (await isTaskThreadAlreadyClosed(ctx.client, threadId, latestTask, ctx.tagMap)) {
+                    return;
+                }
+                if (ctx.hasInFlightForChannel(threadId)) {
+                    ctx.counters.closesDeferred++;
+                    ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase4 close deferred (in-flight reply active)');
+                    return;
+                }
+                await closeTaskThread(ctx.client, threadId, latestTask, ctx.tagMap, ctx.log);
+                ctx.counters.threadsArchived++;
+                ctx.log?.info({ taskId: latestTask.id, threadId }, 'task-sync:phase4 archived');
+            }
+            catch (err) {
+                ctx.log?.warn({ err, taskId: latestTask.id, threadId }, 'task-sync:phase4 failed');
+                ctx.counters.warnings++;
+            }
+        });
+        await sleep(ctx.throttleMs);
+    }
+}
+const PHASE_EXECUTORS = {
+    phase1: applyPhase1CreateMissingThreads,
+    phase2: applyPhase2FixBlockedStatus,
+    phase3: applyPhase3SyncActiveThreads,
+    phase4: applyPhase4ArchiveClosedThreads,
+};
+export async function applyTaskSyncExecutionPlan(ctx, applyPlan) {
+    for (const phasePlan of applyPlan.phasePlans) {
+        if (phasePlan.taskIds.length === 0)
+            continue;
+        await PHASE_EXECUTORS[phasePlan.phase](ctx, applyPlan.tasksById, phasePlan.taskIds);
+    }
+}

package/dist/tasks/task-sync-pipeline.js

@@ -0,0 +1,2 @@
+export * from './task-sync-apply-plan.js';
+export * from './task-sync-reconcile-plan.js';

package/dist/tasks/task-sync-pipeline.test.js

@@ -0,0 +1,265 @@
+import { describe, expect, it } from 'vitest';
+import { buildTasksByShortIdMap, buildTasksByThreadIdMap, ingestTaskThreadSnapshots, ingestTaskSyncSnapshot, planTaskSyncApplyExecution, planTaskReconcileFromThreadSources, planTaskReconcileFromSnapshots, planTaskReconcileOperations, planTaskApplyPhases, operationTaskIdList, normalizeTaskSyncBuckets, operationTaskIdSet, planTaskSyncOperations, } from './task-sync-pipeline.js';
+function task(overrides) {
+    return {
+        id: overrides.id,
+        title: overrides.title,
+        status: overrides.status,
+        labels: overrides.labels ?? [],
+        external_ref: overrides.external_ref,
+    };
+}
+describe('task-sync pipeline helpers', () => {
+    it('ingest copies list shape without cloning task objects', () => {
+        const originalTask = task({ id: 'ws-001', title: 'A', status: 'open' });
+        const input = [originalTask];
+        const snapshot = ingestTaskSyncSnapshot(input);
+        expect(snapshot).not.toBe(input);
+        expect(snapshot[0]).toBe(originalTask);
+    });
+    it('normalizes tasks into expected phase buckets', () => {
+        const allTasks = [
+            task({ id: 'ws-001', title: 'Missing ref', status: 'open' }),
+            task({ id: 'ws-002', title: 'No thread', status: 'open', labels: ['no-thread'] }),
+            task({ id: 'ws-003', title: 'Blocked label', status: 'open', labels: ['blocked-api'] }),
+            task({ id: 'ws-004', title: 'Has ref', status: 'in_progress', external_ref: 'discord:123' }),
+            task({ id: 'ws-005', title: 'Closed ref', status: 'closed', external_ref: 'discord:124' }),
+        ];
+        const buckets = normalizeTaskSyncBuckets(allTasks);
+        expect(buckets.tasksMissingRef.map((t) => t.id)).toEqual(['ws-001', 'ws-003']);
+        expect(buckets.needsBlockedTasks.map((t) => t.id)).toEqual(['ws-003']);
+        expect(buckets.tasksWithRef.map((t) => t.id)).toEqual(['ws-004']);
+        expect(buckets.closedTasks.map((t) => t.id)).toEqual(['ws-005']);
+    });
+    it('builds deterministic idempotent operation plans and phase id sets', () => {
+        const buckets = {
+            tasksMissingRef: [
+                task({ id: 'ws-001', title: 'A', status: 'open' }),
+                task({ id: 'ws-002', title: 'B', status: 'open' }),
+            ],
+            needsBlockedTasks: [
+                task({ id: 'ws-003', title: 'C', status: 'open', labels: ['blocked-db'] }),
+            ],
+            tasksWithRef: [
+                task({ id: 'ws-004', title: 'D', status: 'in_progress', external_ref: 'discord:11' }),
+            ],
+            closedTasks: [
+                task({ id: 'ws-005', title: 'E', status: 'closed', external_ref: 'discord:12' }),
+            ],
+        };
+        const operations = planTaskSyncOperations(buckets);
+        expect(operations.map((op) => op.key)).toEqual([
+            'task-sync:phase1:ws-001',
+            'task-sync:phase1:ws-002',
+            'task-sync:phase2:ws-003',
+            'task-sync:phase3:ws-004',
+            'task-sync:phase4:ws-005',
+        ]);
+        expect(operationTaskIdSet(operations, 'phase1')).toEqual(new Set(['ws-001', 'ws-002']));
+        expect(operationTaskIdSet(operations, 'phase4')).toEqual(new Set(['ws-005']));
+        expect(operationTaskIdList(operations, 'phase1')).toEqual(['ws-001', 'ws-002']);
+        expect(operationTaskIdList(operations, 'phase3')).toEqual(['ws-004']);
+    });
+    it('operationTaskIdList preserves in-plan order for the selected phase', () => {
+        const operations = [
+            { phase: 'phase2', taskId: 'ws-010', key: 'task-sync:phase2:ws-010' },
+            { phase: 'phase1', taskId: 'ws-001', key: 'task-sync:phase1:ws-001' },
+            { phase: 'phase3', taskId: 'ws-020', key: 'task-sync:phase3:ws-020' },
+            { phase: 'phase1', taskId: 'ws-002', key: 'task-sync:phase1:ws-002' },
+        ];
+        expect(operationTaskIdList(operations, 'phase1')).toEqual(['ws-001', 'ws-002']);
+    });
+    it('builds ordered apply-phase plans from the diff operation list', () => {
+        const operations = [
+            { phase: 'phase3', taskId: 'ws-020', key: 'task-sync:phase3:ws-020' },
+            { phase: 'phase1', taskId: 'ws-001', key: 'task-sync:phase1:ws-001' },
+            { phase: 'phase4', taskId: 'ws-030', key: 'task-sync:phase4:ws-030' },
+            { phase: 'phase1', taskId: 'ws-002', key: 'task-sync:phase1:ws-002' },
+        ];
+        const phasePlans = planTaskApplyPhases(operations);
+        expect(phasePlans).toEqual([
+            { phase: 'phase1', taskIds: ['ws-001', 'ws-002'] },
+            { phase: 'phase2', taskIds: [] },
+            { phase: 'phase3', taskIds: ['ws-020'] },
+            { phase: 'phase4', taskIds: ['ws-030'] },
+        ]);
+    });
+    it('composes stage2-4 apply execution plan from a task snapshot', () => {
+        const allTasks = [
+            task({ id: 'ws-001', title: 'Missing ref', status: 'open' }),
+            task({ id: 'ws-003', title: 'Blocked label', status: 'open', labels: ['blocked-api'] }),
+            task({ id: 'ws-004', title: 'Has ref', status: 'in_progress', external_ref: 'discord:123' }),
+            task({ id: 'ws-005', title: 'Closed ref', status: 'closed', external_ref: 'discord:124' }),
+        ];
+        const plan = planTaskSyncApplyExecution(allTasks);
+        expect(plan.operations.map((op) => op.key)).toEqual([
+            'task-sync:phase1:ws-001',
+            'task-sync:phase1:ws-003',
+            'task-sync:phase2:ws-003',
+            'task-sync:phase3:ws-004',
+            'task-sync:phase4:ws-005',
+        ]);
+        expect(plan.phasePlans).toEqual([
+            { phase: 'phase1', taskIds: ['ws-001', 'ws-003'] },
+            { phase: 'phase2', taskIds: ['ws-003'] },
+            { phase: 'phase3', taskIds: ['ws-004'] },
+            { phase: 'phase4', taskIds: ['ws-005'] },
+        ]);
+        expect(plan.tasksById.get('ws-004')).toBe(allTasks[2]);
+    });
+    it('builds a short-id lookup map for reconciliation', () => {
+        const map = buildTasksByShortIdMap([
+            task({ id: 'ws-001', title: 'A', status: 'open' }),
+            task({ id: 'dev-001', title: 'B', status: 'open' }),
+            task({ id: 'ws-002', title: 'C', status: 'closed' }),
+        ], (id) => id.split('-')[1] ?? id);
+        expect(map.get('001')?.map((t) => t.id)).toEqual(['ws-001', 'dev-001']);
+        expect(map.get('002')?.map((t) => t.id)).toEqual(['ws-002']);
+    });
+    it('builds a thread-id lookup map for reconciliation', () => {
+        const map = buildTasksByThreadIdMap([
+            task({ id: 'ws-001', title: 'A', status: 'closed', external_ref: 'discord:thread-1' }),
+            task({ id: 'ws-002', title: 'B', status: 'open', external_ref: 'discord:thread-2' }),
+            task({ id: 'ws-003', title: 'C', status: 'open' }),
+        ], (t) => {
+            const ref = t.external_ref ?? '';
+            return ref.startsWith('discord:') ? ref.slice('discord:'.length) : null;
+        });
+        expect(map.get('thread-1')?.map((t) => t.id)).toEqual(['ws-001']);
+        expect(map.get('thread-2')?.map((t) => t.id)).toEqual(['ws-002']);
+        expect(map.get('thread-3')).toBeUndefined();
+    });
+    it('normalizes and merges phase5 thread snapshots with active-over-archived precedence', () => {
+        const snapshots = ingestTaskThreadSnapshots([
+            { id: 'thread-1', name: 'Archived One', archived: true },
+            { id: 'shared', name: 'Archived Shared', archived: true },
+        ], [
+            { id: 'shared', name: 'Active Shared', archived: false },
+            { id: 2, name: null, archived: null },
+        ]);
+        expect(snapshots).toEqual([
+            { id: 'thread-1', name: 'Archived One', archived: true },
+            { id: 'shared', name: 'Active Shared', archived: false },
+            { id: '2', name: '', archived: false },
+        ]);
+    });
+    it('plans phase5 reconcile operations from thread snapshots', () => {
+        const tasksByShortId = buildTasksByShortIdMap([
+            task({ id: 'ws-001', title: 'Closed A', status: 'closed', external_ref: 'discord:thread-001' }),
+            task({ id: 'ws-002', title: 'Closed B', status: 'closed' }),
+            task({ id: 'ws-777', title: 'Collision A', status: 'open' }),
+            task({ id: 'dev-777', title: 'Collision B', status: 'open' }),
+        ], (id) => id.split('-')[1] ?? id);
+        const ops = planTaskReconcileOperations({
+            threads: [
+                { id: 'thread-orphan', name: '🟢 [999] Orphan', archived: false },
+                { id: 'thread-collision', name: '🟢 [777] Collision', archived: false },
+                { id: 'thread-mismatch', name: '🟢 [001] Mismatch', archived: false },
+                { id: 'thread-archive', name: '🟢 [002] Closed active', archived: false },
+                { id: 'thread-reconcile', name: '☑️ [002] Closed archived', archived: true },
+            ],
+            tasksByShortId,
+            shortIdFromThreadName: (name) => {
+                const match = name.match(/\[(\d+)\]/);
+                return match ? match[1] : null;
+            },
+            threadIdFromTask: (t) => {
+                const ref = t.external_ref ?? '';
+                return ref.startsWith('discord:') ? ref.slice('discord:'.length) : null;
+            },
+        });
+        expect(ops.map((op) => op.action)).toEqual([
+            'orphan',
+            'collision',
+            'skip_external_ref_mismatch',
+            'archive_active_closed',
+            'reconcile_archived_closed',
+        ]);
+    });
+    it('plans phase5 reconcile operations directly from task and thread snapshots', () => {
+        const ops = planTaskReconcileFromSnapshots({
+            tasks: [
+                task({ id: 'ws-001', title: 'Closed A', status: 'closed', external_ref: 'discord:thread-001' }),
+                task({ id: 'ws-002', title: 'Closed B', status: 'closed' }),
+                task({ id: 'ws-777', title: 'Collision A', status: 'open' }),
+                task({ id: 'dev-777', title: 'Collision B', status: 'open' }),
+            ],
+            threads: [
+                { id: 'thread-orphan', name: '🟢 [999] Orphan', archived: false },
+                { id: 'thread-collision', name: '🟢 [777] Collision', archived: false },
+                { id: 'thread-mismatch', name: '🟢 [001] Mismatch', archived: false },
+                { id: 'thread-archive', name: '🟢 [002] Closed active', archived: false },
+                { id: 'thread-reconcile', name: '☑️ [002] Closed archived', archived: true },
+            ],
+            shortIdOfTaskId: (id) => id.split('-')[1] ?? id,
+            shortIdFromThreadName: (name) => {
+                const match = name.match(/\[(\d+)\]/);
+                return match ? match[1] : null;
+            },
+            threadIdFromTask: (t) => {
+                const ref = t.external_ref ?? '';
+                return ref.startsWith('discord:') ? ref.slice('discord:'.length) : null;
+            },
+        });
+        expect(ops.map((op) => op.action)).toEqual([
+            'orphan',
+            'collision',
+            'skip_external_ref_mismatch',
+            'archive_active_closed',
+            'reconcile_archived_closed',
+        ]);
+    });
+    it('prefers thread-id mapping before thread-name parsing in reconcile planning', () => {
+        const ops = planTaskReconcileFromSnapshots({
+            tasks: [
+                task({ id: 'ws-010', title: 'Closed mapped', status: 'closed', external_ref: 'discord:thread-linked' }),
+            ],
+            threads: [
+                { id: 'thread-linked', name: 'General thread without token', archived: false },
+            ],
+            shortIdOfTaskId: (id) => id.split('-')[1] ?? id,
+            shortIdFromThreadName: () => null,
+            threadIdFromTask: (t) => {
+                const ref = t.external_ref ?? '';
+                return ref.startsWith('discord:') ? ref.slice('discord:'.length) : null;
+            },
+        });
+        expect(ops.map((op) => op.action)).toEqual(['archive_active_closed']);
+        expect(ops[0]?.task?.id).toBe('ws-010');
+    });
+    it('plans phase5 reconcile operations directly from archived and active thread sources', () => {
+        const ops = planTaskReconcileFromThreadSources({
+            tasks: [
+                task({ id: 'ws-001', title: 'Closed A', status: 'closed', external_ref: 'discord:thread-001' }),
+                task({ id: 'ws-002', title: 'Closed B', status: 'closed' }),
+                task({ id: 'ws-777', title: 'Collision A', status: 'open' }),
+                task({ id: 'dev-777', title: 'Collision B', status: 'open' }),
+            ],
+            archivedThreads: [
+                { id: 'thread-reconcile', name: '☑️ [002] Closed archived', archived: true },
+            ],
+            activeThreads: [
+                { id: 'thread-orphan', name: '🟢 [999] Orphan', archived: false },
+                { id: 'thread-collision', name: '🟢 [777] Collision', archived: false },
+                { id: 'thread-mismatch', name: '🟢 [001] Mismatch', archived: false },
+                { id: 'thread-archive', name: '🟢 [002] Closed active', archived: false },
+            ],
+            shortIdOfTaskId: (id) => id.split('-')[1] ?? id,
+            shortIdFromThreadName: (name) => {
+                const match = name.match(/\[(\d+)\]/);
+                return match ? match[1] : null;
+            },
+            threadIdFromTask: (t) => {
+                const ref = t.external_ref ?? '';
+                return ref.startsWith('discord:') ? ref.slice('discord:'.length) : null;
+            },
+        });
+        expect(ops.map((op) => op.action)).toEqual([
+            'reconcile_archived_closed',
+            'orphan',
+            'collision',
+            'skip_external_ref_mismatch',
+            'archive_active_closed',
+        ]);
+    });
+});

package/dist/tasks/task-sync-reconcile-plan.js

@@ -0,0 +1,182 @@
+export function buildTasksByShortIdMap(allTasks, shortIdOf) {
+    const tasksByShortId = new Map();
+    for (const task of allTasks) {
+        const shortId = shortIdOf(task.id);
+        const existing = tasksByShortId.get(shortId);
+        if (existing)
+            existing.push(task);
+        else
+            tasksByShortId.set(shortId, [task]);
+    }
+    return tasksByShortId;
+}
+export function buildTasksByThreadIdMap(allTasks, threadIdFromTask) {
+    const tasksByThreadId = new Map();
+    for (const task of allTasks) {
+        const threadId = threadIdFromTask(task);
+        if (!threadId)
+            continue;
+        const existing = tasksByThreadId.get(threadId);
+        if (existing)
+            existing.push(task);
+        else
+            tasksByThreadId.set(threadId, [task]);
+    }
+    return tasksByThreadId;
+}
+/**
+ * Stage: ingest (phase 5)
+ * Merge archived+active thread sources into a normalized snapshot list.
+ * When a thread ID appears in both sources, the active source wins.
+ */
+export function ingestTaskThreadSnapshots(archivedThreads, activeThreads) {
+    const byThreadId = new Map();
+    const push = (thread) => {
+        const id = String(thread.id);
+        byThreadId.set(id, {
+            id,
+            name: String(thread.name ?? ''),
+            archived: Boolean(thread.archived),
+        });
+    };
+    for (const thread of archivedThreads)
+        push(thread);
+    for (const thread of activeThreads)
+        push(thread);
+    return [...byThreadId.values()];
+}
+/**
+ * Stage: diff (phase 5)
+ * Plan reconciliation operations for forum threads vs local task snapshot.
+ */
+export function planTaskReconcileOperations(opts) {
+    const operations = [];
+    const tasksByThreadId = opts.tasksByThreadId ?? new Map();
+    for (const thread of opts.threads) {
+        const linkedTasks = tasksByThreadId.get(thread.id) ?? [];
+        if (linkedTasks.length > 1) {
+            operations.push({
+                action: 'collision',
+                key: `task-sync:phase5:collision:${thread.id}`,
+                thread,
+                shortId: opts.shortIdFromThreadName(thread.name) ?? '',
+                collisionCount: linkedTasks.length,
+            });
+            continue;
+        }
+        if (linkedTasks.length === 1) {
+            const task = linkedTasks[0];
+            const existingThreadId = opts.threadIdFromTask(task);
+            if (task.status === 'closed' && !thread.archived) {
+                operations.push({
+                    action: 'archive_active_closed',
+                    key: `task-sync:phase5:archive:${thread.id}`,
+                    thread,
+                    shortId: opts.shortIdFromThreadName(thread.name) ?? '',
+                    task,
+                    existingThreadId: existingThreadId ?? undefined,
+                });
+                continue;
+            }
+            if (task.status === 'closed' && thread.archived) {
+                operations.push({
+                    action: 'reconcile_archived_closed',
+                    key: `task-sync:phase5:reconcile:${thread.id}`,
+                    thread,
+                    shortId: opts.shortIdFromThreadName(thread.name) ?? '',
+                    task,
+                    existingThreadId: existingThreadId ?? undefined,
+                });
+            }
+            continue;
+        }
+        // Fallback for legacy threads missing task external_ref mapping.
+        const shortId = opts.shortIdFromThreadName(thread.name);
+        if (!shortId)
+            continue;
+        const tasks = opts.tasksByShortId.get(shortId);
+        if (!tasks || tasks.length === 0) {
+            operations.push({
+                action: 'orphan',
+                key: `task-sync:phase5:orphan:${thread.id}`,
+                thread,
+                shortId,
+            });
+            continue;
+        }
+        if (tasks.length > 1) {
+            operations.push({
+                action: 'collision',
+                key: `task-sync:phase5:collision:${thread.id}`,
+                thread,
+                shortId,
+                collisionCount: tasks.length,
+            });
+            continue;
+        }
+        const task = tasks[0];
+        const existingThreadId = opts.threadIdFromTask(task);
+        if (existingThreadId && existingThreadId !== thread.id) {
+            operations.push({
+                action: 'skip_external_ref_mismatch',
+                key: `task-sync:phase5:skip-mismatch:${thread.id}`,
+                thread,
+                shortId,
+                task,
+                existingThreadId,
+            });
+            continue;
+        }
+        if (task.status === 'closed' && !thread.archived) {
+            operations.push({
+                action: 'archive_active_closed',
+                key: `task-sync:phase5:archive:${thread.id}`,
+                thread,
+                shortId,
+                task,
+                existingThreadId: existingThreadId ?? undefined,
+            });
+            continue;
+        }
+        if (task.status === 'closed' && thread.archived) {
+            operations.push({
+                action: 'reconcile_archived_closed',
+                key: `task-sync:phase5:reconcile:${thread.id}`,
+                thread,
+                shortId,
+                task,
+                existingThreadId: existingThreadId ?? undefined,
+            });
+        }
+    }
+    return operations;
+}
+/**
+ * Stage: diff (phase 5)
+ * Build phase-5 reconcile operations directly from task+thread snapshots.
+ */
+export function planTaskReconcileFromSnapshots(opts) {
+    const tasksByShortId = buildTasksByShortIdMap(opts.tasks, opts.shortIdOfTaskId);
+    const tasksByThreadId = buildTasksByThreadIdMap(opts.tasks, opts.threadIdFromTask);
+    return planTaskReconcileOperations({
+        threads: opts.threads,
+        tasksByShortId,
+        tasksByThreadId,
+        shortIdFromThreadName: opts.shortIdFromThreadName,
+        threadIdFromTask: opts.threadIdFromTask,
+    });
+}
+/**
+ * Stage: diff (phase 5)
+ * Compose thread-source ingest + reconcile diff planning.
+ */
+export function planTaskReconcileFromThreadSources(opts) {
+    const threads = ingestTaskThreadSnapshots(opts.archivedThreads, opts.activeThreads);
+    return planTaskReconcileFromSnapshots({
+        tasks: opts.tasks,
+        threads,
+        shortIdOfTaskId: opts.shortIdOfTaskId,
+        shortIdFromThreadName: opts.shortIdFromThreadName,
+        threadIdFromTask: opts.threadIdFromTask,
+    });
+}