@amsterdamdatalabs/enact-factory 0.1.1

package/dist/workItems/azureDevOpsSync.js

@@ -0,0 +1,748 @@
+// ============================================
+// EnactFactory - Azure DevOps Heartbeat Sync Orchestrator
+// Pull-down from AzDO, push-up local changes, stale detection, SSE events.
+// ============================================
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { AzdoApiError, createAzdoClient } from '../azureDevOps/client.js';
+import { DEFAULT_FIELD_NAMES, azdoToWorkItemRecord, azdoToWorkItemPayload, payloadToAzdoPatches, azdoToArea } from '../azureDevOps/mapper.js';
+import { loadConfig } from '../core/config.js';
+import { provisionHierarchy } from '../azureDevOps/hierarchy.js';
+import { DEFAULT_AZDO_TERMINAL_STATES, localStatusToAzdoState, resolveTerminalAzdoStates, } from '../azureDevOps/stateMapping.js';
+import { resolveProjectConfigs } from '../core/runtimeConfig.js';
+import { EventEmitter } from 'node:events';
+import { drainPushQueue } from '../factory/workitemQueues.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Drains the workitem-push-queue at `root` by calling pushLocalChange for
+ * each pending entry. Entries that succeed are marked drained. Entries that
+ * exhaust all attempts remain in the queue and are reported in result.errors.
+ *
+ * Exponential backoff: delay = backoffMs * 2^attempt (capped at 30 000 ms).
+ */
+export async function drainWorkItemPushQueue(root, context, options = {}) {
+    const maxAttempts = options.maxAttemptsPerEntry ?? 3;
+    const backoffMs = options.backoffMs ?? 1000;
+    const errors = [];
+    // Build an inline pushLocalChange equivalent using the provided context.
+    const { client, store, config, events } = context;
+    const fieldNames = { ...DEFAULT_FIELD_NAMES, ...config.fieldNames };
+    async function pushEntry(workItemId) {
+        const local = await store.getWorkItem(workItemId);
+        if (!local) {
+            console.warn(`[AzdoSync] drainPushQueue: item ${workItemId} not found in local store — skipping`);
+            return;
+        }
+        const numericId = parseInt(workItemId, 10);
+        if (isNaN(numericId)) {
+            console.warn(`[AzdoSync] drainPushQueue: ${workItemId} is not a numeric AzDO ID — skipping`);
+            return;
+        }
+        // Source the patch from local intent (stored payload + local title), not a
+        // fresh AzDO fetch — otherwise we re-derive from AzDO's current state and
+        // clobber the local edit we're draining.
+        const patches = await buildLocalPushPatches(store, fieldNames, workItemId, local, context.config);
+        try {
+            await withExponentialBackoff(() => client.updateWorkItem(numericId, patches), 3, 1000, 30000);
+        }
+        catch (err) {
+            if (err instanceof AzdoApiError && err.status !== 429 && err.status !== 503) {
+                console.error(`[AzdoSync] drainPushQueue push failed for ${workItemId}:`, err instanceof Error ? err.message : String(err));
+                events.emit('azdo.push.failed', { workItemId, status: err.status, message: err.message });
+                // Non-retriable — surface as resolved so we don't re-queue indefinitely.
+                return;
+            }
+            throw err;
+        }
+    }
+    const queueResult = await drainPushQueue(root, async (entry) => {
+        let lastErr;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                await pushEntry(entry.workItemId);
+                return; // success → drainPushQueue marks this entry drained
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt < maxAttempts - 1) {
+                    await new Promise((r) => setTimeout(r, backoffMs * Math.pow(2, attempt)));
+                }
+            }
+        }
+        // All attempts exhausted — record for forensics and rethrow so
+        // drainPushQueue does NOT mark this entry drained.
+        errors.push({
+            entryId: entry.id,
+            workItemId: entry.workItemId,
+            attempts: maxAttempts,
+            lastError: lastErr instanceof Error ? lastErr.message : String(lastErr),
+        });
+        throw lastErr;
+    });
+    return { drained: queueResult.drained, errors };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const BATCH_SIZE = 200;
+// Default Scrum terminal states — open = not in these. PBI/Bug (the Scrum
+// process template) end their lifecycle at exactly 'Done' or 'Removed'.
+// Overridable per-workspace via AzdoSyncConfig.terminalStates.
+export const AZDO_TERMINAL_STATES = DEFAULT_AZDO_TERMINAL_STATES;
+function buildWiql(project, areaFilter, changedSince, terminalStates = AZDO_TERMINAL_STATES) {
+    // Board scope: only executable work items (Product Backlog Item, Bug).
+    // Epic/Feature are planning containers — they live in AzDO for hierarchy
+    // and breadcrumbs but are out of scope for the Factory board.
+    let wiql = `SELECT [System.Id] FROM WorkItems` +
+        ` WHERE [System.TeamProject] = '${project}'` +
+        ` AND [System.WorkItemType] IN ('Product Backlog Item', 'Bug')`;
+    // Open items only — exclude terminal states so the fetch stays bounded at
+    // scale and the board mirrors only live work. Applied in both modes.
+    const terminalList = terminalStates.map((s) => `'${s}'`).join(', ');
+    wiql += ` AND [System.State] NOT IN (${terminalList})`;
+    if (areaFilter) {
+        wiql += ` AND [System.AreaPath] UNDER '${areaFilter}'`;
+    }
+    if (changedSince) {
+        // Incremental mode: only items touched since the watermark, ordered by
+        // ChangedDate ASC so the watermark can advance monotonically.
+        //
+        // AzDO WIQL requires DATE precision for [System.ChangedDate] comparisons —
+        // supplying a full ISO timestamp (e.g. "2026-06-16T00:24:05.860Z") causes
+        // HTTP 400: "You cannot supply a time with the date when running a query
+        // using date precision". Truncate to YYYY-MM-DD.
+        //
+        // Date-precision re-scans from midnight of the watermark's date, so items
+        // changed earlier the same day are re-fetched on the next tick. That is
+        // safe: mergeRecord is idempotent (no-op when local is already current) and
+        // the stored watermark stays full-ISO so the monotonic advance is preserved.
+        const azdoDate = new Date(changedSince).toISOString().slice(0, 10);
+        wiql += ` AND [System.ChangedDate] >= '${azdoDate}'`;
+        wiql += ' ORDER BY [System.ChangedDate] ASC';
+    }
+    else {
+        // Full mode: stable id ordering over the complete set.
+        wiql += ' ORDER BY [System.Id]';
+    }
+    return wiql;
+}
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function extractParentId(workItem) {
+    const relation = workItem.relations?.find((entry) => entry.rel === 'System.LinkTypes.Hierarchy-Reverse');
+    if (!relation?.url)
+        return null;
+    const match = relation.url.match(/workItems\/(\d+)/i);
+    return match ? match[1] : null;
+}
+async function withExponentialBackoff(fn, maxAttempts, baseDelayMs, capMs) {
+    let delay = baseDelayMs;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (attempt === maxAttempts)
+                throw err;
+            // Only retry on 429 / 503
+            if (err instanceof AzdoApiError && err.status !== 429 && err.status !== 503) {
+                throw err;
+            }
+            await sleep(Math.min(delay, capMs));
+            delay *= 2;
+        }
+    }
+    // Unreachable — satisfies TS
+    throw new Error('withExponentialBackoff: exhausted attempts');
+}
+function mergeRecord(local, azdoRecord, azdoChangedDate, payloadFields) {
+    // Conflict rule: if local was updated after AzDO's changedDate, keep local for AzDO-owned fields
+    const localUpdated = new Date(local.updatedAt).getTime();
+    const azdoChanged = new Date(azdoChangedDate).getTime();
+    if (localUpdated > azdoChanged) {
+        // Local is newer — keep it as-is
+        return { merged: {}, changed: false };
+    }
+    // AzDO is newer — accept AzDO-owned fields
+    const patch = {};
+    let changed = false;
+    // Flat fields that azdoToWorkItemRecord produces.
+    const fields = [
+        'title', 'description', 'status', 'priority',
+    ];
+    for (const field of fields) {
+        const azdoVal = azdoRecord[field];
+        if (azdoVal !== undefined && local[field] !== azdoVal) {
+            patch[field] = azdoVal;
+            changed = true;
+        }
+    }
+    // Payload-derived fields (area, kind, assignee) — these ARE DB columns but are
+    // not produced by azdoToWorkItemRecord. Merge them here when AzDO is canonical.
+    if (payloadFields) {
+        // area: merge only when AzDO has a real sub-area (non-null). A null area
+        // means the item lives at the project root — don't clobber an existing local area.
+        if (payloadFields.area !== null && payloadFields.area !== undefined &&
+            local.area !== payloadFields.area) {
+            patch.area = payloadFields.area;
+            changed = true;
+        }
+        // kind: always present on synced PBIs/Bugs; update if it changed upstream.
+        if (payloadFields.kind !== undefined && local.kind !== payloadFields.kind) {
+            patch.kind = payloadFields.kind;
+            changed = true;
+        }
+        // assignee: null means unassigned — propagate that too (clear the local assignee).
+        const azdoAssignee = payloadFields.assignee ?? null;
+        const localAssignee = local.assignee ?? null;
+        if (localAssignee !== azdoAssignee) {
+            // Use explicit `null` (not `undefined`) so updateWorkItem writes NULL and
+            // actually clears the column. `undefined` would be treated as "leave unchanged"
+            // by the Postgres store (and dropped by the `{...existing, ...patch}` spread),
+            // so the local assignee would never clear when AzDO unassigns the item.
+            patch['assignee'] = azdoAssignee;
+            changed = true;
+        }
+    }
+    if (changed) {
+        // Stamp the REAL AzDO ChangedDate, not NOW() — otherwise every merged row
+        // looks "just now" on the dashboard even though AzDO changed it minutes ago.
+        patch.updatedAt = azdoChangedDate;
+    }
+    return { merged: patch, changed };
+}
+// Canonical assignee re-applied on every drained push (mirrors azdoBridge.ts).
+// Replicated inline — importing from azdoBridge would create an import cycle.
+const AZDO_DEFAULT_ASSIGNEE = 'Tarun Rana <tarun.rana@amsterdamdatalabs.com>';
+/**
+ * Build AzDO patches to push a LOCAL change up, sourced from local intent
+ * rather than a fresh AzDO fetch. Re-fetching AzDO and re-deriving patches
+ * from its current state clobbers the very edit we're trying to push.
+ *
+ * Strategy: take the last-known stored payload (which carries the
+ * AzDO-canonical area/kind from the previous pull), overlay the local record's
+ * authoritative title, then OVERRIDE System.State with the value derived from
+ * `local.status`. The stored payload's layeredState is the PRE-edit state, so
+ * for a queued status change (e.g. a failed soft-delete cancel) trusting it
+ * would push a stale non-Removed state and the delete would not stick — the
+ * row resurrects on the next full pull. We therefore de-dup any System.State
+ * patch the payload produced and append exactly one built from local.status.
+ * AssignedTo is (re)applied to honor the same canonical-assignee guarantee as
+ * the direct bridge pushes.
+ */
+async function buildLocalPushPatches(store, fieldNames, workItemId, local, syncConfig) {
+    // Base patches: payload-derived (title/area/booleans) or title-only fallback.
+    let base;
+    const storedJson = await store.getPayloadJson(workItemId);
+    let parsed = null;
+    if (storedJson) {
+        try {
+            parsed = JSON.parse(storedJson);
+        }
+        catch {
+            // Corrupt stored payload — fall through to the title-only fallback.
+        }
+    }
+    if (parsed) {
+        const overlaid = { ...parsed, title: local.title };
+        base = payloadToAzdoPatches(overlaid, fieldNames);
+    }
+    else {
+        base = [{ op: 'replace', path: `/fields/${fieldNames.title}`, value: local.title }];
+    }
+    // Drop any System.State patch the payload emitted — its value is the stale
+    // pre-edit state. The authoritative state comes from local.status below.
+    const statePath = `/fields/${fieldNames.state}`;
+    base = base.filter((p) => p.path !== statePath);
+    // Append the single authoritative System.State + the canonical AssignedTo.
+    base.push({ op: 'add', path: statePath, value: localStatusToAzdoState(local.status, syncConfig) });
+    base.push({ op: 'add', path: `/fields/${fieldNames.assignedTo}`, value: AZDO_DEFAULT_ASSIGNEE });
+    return base;
+}
+// ---------------------------------------------------------------------------
+// fetchToken factories (exported for service.ts bootstrap)
+// ---------------------------------------------------------------------------
+export function makePATFetcher(patEnvVar) {
+    return async () => {
+        const pat = process.env[patEnvVar];
+        if (!pat) {
+            throw new Error(`AzDO PAT environment variable "${patEnvVar}" is not set`);
+        }
+        return `Basic ${Buffer.from(':' + pat).toString('base64')}`;
+    };
+}
+export function makeAzCliTokenFetcher(tenant) {
+    return async () => {
+        const args = [
+            'account', 'get-access-token',
+            '--resource', '499b84ac-1321-427f-aa17-267ca6975798',
+        ];
+        if (tenant) {
+            args.push('--tenant', tenant);
+        }
+        args.push('--query', 'accessToken', '-o', 'tsv');
+        const { stdout } = await execFileAsync('az', args);
+        return stdout.trim();
+    };
+}
+// ---------------------------------------------------------------------------
+// AzdoSyncContext builder — shared by the service and MCP tool
+// ---------------------------------------------------------------------------
+/**
+ * Build an AzdoSyncContext from workspace config.
+ * Organization / project come from config.toml; PAT remains a secret env var.
+ */
+export function buildAzdoSyncContextFromConfig(store) {
+    const loadedConfig = loadConfig();
+    const azdoCfg = loadedConfig.azureDevOps;
+    if (!azdoCfg?.enabled) {
+        throw new Error('factory_workitem_drain_push_queue: Azure DevOps sync is disabled in config.toml');
+    }
+    const fetchToken = azdoCfg.authStrategy === 'pat'
+        ? makePATFetcher(azdoCfg.patEnvVar ?? 'AZDO_PAT')
+        : makeAzCliTokenFetcher('amsterdamdatalabs.com');
+    const client = createAzdoClient({ organization: azdoCfg.organization, project: azdoCfg.project, fetchToken });
+    const events = new EventEmitter();
+    const syncConfig = {
+        enabled: true,
+        organization: azdoCfg.organization,
+        project: azdoCfg.project,
+        intervalMs: azdoCfg.intervalMs,
+        authStrategy: azdoCfg.authStrategy,
+        patEnvVar: azdoCfg.patEnvVar,
+        fieldNames: azdoCfg.fieldNames,
+        areaFilter: azdoCfg.areaFilter,
+        azdoStateToStatus: azdoCfg.azdoStateToStatus,
+        statusToAzdoState: azdoCfg.statusToAzdoState,
+        terminalStates: azdoCfg.terminalStates,
+    };
+    return { client, store, config: syncConfig, events, fetchToken };
+}
+export function createAzdoSyncService(deps, options) {
+    const { client, store, config, events } = deps;
+    const drainAfterSync = options?.drainPushQueueAfterSync !== false;
+    const root = options?.root;
+    const fieldNames = { ...DEFAULT_FIELD_NAMES, ...config.fieldNames };
+    // Incremental-sync watermark key. Scoped to org/project/areaFilter so a
+    // workspace that re-points at a different project/area starts fresh instead
+    // of inheriting a stale ChangedDate cursor.
+    const watermarkKey = `azdo:watermark:${config.organization}/${config.project}:${config.areaFilter ?? ''}`;
+    // Single source of truth for "what counts as terminal". Drives both the
+    // open-only WIQL filter and the reconcile's closed-item detection so they
+    // can't drift. Defaults to AZDO_TERMINAL_STATES when config omits it.
+    const terminalStates = resolveTerminalAzdoStates(config);
+    const terminalStateSet = new Set(terminalStates);
+    // State
+    let intervalHandle = null;
+    let inFlightSync = null;
+    let started = false;
+    let lastSuccessAt = null;
+    let lastErrorAt = null;
+    let lastError;
+    let wasStale = false;
+    // ---------------------------------------------------------------------------
+    // Stale detection
+    // ---------------------------------------------------------------------------
+    function checkStale() {
+        const now = Date.now();
+        const threshold = config.intervalMs * 3;
+        const isStale = lastSuccessAt === null || (now - lastSuccessAt) > threshold;
+        if (isStale && !wasStale) {
+            wasStale = true;
+            events.emit('azdo.sync.stale', { at: now });
+        }
+        else if (!isStale && wasStale) {
+            wasStale = false;
+            events.emit('azdo.sync.healthy', { at: now });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // syncOnce — pull-down
+    // ---------------------------------------------------------------------------
+    async function syncOnce(opts) {
+        const t0 = Date.now();
+        const result = { pulled: 0, pushed: 0, conflicts: 0, errors: [], durationMs: 0 };
+        const mode = opts?.mode ?? 'incremental';
+        try {
+            // Incremental mode reads the stored watermark and only pulls items whose
+            // System.ChangedDate is at or after it. The very first incremental run
+            // (no watermark yet) falls through to a full scan so we don't miss the
+            // existing backlog. Full mode always scans the complete id set.
+            const currentWatermark = await store.getSyncMeta(watermarkKey);
+            const effectiveMode = mode === 'incremental' && !currentWatermark ? 'full' : mode;
+            const changedSince = effectiveMode === 'incremental' ? currentWatermark ?? undefined : undefined;
+            const wiql = buildWiql(config.project, config.areaFilter, changedSince, terminalStates);
+            const ids = await client.queryByWiql(wiql);
+            // Batch IDs in groups of BATCH_SIZE
+            const batches = [];
+            for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+                batches.push(ids.slice(i, i + BATCH_SIZE));
+            }
+            // Track every AzDO id we see this heartbeat so we can prune local
+            // rows whose upstream item has been deleted in AzDO. Prune only runs in
+            // full mode (incremental never sees the complete id set).
+            const azdoIdsSeen = new Set();
+            // Highest System.ChangedDate observed across processed items this run.
+            // After a successful run we advance the watermark to (max − 60s) so a
+            // small clock-skew window is re-scanned next time; re-processing is
+            // idempotent because create/merge key on the AzDO id PK.
+            let maxChangedMs = 0;
+            // ALL open executable items (PBI/Bug) this run, each carrying its CURRENT
+            // upstream parent id. Provisioning self-heals wrong parentage, so it needs
+            // every executable item (not just empty-parent orphans) to detect and fix
+            // mis-parented ones. Collected in full mode only; provisioned after the
+            // hydration loop + reconcile.
+            const hierItems = [];
+            for (const batch of batches) {
+                const azdoItems = await client.getWorkItems(batch);
+                const parentIds = Array.from(new Set(azdoItems
+                    .map((item) => extractParentId(item))
+                    .filter((id) => Boolean(id))));
+                const parentItems = parentIds.length > 0
+                    ? await client.getWorkItems(parentIds.map((id) => Number(id)))
+                    : [];
+                const parentMap = new Map(parentItems.map((item) => [String(item.id), item]));
+                const grandparentIds = Array.from(new Set(parentItems
+                    .map((item) => extractParentId(item))
+                    .filter((id) => Boolean(id))));
+                const grandparentItems = grandparentIds.length > 0
+                    ? await client.getWorkItems(grandparentIds.map((id) => Number(id)))
+                    : [];
+                const grandparentMap = new Map(grandparentItems.map((item) => [String(item.id), item]));
+                for (const azdo of azdoItems) {
+                    const itemId = String(azdo.id);
+                    azdoIdsSeen.add(itemId);
+                    try {
+                        const azdoRecord = azdoToWorkItemRecord(azdo, config);
+                        const azdoChangedDate = String(azdo.fields['System.ChangedDate'] ?? new Date().toISOString());
+                        const changedMs = new Date(azdoChangedDate).getTime();
+                        if (Number.isFinite(changedMs) && changedMs > maxChangedMs) {
+                            maxChangedMs = changedMs;
+                        }
+                        const payload = azdoToWorkItemPayload(azdo, fieldNames, config);
+                        const parentId = extractParentId(azdo);
+                        // Collect EVERY open executable item (Backlog item / Bug) for the
+                        // hierarchy self-heal (full mode only), carrying its CURRENT parent
+                        // id (null if none). Provisioning needs all of them — not just
+                        // empty-parent orphans — to detect and re-parent mis-parented items.
+                        // Epics/Features are never returned by the WIQL, but we still guard
+                        // on kind. kind/area come from the payload/mapper (the record mapper
+                        // doesn't emit them); area is the real value or omitted (no fabrication).
+                        if (effectiveMode === 'full' &&
+                            (payload.kind === 'Backlog item' || payload.kind === 'Bug')) {
+                            const itemArea = azdoToArea(azdo);
+                            hierItems.push({
+                                id: itemId,
+                                kind: payload.kind,
+                                ...(itemArea !== null ? { area: itemArea } : {}),
+                                currentParentId: parentId,
+                            });
+                        }
+                        const parent = parentId ? parentMap.get(parentId) : null;
+                        const grandparentId = parent ? extractParentId(parent) : null;
+                        const grandparent = grandparentId ? grandparentMap.get(grandparentId) : null;
+                        payload.parentId = parentId;
+                        if (payload.azdoFields) {
+                            payload.azdoFields.parentId = parentId;
+                            payload.azdoFields.parentTitle = parent ? String(parent.fields[fieldNames.title] ?? '') || null : null;
+                            payload.azdoFields.parentWorkItemType = parent ? String(parent.fields[fieldNames.workItemType] ?? '') || null : null;
+                            payload.azdoFields.parentStartDate = parent ? String(parent.fields[fieldNames.startDate] ?? '') || null : null;
+                            payload.azdoFields.parentTargetDate = parent ? String(parent.fields[fieldNames.targetDate] ?? '') || null : null;
+                            payload.azdoFields.grandparentId = grandparentId;
+                            payload.azdoFields.grandparentTitle = grandparent ? String(grandparent.fields[fieldNames.title] ?? '') || null : null;
+                            payload.azdoFields.grandparentWorkItemType = grandparent ? String(grandparent.fields[fieldNames.workItemType] ?? '') || null : null;
+                            payload.azdoFields.grandparentStartDate = grandparent ? String(grandparent.fields[fieldNames.startDate] ?? '') || null : null;
+                            payload.azdoFields.grandparentTargetDate = grandparent ? String(grandparent.fields[fieldNames.targetDate] ?? '') || null : null;
+                        }
+                        const payloadJson = JSON.stringify(payload);
+                        const local = await store.getWorkItem(itemId);
+                        if (!local) {
+                            // Insert with the AzDO numeric id as the local PK; tag as 'azdo'
+                            // so future heartbeats and pruning can identify mirrored rows.
+                            //
+                            // Forward the REAL AzDO values for every content field the store
+                            // now persists. Phase 1 removed the store's fabricated defaults,
+                            // so anything we omit lands as NULL. createdAt/updatedAt come from
+                            // the AzDO record (real System.CreatedDate / System.ChangedDate) —
+                            // omitting them used to make the store fall back to NOW(), which is
+                            // exactly the "just now" dashboard bug.
+                            //
+                            // kind/area/review/resolution/assignee are not on azdoRecord (the
+                            // record mapper only covers the flat columns) — derive them from
+                            // the payload/mapper helpers. `area` is taken from azdoToArea so a
+                            // genuinely root-only path stays null rather than being fabricated
+                            // as 'Enact/Factory'.
+                            const area = azdoToArea(azdo);
+                            await store.createWorkItem({
+                                id: itemId,
+                                projectId: azdoRecord.projectId ?? config.project,
+                                title: azdoRecord.title ?? '',
+                                description: azdoRecord.description,
+                                status: azdoRecord.status,
+                                priority: azdoRecord.priority ?? undefined,
+                                source: 'azdo',
+                                kind: payload.kind,
+                                ...(area !== null ? { area } : {}),
+                                reviewState: payload.layeredState.review,
+                                resolution: payload.layeredState.resolution,
+                                ...(payload.azdoFields?.assignedTo ? { assignee: payload.azdoFields.assignedTo } : {}),
+                                createdAt: azdoRecord.createdAt,
+                                updatedAt: azdoChangedDate,
+                                ...(azdoRecord.closedAt !== undefined ? { closedAt: azdoRecord.closedAt } : {}),
+                            });
+                            await store.setPayloadJson(itemId, payloadJson);
+                            result.pulled++;
+                            events.emit('workitem.updated', { id: itemId, action: 'created' });
+                        }
+                        else {
+                            const { merged, changed } = mergeRecord(local, azdoRecord, azdoChangedDate, {
+                                area: azdoToArea(azdo),
+                                kind: payload.kind,
+                                assignee: payload.azdoFields?.assignedTo ?? null,
+                            });
+                            if (changed) {
+                                await store.updateWorkItem(itemId, merged);
+                                result.pulled++;
+                                events.emit('workitem.updated', { id: itemId, action: 'updated' });
+                            }
+                            else if (new Date(local.updatedAt).getTime() > new Date(azdoChangedDate).getTime()) {
+                                result.conflicts++;
+                            }
+                            // Always refresh the payload mirror — even if record fields
+                            // didn't change, AzDO custom fields (operator lane, lifecycle
+                            // booleans, etc.) may have been edited upstream.
+                            await store.setPayloadJson(itemId, payloadJson);
+                        }
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        result.errors.push({ workItemId: itemId, message: msg });
+                        console.warn(`[AzdoSync] Error processing item ${itemId}: ${msg}`);
+                    }
+                }
+            }
+            // Reconcile AzDO-sourced rows that are open locally but absent from the
+            // open upstream set — full mode only. Incremental never queries the
+            // complete id set, so its "not returned" set would be every unchanged
+            // item (heavy + wrong). Rather than blind-deleting (the old pruneOrphans
+            // behavior), we RE-FETCH only the small diff to confirm true state before
+            // removing anything — a transient fetch error must never cause an
+            // erroneous prune.
+            if (effectiveMode === 'full') {
+                const TERMINAL_LOCAL_STATUSES = new Set(['done', 'cancelled', 'duplicate']);
+                // Local OPEN azdo rows: source='azdo' and not in a terminal local
+                // status. Page through the LOCAL store (fixed page size, advance offset
+                // until a short page) so a board with >1 page of open rows can't
+                // silently skip prune candidates. This read is local-only; only the
+                // candidate diff is later fetched from AzDO.
+                const LOCAL_PAGE_SIZE = 1000;
+                const localOpenIds = [];
+                for (let offset = 0;; offset += LOCAL_PAGE_SIZE) {
+                    const page = await store.listWorkItems({ source: 'azdo', limit: LOCAL_PAGE_SIZE, offset });
+                    for (const r of page.workItems) {
+                        if (!TERMINAL_LOCAL_STATUSES.has(r.status)) {
+                            localOpenIds.push(r.id);
+                        }
+                    }
+                    if (page.workItems.length < LOCAL_PAGE_SIZE)
+                        break;
+                }
+                // Candidates: open locally but NOT in the open upstream set this run.
+                const candidates = localOpenIds.filter((id) => !azdoIdsSeen.has(id));
+                let prunedCount = 0;
+                if (candidates.length > 0) {
+                    for (let i = 0; i < candidates.length; i += BATCH_SIZE) {
+                        const batch = candidates.slice(i, i + BATCH_SIZE);
+                        let fetched;
+                        try {
+                            fetched = await withExponentialBackoff(() => client.getWorkItems(batch.map(Number)), 3, 1000, 30000);
+                        }
+                        catch (err) {
+                            // Transient fetch failure — KEEP this batch (safer than deleting
+                            // on an error). The next reconcile retries it.
+                            console.warn(`[AzdoSync] Reconcile fetch failed for ${batch.length} candidate(s) — keeping them: ` +
+                                (err instanceof Error ? err.message : String(err)));
+                            continue;
+                        }
+                        const fetchedMap = new Map(fetched.map((item) => [String(item.id), item]));
+                        for (const id of batch) {
+                            const item = fetchedMap.get(id);
+                            if (!item) {
+                                // Hard-deleted upstream — confirmed gone.
+                                await store.deleteWorkItem(id);
+                                prunedCount++;
+                                continue;
+                            }
+                            // Present upstream: read its true System.State. Terminal check
+                            // uses the SAME configured set as the WIQL open-filter so the two
+                            // can't drift.
+                            const upstreamState = String(item.fields[fieldNames.state] ?? '').trim();
+                            const isTerminal = terminalStateSet.has(upstreamState);
+                            if (isTerminal) {
+                                // Closed upstream — leave the open board.
+                                await store.deleteWorkItem(id);
+                                prunedCount++;
+                            }
+                            // else: still OPEN upstream (WIQL eventual-consistency lag) — KEEP
+                            // it; the next full reconcile will handle it.
+                        }
+                    }
+                }
+                if (prunedCount > 0) {
+                    events.emit('azdo.sync.pruned', { count: prunedCount });
+                }
+            }
+            // Hierarchy self-heal (full mode only): provision Epics/Features, link
+            // unparented items, and re-parent mis-parented ones. Idempotent
+            // (find-or-create + KV cache) and self-limiting — once correct, the next
+            // pull shows the right parent so they land in `alreadyCorrect`. Failure
+            // here must NEVER crash the sync tick, hence its own try/catch.
+            if (effectiveMode === 'full' && hierItems.length > 0) {
+                try {
+                    const projects = await resolveProjectConfigs(loadConfig(), store);
+                    const hier = await provisionHierarchy({ client, store, organization: config.organization, project: config.project, projects }, hierItems);
+                    if (hier.epicsCreated || hier.featuresCreated || hier.linked || hier.reparented) {
+                        events.emit('azdo.sync.hierarchy', hier);
+                        console.log(`[AzdoSync] Hierarchy: +${hier.epicsCreated} epics, +${hier.featuresCreated} features, ${hier.linked} linked, ${hier.reparented} reparented, ${hier.alreadyCorrect} ok, ${hier.skipped} skipped, ${hier.errors.length} errors`);
+                    }
+                }
+                catch (err) {
+                    console.error('[AzdoSync] Hierarchy provisioning failed (sync continues):', err instanceof Error ? err.message : String(err));
+                }
+            }
+            // Advance the watermark to (maxChangedDate − 60s) so the next incremental
+            // run re-scans a short overlap window (absorbs clock skew). Only advance
+            // forward — never rewind past a watermark a concurrent/prior run set.
+            if (maxChangedMs > 0) {
+                const nextWatermark = new Date(maxChangedMs - 60_000).toISOString();
+                const prevMs = currentWatermark ? new Date(currentWatermark).getTime() : 0;
+                if (!Number.isFinite(prevMs) || new Date(nextWatermark).getTime() > prevMs) {
+                    await store.setSyncMeta(watermarkKey, nextWatermark);
+                }
+            }
+            lastSuccessAt = Date.now();
+            lastError = undefined;
+            checkStale();
+            result.durationMs = Date.now() - t0;
+            events.emit('azdo.sync.tick', result);
+            return result;
+        }
+        catch (err) {
+            lastErrorAt = Date.now();
+            lastError = err instanceof Error ? err.message : String(err);
+            checkStale();
+            result.durationMs = Date.now() - t0;
+            throw err;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // pushLocalChange — push-up a single work item
+    // ---------------------------------------------------------------------------
+    async function pushLocalChange(workItemId) {
+        const local = await store.getWorkItem(workItemId);
+        if (!local) {
+            console.warn(`[AzdoSync] pushLocalChange: item ${workItemId} not found in local store`);
+            return;
+        }
+        const numericId = parseInt(workItemId, 10);
+        if (isNaN(numericId)) {
+            console.warn(`[AzdoSync] pushLocalChange: ${workItemId} is not a numeric AzDO ID`);
+            return;
+        }
+        // Build patches from the LOCAL intent, not a fresh AzDO fetch. Re-fetching
+        // AzDO and re-deriving patches from its current state would overwrite the
+        // very local edit we're trying to push.
+        const patches = await buildLocalPushPatches(store, fieldNames, workItemId, local, config);
+        try {
+            await withExponentialBackoff(() => client.updateWorkItem(numericId, patches), 3, 1000, 30000);
+        }
+        catch (err) {
+            if (err instanceof AzdoApiError && err.status !== 429 && err.status !== 503) {
+                console.error(`[AzdoSync] Push failed for ${workItemId}:`, err.message);
+                events.emit('azdo.push.failed', { workItemId, status: err.status, message: err.message });
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // start / stop
+    // ---------------------------------------------------------------------------
+    async function start() {
+        if (!config.enabled) {
+            return;
+        }
+        if (started) {
+            return;
+        }
+        started = true;
+        // Boot: a FULL sync seeds the complete backlog and establishes the
+        // watermark before the incremental heartbeat takes over.
+        inFlightSync = syncOnce({ mode: 'full' }).catch((err) => {
+            console.error('[AzdoSync] Initial sync failed:', err);
+            return { pulled: 0, pushed: 0, conflicts: 0, errors: [], durationMs: 0 };
+        });
+        await inFlightSync;
+        inFlightSync = null;
+        // Periodic FULL reconcile cadence: roughly every 15 minutes. A full pass
+        // re-scans the complete id set and prunes orphans (deletes that an
+        // incremental ChangedDate query can never observe). Every other tick is a
+        // cheap incremental pull.
+        const FULL_RECONCILE_MS = 900_000; // 15 minutes
+        const fullEveryNthTick = Math.max(1, Math.round(FULL_RECONCILE_MS / config.intervalMs));
+        let tick = 0;
+        intervalHandle = setInterval(() => {
+            tick += 1;
+            const mode = tick % fullEveryNthTick === 0 ? 'full' : 'incremental';
+            inFlightSync = syncOnce({ mode }).then(async () => {
+                if (drainAfterSync && root) {
+                    const ctx = { client, store, config, events, fetchToken: deps.fetchToken };
+                    try {
+                        const drainResult = await drainWorkItemPushQueue(root, ctx);
+                        console.log(`[AzdoSync] Drain complete: ${drainResult.drained} drained, ${drainResult.errors.length} errors`);
+                        if (drainResult.errors.length > 0) {
+                            console.warn('[AzdoSync] Drain errors:', drainResult.errors.map((e) => `${e.workItemId}(${e.lastError})`).join(', '));
+                        }
+                    }
+                    catch (err) {
+                        console.error('[AzdoSync] Drain threw unexpectedly (tick continues):', err instanceof Error ? err.message : String(err));
+                    }
+                }
+                return { pulled: 0, pushed: 0, conflicts: 0, errors: [], durationMs: 0 };
+            }).catch((err) => {
+                console.error('[AzdoSync] Periodic sync failed:', err);
+                return { pulled: 0, pushed: 0, conflicts: 0, errors: [], durationMs: 0 };
+            }).finally(() => {
+                inFlightSync = null;
+            });
+        }, config.intervalMs);
+    }
+    async function stop() {
+        if (intervalHandle !== null) {
+            clearInterval(intervalHandle);
+            intervalHandle = null;
+        }
+        started = false;
+        // Wait for any in-flight sync to settle
+        if (inFlightSync) {
+            await inFlightSync.catch(() => undefined);
+            inFlightSync = null;
+        }
+    }
+    function getStatus() {
+        const now = Date.now();
+        const threshold = config.intervalMs * 3;
+        const isStale = lastSuccessAt === null || (now - lastSuccessAt) > threshold;
+        return {
+            lastSuccessAt,
+            lastErrorAt,
+            lastError,
+            running: started,
+            isStale,
+        };
+    }
+    return { start, stop, syncOnce, pushLocalChange, getStatus };
+}
+//# sourceMappingURL=azureDevOpsSync.js.map