@letta-ai/dreams 0.0.1 → 0.0.3

package/dist/sync.js

@@ -0,0 +1,790 @@
+"use strict";
+/**
+ * Hook-safe `dreams sync` ([LET-10237] / [LET-10240]).
+ *
+ * Default invocation records a durable trigger and may spawn a detached worker.
+ * The hook parent always exits 0. The worker performs live scan + live-first
+ * upload, then — only when an active backfill policy already exists and upload
+ * budget remains — one backfill continuation slice + remaining-budget upload.
+ * Historical windows are never minted here; use `dreams backfill start`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSyncAdapter = resolveSyncAdapter;
+exports.setDetachedWorkerSpawnerForTests = setDetachedWorkerSpawnerForTests;
+exports.setBeforeWorkerLeaseReleaseForTests = setBeforeWorkerLeaseReleaseForTests;
+exports.readSessionHintFromStdin = readSessionHintFromStdin;
+exports.commandSyncSchedule = commandSyncSchedule;
+exports.commandSyncPause = commandSyncPause;
+exports.commandSyncResume = commandSyncResume;
+exports.commandSyncStatus = commandSyncStatus;
+exports.commandSyncWorker = commandSyncWorker;
+exports.commandSync = commandSync;
+const node_child_process_1 = require("node:child_process");
+const path = __importStar(require("node:path"));
+const upload_1 = require("./cloud/upload");
+const backfill_1 = require("./local/backfill");
+const db_1 = require("./local/db");
+const leases_1 = require("./local/leases");
+const scan_1 = require("./local/scan");
+const state_lock_1 = require("./local/state-lock");
+const sync_control_1 = require("./local/sync-control");
+const source_adapters_1 = require("./local/source-adapters");
+const store_1 = require("./store");
+const STDIN_LIMIT_BYTES = 64 * 1024;
+/** Resolve `--source <type>` at the sync command boundary (stdin never selects source). */
+function resolveSyncAdapter(sourceType) {
+    if (sourceType === undefined)
+        return (0, source_adapters_1.defaultSourceAdapter)();
+    const trimmed = sourceType.trim();
+    if (!trimmed)
+        throw new Error("unknown source type: (empty)");
+    return (0, source_adapters_1.getSourceAdapterByType)(trimmed);
+}
+function defaultWorkerEntry() {
+    const candidate = process.argv[1] ? path.resolve(process.argv[1]) : "";
+    // Only trust argv when this process was started via the CLI entrypoints.
+    // Under `node --test`, argv[1] is the test file and must not be respawned.
+    if (candidate && /(?:^|[/\\])(?:cli\.(?:js|ts)|dreams\.cjs)$/.test(candidate))
+        return candidate;
+    return path.resolve(__dirname, "..", "bin", "dreams.cjs");
+}
+function defaultSpawnDetachedWorker(force, sourceType) {
+    try {
+        const args = [defaultWorkerEntry(), "sync", "--worker", "--json"];
+        if (force)
+            args.push("--force");
+        const type = sourceType ?? (0, source_adapters_1.defaultSourceAdapter)().sourceType;
+        args.push("--source", type);
+        const child = (0, node_child_process_1.spawn)(process.execPath, args, {
+            detached: true,
+            stdio: "ignore",
+            shell: false,
+            env: process.env,
+        });
+        // Asynchronous spawn failures must not reject the hook parent.
+        child.on("error", () => {
+            /* leave durable trigger pending for a later wake */
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+let detachedWorkerSpawner = defaultSpawnDetachedWorker;
+/** Test-only: replace (or restore) the detached worker spawner. */
+function setDetachedWorkerSpawnerForTests(spawner) {
+    detachedWorkerSpawner = spawner ?? defaultSpawnDetachedWorker;
+}
+/** Test-only: run after the in-loop successor decision, before lease release. */
+let beforeWorkerLeaseReleaseForTests = null;
+function setBeforeWorkerLeaseReleaseForTests(hook) {
+    beforeWorkerLeaseReleaseForTests = hook;
+}
+function spawnDetachedWorker(force, sourceType) {
+    return detachedWorkerSpawner(force, sourceType);
+}
+function emit(json, payload, human) {
+    if (json)
+        console.log(JSON.stringify(payload, null, 2));
+    else
+        console.log(human());
+}
+function openInstallationDb() {
+    const installation = (0, store_1.loadOrCreateInstallation)();
+    const db = (0, db_1.openDb)({
+        installationId: installation.installation_id,
+        installationCreatedAt: installation.created_at,
+    });
+    return { db, installationId: installation.installation_id };
+}
+/**
+ * Bound stdin read for hook payloads.
+ * Ignore interactive TTYs. In non-TTY environments without a real pipe (tests),
+ * time out quickly so we never hang waiting for EOF.
+ */
+async function readSessionHintFromStdin(adapter, timeoutMs = 100) {
+    if (process.stdin.isTTY)
+        return null;
+    const chunks = [];
+    let total = 0;
+    const text = await new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeListener("data", onData);
+            process.stdin.removeListener("end", onEnd);
+            process.stdin.removeListener("error", onError);
+            // Pause so a non-EOF stdin (test runners / sockets) does not keep the
+            // event loop alive after the bounded read completes.
+            try {
+                process.stdin.pause();
+            }
+            catch {
+                // ignore
+            }
+            resolve(value);
+        };
+        const onData = (chunk) => {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buf.length;
+            if (total <= STDIN_LIMIT_BYTES)
+                chunks.push(buf);
+            if (total >= STDIN_LIMIT_BYTES)
+                finish(Buffer.concat(chunks).toString("utf8"));
+        };
+        const onEnd = () => finish(chunks.length ? Buffer.concat(chunks).toString("utf8") : null);
+        const onError = () => finish(null);
+        const timer = setTimeout(() => finish(chunks.length ? Buffer.concat(chunks).toString("utf8") : null), timeoutMs);
+        process.stdin.on("data", onData);
+        process.stdin.on("end", onEnd);
+        process.stdin.on("error", onError);
+        if (process.stdin.readableEnded)
+            onEnd();
+        else
+            process.stdin.resume();
+    });
+    if (!text)
+        return null;
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        // Only session_id is trusted as a live hint. transcript_path / cwd from hooks
+        // are informational and must not become authoritative discovery paths.
+        const candidates = [parsed.session_id, parsed.sessionId, parsed.sessionID];
+        for (const value of candidates) {
+            if (typeof value === "string" && adapter.validateSessionId(value))
+                return value;
+        }
+    }
+    catch {
+        // Malformed hook stdin is ignored; sync still proceeds for tracked sessions.
+    }
+    return null;
+}
+function shouldSpawnWorker(options) {
+    if (options.forced)
+        return true;
+    if (options.retryDue)
+        return true;
+    if (options.runtimeDue && options.pending)
+        return true;
+    return false;
+}
+async function commandSyncSchedule(options) {
+    // Hook parent must always exit 0 — never surface local/SQLite failures as exit 1.
+    const adapter = options.adapter;
+    const sourceId = adapter.sourceId;
+    try {
+        const sessionHint = await readSessionHintFromStdin(adapter);
+        const { db } = openInstallationDb();
+        try {
+            const leaseRow = db.prepare("SELECT owner, expires_at FROM leases WHERE name = ?").get(leases_1.SYNC_WORKER_LEASE);
+            const workerActive = Boolean(leaseRow && leaseRow.expires_at > Date.now());
+            (0, sync_control_1.normalizeStaleRunning)(db, workerActive);
+            const recorded = (0, sync_control_1.recordSyncRequest)(db, { forced: options.force, sessionHint, sourceId });
+            if (recorded.paused) {
+                emit(options.json, { status: "paused", schema_version: 1 }, () => "Sync paused; hooks are no-ops until `dreams sync resume`.");
+                return 0;
+            }
+            const runtime = (0, sync_control_1.readRuntime)(db, sourceId);
+            const pending = (0, sync_control_1.triggerPending)(db, sourceId);
+            const due = options.force || recorded.forced || (0, sync_control_1.cadenceDue)(runtime) || (0, sync_control_1.retryDueFromError)(runtime);
+            if (!due && !workerActive) {
+                // Do not advance processed_gen here. Consuming on not_due would drop a
+                // durable trigger left pending after spawn failure / pass-budget handoff.
+                emit(options.json, {
+                    status: "not_due",
+                    schema_version: 1,
+                    source: adapter.sourceType,
+                    trigger_generation: recorded.generation,
+                    pending,
+                    next_due_at: runtime.next_due_at,
+                    cadence_ms: sync_control_1.CADENCE_MS,
+                }, () => `Sync not due until ${runtime.next_due_at ?? "now"}.`);
+                return 0;
+            }
+            if (workerActive) {
+                emit(options.json, {
+                    status: "coalesced",
+                    schema_version: 1,
+                    source: adapter.sourceType,
+                    trigger_generation: recorded.generation,
+                    forced: recorded.forced,
+                }, () => `Sync request coalesced into the running worker (generation ${recorded.generation}).`);
+                return 0;
+            }
+            if (!shouldSpawnWorker({
+                forced: options.force || recorded.forced,
+                runtimeDue: (0, sync_control_1.cadenceDue)(runtime),
+                retryDue: (0, sync_control_1.retryDueFromError)(runtime),
+                pending,
+            })) {
+                emit(options.json, {
+                    status: "coalesced",
+                    schema_version: 1,
+                    source: adapter.sourceType,
+                    trigger_generation: recorded.generation,
+                    forced: recorded.forced,
+                }, () => `Sync request recorded (generation ${recorded.generation}).`);
+                return 0;
+            }
+            const spawned = spawnDetachedWorker(options.force || recorded.forced, adapter.sourceType);
+            // Spawn failure must leave the durable trigger pending for a later wake
+            // and record a degraded diagnosis visible via `sync status`.
+            if (!spawned) {
+                (0, sync_control_1.markRuntimeDegraded)(db, "spawn_failed", "worker could not be detached; trigger left pending for next wake", null, sourceId);
+            }
+            emit(options.json, {
+                status: spawned ? "scheduled" : "coalesced",
+                schema_version: 1,
+                source: adapter.sourceType,
+                trigger_generation: recorded.generation,
+                forced: recorded.forced,
+                worker: spawned ? "spawned" : "spawn_failed",
+            }, () => spawned
+                ? `Sync scheduled (generation ${recorded.generation}).`
+                : `Sync request recorded; worker spawn failed — will retry on next wake (generation ${recorded.generation}).`);
+            return 0;
+        }
+        finally {
+            (0, db_1.closeDb)();
+        }
+    }
+    catch (error) {
+        try {
+            emit(options.json, {
+                status: "coalesced",
+                schema_version: 1,
+                source: adapter.sourceType,
+                worker: "schedule_error",
+                message: error instanceof Error ? error.message : String(error),
+            }, () => "Sync request could not be fully scheduled; will retry on next wake.");
+        }
+        catch {
+            // ignore secondary emit failures
+        }
+        return 0;
+    }
+}
+function commandSyncPause(json) {
+    const { db } = openInstallationDb();
+    try {
+        const runtime = (0, sync_control_1.setPaused)(db, true);
+        emit(json, { status: "paused", schema_version: 1, sync: runtime }, () => "Sync paused. Existing hooks will no-op.");
+        return 0;
+    }
+    finally {
+        (0, db_1.closeDb)();
+    }
+}
+async function commandSyncResume(json) {
+    const { db } = openInstallationDb();
+    try {
+        const runtime = (0, sync_control_1.setPaused)(db, false);
+        // Resume force-wakes every source with a trigger row; spawn the first
+        // runnable source and let post-pass handoff chain the rest ([LET-10314]).
+        const nextId = (0, sync_control_1.nextRunnableSourceId)(db) ?? (0, source_adapters_1.defaultSourceAdapter)().sourceId;
+        const nextType = (0, source_adapters_1.getSourceAdapterById)(nextId).sourceType;
+        const spawned = spawnDetachedWorker(true, nextType);
+        emit(json, { status: "resumed", schema_version: 1, sync: runtime, worker: spawned ? "scheduled" : "pending", source: nextType }, () => "Sync resumed; an immediate sync was requested.");
+        return 0;
+    }
+    finally {
+        (0, db_1.closeDb)();
+    }
+}
+function commandSyncStatus(json) {
+    const { db } = openInstallationDb();
+    try {
+        const leaseRow = db.prepare("SELECT expires_at FROM leases WHERE name = ?").get(leases_1.SYNC_WORKER_LEASE);
+        const workerActive = Boolean(leaseRow && leaseRow.expires_at > Date.now());
+        (0, sync_control_1.normalizeStaleRunning)(db, workerActive);
+        const runtime = (0, sync_control_1.readRuntime)(db);
+        const trigger = (0, sync_control_1.observeTrigger)(db);
+        const pending = trigger.requested_gen > trigger.processed_gen || trigger.forced;
+        const effective = (0, sync_control_1.effectiveSyncState)({
+            runtime,
+            pending,
+            forced: trigger.forced,
+            workerActive,
+        });
+        const payload = {
+            schema_version: 1,
+            status: "ok",
+            sync: {
+                ...runtime,
+                effective_state: effective,
+                worker_active: workerActive,
+                pending,
+                requested_gen: trigger.requested_gen,
+                processed_gen: trigger.processed_gen,
+                forced: trigger.forced,
+                session_hints: trigger.session_hints,
+                cadence_ms: sync_control_1.CADENCE_MS,
+            },
+        };
+        emit(json, payload, () => [
+            "Dreams sync status",
+            "",
+            `  Effective:   ${effective}`,
+            `  Runtime:     ${runtime.state}`,
+            `  Paused:      ${runtime.paused ? "yes" : "no"}`,
+            `  Pending:     ${pending ? "yes" : "no"}`,
+            `  Worker:      ${workerActive ? "active" : "idle"}`,
+            `  Next due:    ${runtime.next_due_at ?? "(immediately)"}`,
+            `  Last success:${runtime.last_success_at ? ` ${runtime.last_success_at}` : " (none)"}`,
+            `  Last error:  ${runtime.last_error_code ? `${runtime.last_error_code}: ${runtime.last_error_message}` : " (none)"}`,
+        ].join("\n"));
+        return 0;
+    }
+    finally {
+        (0, db_1.closeDb)();
+    }
+}
+function uploadFailureResult(db, uploadSummary, budgetExhausted, backfillContinuation, sourceId) {
+    if (uploadSummary.stopped_code) {
+        return {
+            ok: false,
+            code: uploadSummary.stopped_code,
+            message: uploadSummary.stopped_reason,
+            budgetExhausted,
+            backfillContinuation,
+            retryAt: (0, sync_control_1.earliestUploadRetryAt)(db, sourceId) ?? (0, sync_control_1.fallbackRetryAt)(uploadSummary.stopped_code),
+            paused: false,
+        };
+    }
+    if (uploadSummary.retry_scheduled > 0) {
+        return {
+            ok: false,
+            code: "network",
+            message: `retry_scheduled=${uploadSummary.retry_scheduled}`,
+            budgetExhausted,
+            backfillContinuation,
+            retryAt: (0, sync_control_1.earliestUploadRetryAt)(db, sourceId) ?? (0, sync_control_1.fallbackRetryAt)("network"),
+            paused: false,
+        };
+    }
+    if (uploadSummary.partial && uploadSummary.quarantined > 0 && uploadSummary.accepted === 0 && uploadSummary.duplicate === 0) {
+        return {
+            ok: false,
+            code: "local_error",
+            message: "upload pass quarantined rows without accepts",
+            budgetExhausted,
+            backfillContinuation,
+            retryAt: (0, sync_control_1.fallbackRetryAt)("local_error"),
+            paused: false,
+        };
+    }
+    return null;
+}
+async function runOneWorkerPass(db, installationId, sourceOwner, workerOwner, observed, adapter) {
+    if ((0, sync_control_1.isPaused)(db)) {
+        return {
+            ok: true,
+            code: null,
+            message: null,
+            budgetExhausted: false,
+            backfillContinuation: false,
+            retryAt: null,
+            paused: true,
+        };
+    }
+    const heartbeat = () => {
+        if (!(0, leases_1.renewLease)(db, leases_1.SYNC_WORKER_LEASE, workerOwner))
+            throw new Error("sync-worker lease lost");
+    };
+    const cancel = () => (0, sync_control_1.isPaused)(db);
+    const totalBudget = (0, sync_control_1.uploadRowBudget)();
+    const scanSummary = (0, scan_1.reconcile)(db, {
+        installationId,
+        leaseOwner: sourceOwner,
+        adapter,
+        mode: "live",
+        hintSessionIds: observed.session_hints,
+        priority: "live",
+        shouldCancel: cancel,
+        onProgress: heartbeat,
+    });
+    if ((0, sync_control_1.isPaused)(db)) {
+        return {
+            ok: true,
+            code: null,
+            message: null,
+            budgetExhausted: false,
+            backfillContinuation: false,
+            retryAt: null,
+            paused: true,
+        };
+    }
+    heartbeat();
+    const liveUpload = await (0, upload_1.runUpload)(db, {
+        installationId,
+        leaseOwner: sourceOwner,
+        adapter,
+        maxRows: totalBudget,
+        shouldCancel: cancel,
+        onProgress: heartbeat,
+    });
+    if ((0, sync_control_1.isPaused)(db)) {
+        return {
+            ok: true,
+            code: null,
+            message: null,
+            budgetExhausted: liveUpload.budget_exhausted,
+            backfillContinuation: false,
+            retryAt: null,
+            paused: true,
+        };
+    }
+    const liveFail = uploadFailureResult(db, liveUpload, liveUpload.budget_exhausted, false, adapter.sourceId);
+    if (liveFail)
+        return liveFail;
+    let rowsProcessed = liveUpload.rows_processed;
+    let budgetExhausted = liveUpload.budget_exhausted;
+    let accepted = liveUpload.accepted;
+    let duplicate = liveUpload.duplicate;
+    let backfillSessions = 0;
+    let backfillEnqueued = 0;
+    let backfillAccepted = 0;
+    let backfillContinuation = false;
+    // Live-first: only continue an existing active policy when shared budget remains.
+    const remainingBudget = Math.max(0, totalBudget - rowsProcessed);
+    if (!budgetExhausted && remainingBudget > 0) {
+        const backfill = (0, backfill_1.runBackfillContinuePass)(db, {
+            installationId,
+            leaseOwner: sourceOwner,
+            adapter,
+            shouldCancel: cancel,
+            onProgress: heartbeat,
+        });
+        if ((0, sync_control_1.isPaused)(db) || backfill.canceled) {
+            return {
+                ok: true,
+                code: null,
+                message: null,
+                budgetExhausted,
+                backfillContinuation: false,
+                retryAt: null,
+                paused: true,
+            };
+        }
+        backfillSessions = backfill.sessions_selected;
+        backfillEnqueued = backfill.scan.segments_enqueued;
+        if (backfill.status !== "skipped") {
+            heartbeat();
+            const backfillUpload = await (0, upload_1.runUpload)(db, {
+                installationId,
+                leaseOwner: sourceOwner,
+                adapter,
+                maxRows: remainingBudget,
+                shouldCancel: cancel,
+                onProgress: heartbeat,
+            });
+            if ((0, sync_control_1.isPaused)(db)) {
+                return {
+                    ok: true,
+                    code: null,
+                    message: null,
+                    budgetExhausted: budgetExhausted || backfillUpload.budget_exhausted,
+                    backfillContinuation: false,
+                    retryAt: null,
+                    paused: true,
+                };
+            }
+            rowsProcessed += backfillUpload.rows_processed;
+            budgetExhausted = budgetExhausted || backfillUpload.budget_exhausted;
+            accepted += backfillUpload.accepted;
+            duplicate += backfillUpload.duplicate;
+            backfillAccepted = backfillUpload.accepted + backfillUpload.duplicate;
+            const backfillMadeProgress = backfill.made_progress || backfillAccepted > 0 || backfillEnqueued > 0;
+            backfillContinuation = backfillMadeProgress && backfill.actionable_remaining > 0;
+            const backfillFail = uploadFailureResult(db, backfillUpload, budgetExhausted, 
+            // Keep continuation intent even on retryable upload failure when frontier remains.
+            backfillContinuation, adapter.sourceId);
+            if (backfillFail)
+                return backfillFail;
+        }
+    }
+    return {
+        ok: true,
+        code: null,
+        message: `live_sessions=${scanSummary.sessions_queued}; backfill_sessions=${backfillSessions}; accepted=${accepted}; duplicate=${duplicate}; rows_processed=${rowsProcessed}`,
+        budgetExhausted,
+        backfillContinuation,
+        retryAt: null,
+        paused: false,
+    };
+}
+async function commandSyncWorker(options) {
+    const adapter = options.adapter;
+    const sourceId = adapter.sourceId;
+    const lock = (0, state_lock_1.acquireLocalStateLock)();
+    if (lock === null) {
+        // Leave trigger pending for a later wake.
+        if (options.json) {
+            console.log(JSON.stringify({ status: "busy", schema_version: 1, code: "busy", source: adapter.sourceType }));
+        }
+        return 0;
+    }
+    const { db, installationId } = openInstallationDb();
+    let workerOwner = null;
+    let sourceOwner = null;
+    let handoffEligible = false;
+    let passes = 0;
+    let lastResult = {
+        ok: true,
+        code: null,
+        message: null,
+        budgetExhausted: false,
+        backfillContinuation: false,
+        retryAt: null,
+        paused: false,
+    };
+    try {
+        workerOwner = (0, leases_1.acquireLease)(db, leases_1.SYNC_WORKER_LEASE);
+        if (workerOwner === null) {
+            if (options.json) {
+                console.log(JSON.stringify({ status: "busy", schema_version: 1, code: "busy", source: adapter.sourceType }));
+            }
+            return 0;
+        }
+        (0, sync_control_1.normalizeStaleRunning)(db, true);
+        if ((0, sync_control_1.isPaused)(db)) {
+            if (options.json)
+                console.log(JSON.stringify({ status: "paused", schema_version: 1, source: adapter.sourceType }));
+            return 0;
+        }
+        (0, sync_control_1.markRuntimeRunning)(db);
+        while (passes < sync_control_1.MAX_TRAILING_PASSES) {
+            if ((0, sync_control_1.isPaused)(db))
+                break;
+            const observed = (0, sync_control_1.observeTrigger)(db, sourceId);
+            const runtime = (0, sync_control_1.readRuntime)(db, sourceId);
+            const due = options.force ||
+                observed.forced ||
+                observed.requested_gen > observed.processed_gen ||
+                (0, sync_control_1.cadenceDue)(runtime) ||
+                (0, sync_control_1.retryDueFromError)(runtime);
+            if (!due && passes > 0)
+                break;
+            if (!due && passes === 0 && !options.force && !observed.forced) {
+                break;
+            }
+            sourceOwner = (0, leases_1.acquireLease)(db, leases_1.SOURCE_LEASE);
+            if (sourceOwner === null) {
+                (0, sync_control_1.markRuntimeDegraded)(db, "busy", "source lease busy; trigger left pending", (0, sync_control_1.fallbackRetryAt)("busy"), sourceId);
+                lastResult = {
+                    ok: false,
+                    code: "busy",
+                    message: "source lease busy",
+                    budgetExhausted: false,
+                    backfillContinuation: false,
+                    retryAt: (0, sync_control_1.fallbackRetryAt)("busy"),
+                    paused: false,
+                };
+                break;
+            }
+            try {
+                if (!(0, leases_1.renewLease)(db, leases_1.SYNC_WORKER_LEASE, workerOwner))
+                    break;
+                lastResult = await runOneWorkerPass(db, installationId, sourceOwner, workerOwner, observed, adapter);
+                // Pause mid-pass must not consume the observed generation or its hints.
+                if (lastResult.paused || (0, sync_control_1.isPaused)(db)) {
+                    lastResult = { ...lastResult, paused: true };
+                    break;
+                }
+                const keepPending = lastResult.budgetExhausted || lastResult.backfillContinuation;
+                const nextDueAt = lastResult.ok ? undefined : (lastResult.retryAt ?? (0, sync_control_1.fallbackRetryAt)(lastResult.code));
+                (0, sync_control_1.completeSyncPass)(db, sourceId, observed.requested_gen, {
+                    ok: lastResult.ok,
+                    errorCode: lastResult.code,
+                    errorMessage: lastResult.message,
+                    advanceCadence: lastResult.ok && !keepPending,
+                    clearHints: lastResult.ok,
+                    forcePending: keepPending,
+                    nextDueAt,
+                });
+            }
+            finally {
+                (0, leases_1.releaseLease)(db, leases_1.SOURCE_LEASE, sourceOwner);
+                sourceOwner = null;
+            }
+            passes++;
+            if (!(0, sync_control_1.triggerPending)(db, sourceId))
+                break;
+            // Trailing pass only if generation advanced during the pass.
+            if (!(0, sync_control_1.observeTrigger)(db, sourceId).requested_gen ||
+                (0, sync_control_1.observeTrigger)(db, sourceId).requested_gen <= observed.requested_gen) {
+                break;
+            }
+        }
+        // Immediate successors are only for successful (non-paused) passes. The
+        // actual pending check happens after lease release so a coalesced Stop wake
+        // that arrives during shutdown is not lost.
+        handoffEligible = lastResult.ok && !lastResult.paused;
+        if (options.json) {
+            console.log(JSON.stringify({
+                status: lastResult.paused ? "paused" : lastResult.ok ? "ok" : "degraded",
+                schema_version: 1,
+                source: adapter.sourceType,
+                passes,
+                code: lastResult.code,
+                message: lastResult.message,
+                sync: (0, sync_control_1.readRuntime)(db, sourceId),
+            }));
+        }
+        return 0;
+    }
+    catch (error) {
+        try {
+            // Do not advance processed_gen — leave in-flight and newer generations pending.
+            (0, sync_control_1.markRuntimeDegraded)(db, "local_error", error instanceof Error ? error.message : String(error), (0, sync_control_1.earliestUploadRetryAt)(db, sourceId) ?? (0, sync_control_1.fallbackRetryAt)("local_error"), sourceId);
+        }
+        catch {
+            // best effort
+        }
+        if (options.json) {
+            console.log(JSON.stringify({
+                status: "degraded",
+                schema_version: 1,
+                source: adapter.sourceType,
+                code: "local_error",
+                message: error instanceof Error ? error.message : String(error),
+            }));
+        }
+        handoffEligible = false;
+        return 0;
+    }
+    finally {
+        if (sourceOwner)
+            (0, leases_1.releaseLease)(db, leases_1.SOURCE_LEASE, sourceOwner);
+        try {
+            beforeWorkerLeaseReleaseForTests?.(db);
+        }
+        catch {
+            // test hooks must not break cleanup
+        }
+        if (workerOwner)
+            (0, leases_1.releaseLease)(db, leases_1.SYNC_WORKER_LEASE, workerOwner);
+        (0, db_1.closeDb)();
+        // Release the local-state lock before the final pending check so a hook that
+        // spawned during shutdown cannot observe busy-on-lock and exit while we also
+        // skip launching a successor.
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+        let successorType = null;
+        if (handoffEligible) {
+            try {
+                const again = openInstallationDb();
+                try {
+                    // Prefer this source when still pending; otherwise hand off to another
+                    // registered source with an actionable wake (cross-source coalesce).
+                    const nextId = (0, sync_control_1.nextRunnableSourceId)(again.db, sourceId);
+                    if (nextId)
+                        successorType = (0, source_adapters_1.getSourceAdapterById)(nextId).sourceType;
+                }
+                finally {
+                    (0, db_1.closeDb)();
+                }
+            }
+            catch {
+                successorType = null;
+            }
+        }
+        if (successorType)
+            spawnDetachedWorker(true, successorType);
+    }
+}
+async function commandSync(subcommand, options) {
+    let adapter;
+    try {
+        adapter = resolveSyncAdapter(options.sourceType);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    if (options.worker) {
+        if (subcommand) {
+            process.stderr.write(`--worker cannot be combined with sync ${subcommand}\n`);
+            return 1;
+        }
+        return commandSyncWorker({ json: options.json, force: options.force, adapter });
+    }
+    switch (subcommand) {
+        case undefined:
+            return commandSyncSchedule({ json: options.json, force: options.force, adapter });
+        case "pause":
+            if (options.force) {
+                process.stderr.write(`--force is not valid with sync pause\n`);
+                return 1;
+            }
+            if (options.sourceType) {
+                process.stderr.write(`--source is not valid with sync pause\n`);
+                return 1;
+            }
+            return commandSyncPause(options.json);
+        case "resume":
+            if (options.force) {
+                process.stderr.write(`--force is not valid with sync resume\n`);
+                return 1;
+            }
+            if (options.sourceType) {
+                process.stderr.write(`--source is not valid with sync resume\n`);
+                return 1;
+            }
+            return commandSyncResume(options.json);
+        case "status":
+            if (options.force) {
+                process.stderr.write(`--force is not valid with sync status\n`);
+                return 1;
+            }
+            if (options.sourceType) {
+                process.stderr.write(`--source is not valid with sync status\n`);
+                return 1;
+            }
+            return commandSyncStatus(options.json);
+        default:
+            process.stderr.write(`Unknown sync subcommand: ${subcommand} — expected pause, resume, or status\n`);
+            return 1;
+    }
+}