@letta-ai/dreams 0.0.1 → 0.0.3

package/dist/local/backfill.js

@@ -0,0 +1,608 @@
+"use strict";
+/**
+ * Historical backfill policy + session frontier ([LET-10239] / [LET-10240]).
+ *
+ * `dreams backfill start --since <RFC3339>` freezes `until_at = now`, persists
+ * the approved window, and runs one bounded local scan/queue pass. The sync
+ * worker continues an existing active policy via `runBackfillContinuePass`
+ * (never mints a new policy).
+ */
+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.BackfillArgumentError = exports.BackfillPolicyConflictError = exports.DEFAULT_BACKFILL_SESSION_BUDGET = exports.DEFAULT_SOURCE_ID = void 0;
+exports.parseRfc3339 = parseRfc3339;
+exports.sessionBudget = sessionBudget;
+exports.readBackfillPolicy = readBackfillPolicy;
+exports.ensureBackfillPolicy = ensureBackfillPolicy;
+exports.runBackfillStartPass = runBackfillStartPass;
+exports.runBackfillContinuePass = runBackfillContinuePass;
+exports.commandBackfillStart = commandBackfillStart;
+const crypto = __importStar(require("node:crypto"));
+const store_1 = require("../store");
+const config_1 = require("./config");
+const db_1 = require("./db");
+const leases_1 = require("./leases");
+const scan_1 = require("./scan");
+const source_adapters_1 = require("./source-adapters");
+const state_lock_1 = require("./state-lock");
+/** CLI default — Claude via deterministic registry ([LET-10313]). */
+exports.DEFAULT_SOURCE_ID = (0, source_adapters_1.defaultSourceAdapter)().sourceId;
+exports.DEFAULT_BACKFILL_SESSION_BUDGET = 16;
+class BackfillPolicyConflictError extends Error {
+    code = "backfill_policy_conflict";
+    constructor(message) {
+        super(message);
+        this.name = "BackfillPolicyConflictError";
+    }
+}
+exports.BackfillPolicyConflictError = BackfillPolicyConflictError;
+class BackfillArgumentError extends Error {
+    code = "invalid_argument";
+    constructor(message) {
+        super(message);
+        this.name = "BackfillArgumentError";
+    }
+}
+exports.BackfillArgumentError = BackfillArgumentError;
+function ensureLocalSource(db, adapter) {
+    const now = (0, db_1.nowIso)();
+    const id = adapter.sourceId;
+    db.prepare(`INSERT INTO sources (id, source_type, source_key, display_name, adapter_version, status, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, 'detected', ?, ?)
+     ON CONFLICT(id) DO NOTHING`).run(id, adapter.sourceType, adapter.sourceKey, adapter.displayName, adapter.adapterVersion, now, now);
+    return id;
+}
+/** Strict RFC3339: timezone required, and calendar components must be real dates. */
+function parseRfc3339(value, label) {
+    const match = value.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(?:Z|([+-])(\d{2}):(\d{2}))$/);
+    if (!match) {
+        throw new BackfillArgumentError(`${label} must be RFC3339 with a timezone (e.g. 2026-01-01T00:00:00.000Z)`);
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    const second = Number(match[6]);
+    if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59) {
+        throw new BackfillArgumentError(`${label} has out-of-range date/time components`);
+    }
+    const utc = Date.UTC(year, month - 1, day, hour, minute, second);
+    const probe = new Date(utc);
+    if (probe.getUTCFullYear() !== year ||
+        probe.getUTCMonth() !== month - 1 ||
+        probe.getUTCDate() !== day ||
+        probe.getUTCHours() !== hour ||
+        probe.getUTCMinutes() !== minute ||
+        probe.getUTCSeconds() !== second) {
+        throw new BackfillArgumentError(`${label} is not a real calendar date/time`);
+    }
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms)) {
+        throw new BackfillArgumentError(`${label} must be a valid RFC3339 timestamp`);
+    }
+    return new Date(ms).toISOString();
+}
+function sessionBudget() {
+    const raw = process.env.DREAMS_BACKFILL_SESSION_BUDGET;
+    if (raw) {
+        const n = Number(raw);
+        if (Number.isSafeInteger(n) && n > 0)
+            return n;
+    }
+    return exports.DEFAULT_BACKFILL_SESSION_BUDGET;
+}
+function readBackfillPolicy(db, sourceId = exports.DEFAULT_SOURCE_ID) {
+    const row = db.prepare("SELECT backfill_policy FROM sources WHERE id = ?").get(sourceId);
+    if (!row?.backfill_policy)
+        return null;
+    try {
+        const parsed = JSON.parse(row.backfill_policy);
+        if (parsed.version !== 1 ||
+            typeof parsed.policy_id !== "string" ||
+            typeof parsed.since_at !== "string" ||
+            typeof parsed.until_at !== "string" ||
+            (parsed.status !== "active" && parsed.status !== "completed") ||
+            typeof parsed.started_at !== "string") {
+            return null;
+        }
+        return {
+            version: 1,
+            policy_id: parsed.policy_id,
+            since_at: parsed.since_at,
+            until_at: parsed.until_at,
+            status: parsed.status,
+            started_at: parsed.started_at,
+            completed_at: typeof parsed.completed_at === "string" ? parsed.completed_at : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writePolicy(db, sourceId, policy) {
+    db.prepare("UPDATE sources SET backfill_policy = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(policy), (0, db_1.nowIso)(), sourceId);
+}
+/**
+ * Initialize or resume a backfill policy.
+ * Same active since_at is idempotent (keeps frozen until_at + policy_id).
+ * A different active since_at fails closed without mutation.
+ * Starting after a completed policy mints a new policy_id (fresh frontier).
+ */
+function ensureBackfillPolicy(db, sinceRaw, adapter) {
+    const sinceAt = parseRfc3339(sinceRaw, "--since");
+    const sourceId = adapter.sourceId;
+    return (0, db_1.tx)(db, () => {
+        ensureLocalSource(db, adapter);
+        const existing = readBackfillPolicy(db, sourceId);
+        if (existing?.status === "active") {
+            if (existing.since_at !== sinceAt) {
+                throw new BackfillPolicyConflictError(`active backfill policy uses since_at=${existing.since_at}; refuse to replace with ${sinceAt}`);
+            }
+            return existing;
+        }
+        const now = (0, db_1.nowIso)();
+        if (Date.parse(sinceAt) > Date.parse(now)) {
+            throw new BackfillArgumentError("--since must not be after the frozen until_at (now)");
+        }
+        const policy = {
+            version: 1,
+            policy_id: crypto.randomUUID(),
+            since_at: sinceAt,
+            until_at: now,
+            status: "active",
+            started_at: now,
+            completed_at: null,
+        };
+        writePolicy(db, sourceId, policy);
+        return policy;
+    });
+}
+function withinWindow(policy, mtimeMs) {
+    if (mtimeMs === null)
+        return false;
+    const since = Date.parse(policy.since_at);
+    const until = Date.parse(policy.until_at);
+    return mtimeMs >= since && mtimeMs <= until;
+}
+function upsertFrontierPending(db, policyId, sourceId, session, generation, sourceFileId) {
+    const now = (0, db_1.nowIso)();
+    db.prepare(`INSERT INTO backfill_frontier
+       (policy_id, source_id, session_id, generation, source_file_id, mtime_ms, status, completed_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, 'pending', NULL, ?)
+     ON CONFLICT(policy_id, session_id, generation) DO UPDATE SET
+       mtime_ms = excluded.mtime_ms,
+       source_file_id = COALESCE(excluded.source_file_id, backfill_frontier.source_file_id),
+       updated_at = excluded.updated_at
+     WHERE backfill_frontier.status = 'pending'`).run(policyId, sourceId, session.session_id, generation, sourceFileId, session.mtime_ms, now);
+}
+function markFrontierComplete(db, policyId, sessionId, generation) {
+    const now = (0, db_1.nowIso)();
+    db.prepare(`UPDATE backfill_frontier
+        SET status = 'complete', completed_at = ?, updated_at = ?
+      WHERE policy_id = ? AND session_id = ? AND generation = ? AND status = 'pending'`).run(now, now, policyId, sessionId, generation);
+}
+function markFrontierExcluded(db, policyId, sessionId, generation) {
+    const now = (0, db_1.nowIso)();
+    db.prepare(`UPDATE backfill_frontier
+        SET status = 'excluded', completed_at = COALESCE(completed_at, ?), updated_at = ?
+      WHERE policy_id = ? AND session_id = ? AND generation = ? AND status = 'pending'`).run(now, now, policyId, sessionId, generation);
+}
+function supersedeOlderGenerations(db, policyId, sessionId, currentGeneration) {
+    const now = (0, db_1.nowIso)();
+    db.prepare(`UPDATE backfill_frontier
+        SET status = 'complete', completed_at = COALESCE(completed_at, ?), updated_at = ?
+      WHERE policy_id = ? AND session_id = ? AND generation < ? AND status = 'pending'`).run(now, now, policyId, sessionId, currentGeneration);
+}
+function currentGeneration(db, sourceId, sessionId) {
+    return (db
+        .prepare("SELECT id AS source_file_id, generation FROM source_files WHERE source_id = ? AND session_id = ? AND is_current = 1")
+        .get(sourceId, sessionId) ?? null);
+}
+function unfinishedFrontier(db, policyId) {
+    return db
+        .prepare(`SELECT session_id, generation, mtime_ms
+         FROM backfill_frontier
+        WHERE policy_id = ? AND status = 'pending'
+        ORDER BY CASE WHEN mtime_ms IS NULL THEN 1 ELSE 0 END, mtime_ms DESC, session_id ASC`)
+        .all(policyId);
+}
+function frontierCounts(db, policyId) {
+    const rows = db
+        .prepare(`SELECT status, count(*) AS c FROM backfill_frontier WHERE policy_id = ? GROUP BY status`)
+        .all(policyId);
+    const counts = { pending: 0, complete: 0, excluded: 0 };
+    for (const row of rows) {
+        if (row.status === "pending")
+            counts.pending = row.c;
+        if (row.status === "complete")
+            counts.complete = row.c;
+        if (row.status === "excluded")
+            counts.excluded = row.c;
+    }
+    return counts;
+}
+function maybeCompletePolicy(db, sourceId, policy) {
+    const counts = frontierCounts(db, policy.policy_id);
+    if (counts.pending > 0)
+        return policy;
+    const completed = { ...policy, status: "completed", completed_at: (0, db_1.nowIso)() };
+    writePolicy(db, sourceId, completed);
+    return completed;
+}
+function emptyScanSummary(sourceId = exports.DEFAULT_SOURCE_ID) {
+    return {
+        source_id: sourceId,
+        sessions_discovered: 0,
+        sessions_queued: 0,
+        sessions_excluded: 0,
+        sessions_skipped_unapproved: 0,
+        sessions_failed: 0,
+        generations_reset: 0,
+        objects_canceled: 0,
+        segments_enqueued: 0,
+        bytes_enqueued: 0,
+        queued: [],
+        processed_sessions: [],
+    };
+}
+function countActionableFrontier(db, policyId, discoveredById) {
+    const seen = new Set();
+    let count = 0;
+    for (const row of unfinishedFrontier(db, policyId)) {
+        if (seen.has(row.session_id))
+            continue;
+        seen.add(row.session_id);
+        if (discoveredById.has(row.session_id))
+            count++;
+    }
+    return count;
+}
+/**
+ * One bounded backfill slice against an already-resolved policy: refresh
+ * frontier, scan/queue up to the session budget (newest unfinished sessions
+ * first by mtime), mark completions. Bytes within a session stay forward-only.
+ */
+function runBackfillSlice(db, policy, options) {
+    const adapter = options.adapter;
+    const sourceId = adapter.sourceId;
+    if (options.shouldCancel?.()) {
+        return {
+            status: "ok",
+            skip_reason: null,
+            policy,
+            sessions_in_window: 0,
+            sessions_selected: 0,
+            frontier_pending: frontierCounts(db, policy.policy_id).pending,
+            frontier_complete: frontierCounts(db, policy.policy_id).complete,
+            actionable_remaining: 0,
+            made_progress: false,
+            canceled: true,
+            scan: emptyScanSummary(sourceId),
+        };
+    }
+    const beforeCounts = frontierCounts(db, policy.policy_id);
+    const terminalBefore = beforeCounts.complete + beforeCounts.excluded;
+    const discovered = adapter.discoverSessions();
+    const roots = (0, config_1.getApprovedRoots)(db);
+    const discoveredById = new Map(discovered.map((session) => [session.session_id, session]));
+    const inWindowApproved = discovered.filter((session) => withinWindow(policy, session.mtime_ms) &&
+        session.cwd !== null &&
+        (0, config_1.isUnderApprovedRoot)(roots, session.cwd) !== null);
+    // Seed frontier for approved sessions currently in the frozen window.
+    // Persisted pending rows remain selectable even if mtime later moves outside.
+    (0, db_1.tx)(db, () => {
+        for (const session of inWindowApproved) {
+            const current = currentGeneration(db, sourceId, session.session_id);
+            const generation = current?.generation ?? 1;
+            if (current)
+                supersedeOlderGenerations(db, policy.policy_id, session.session_id, current.generation);
+            upsertFrontierPending(db, policy.policy_id, sourceId, session, generation, current?.source_file_id ?? null);
+        }
+        // Terminally exclude only when we can prove the root is unapproved.
+        // Discovery absence is not proof (transient incomplete/missing files stay pending).
+        // Null cwd is deny-by-default → excluded.
+        for (const row of unfinishedFrontier(db, policy.policy_id)) {
+            const session = discoveredById.get(row.session_id);
+            if (session) {
+                if (session.cwd === null || (0, config_1.isUnderApprovedRoot)(roots, session.cwd) === null) {
+                    markFrontierExcluded(db, policy.policy_id, row.session_id, row.generation);
+                }
+                continue;
+            }
+            const persisted = db
+                .prepare(`SELECT sf.cwd
+             FROM backfill_frontier bf
+             JOIN source_files sf ON sf.id = bf.source_file_id
+            WHERE bf.policy_id = ? AND bf.session_id = ? AND bf.generation = ?`)
+                .get(policy.policy_id, row.session_id, row.generation);
+            if (persisted &&
+                (persisted.cwd === null || (0, config_1.isUnderApprovedRoot)(roots, persisted.cwd) === null)) {
+                markFrontierExcluded(db, policy.policy_id, row.session_id, row.generation);
+            }
+        }
+        // Supersede stale generations before selection so one session cannot consume the budget twice.
+        for (const row of unfinishedFrontier(db, policy.policy_id)) {
+            const current = currentGeneration(db, sourceId, row.session_id);
+            if (current)
+                supersedeOlderGenerations(db, policy.policy_id, row.session_id, current.generation);
+        }
+    });
+    if (options.shouldCancel?.()) {
+        const counts = frontierCounts(db, policy.policy_id);
+        return {
+            status: "ok",
+            skip_reason: null,
+            policy,
+            sessions_in_window: inWindowApproved.length,
+            sessions_selected: 0,
+            frontier_pending: counts.pending,
+            frontier_complete: counts.complete,
+            actionable_remaining: countActionableFrontier(db, policy.policy_id, discoveredById),
+            made_progress: counts.complete + counts.excluded > terminalBefore,
+            canceled: true,
+            scan: emptyScanSummary(sourceId),
+        };
+    }
+    options.onProgress?.();
+    // Select only currently discoverable pending sessions so a prefix of
+    // transiently missing rows cannot starve later actionable work. Missing
+    // rows stay pending for a future discovery refresh.
+    const unfinished = unfinishedFrontier(db, policy.policy_id);
+    const budget = sessionBudget();
+    const selected = [];
+    const seen = new Set();
+    for (const row of unfinished) {
+        if (seen.has(row.session_id))
+            continue;
+        seen.add(row.session_id);
+        if (!discoveredById.has(row.session_id))
+            continue;
+        selected.push(row.session_id);
+        if (selected.length >= budget)
+            break;
+    }
+    const scan = (0, scan_1.reconcile)(db, {
+        installationId: options.installationId,
+        leaseOwner: options.leaseOwner,
+        adapter,
+        mode: "backfill",
+        hintSessionIds: selected,
+        priority: "backfill",
+        shouldCancel: options.shouldCancel,
+        onProgress: options.onProgress,
+    });
+    if (options.shouldCancel?.()) {
+        const counts = frontierCounts(db, policy.policy_id);
+        return {
+            status: "ok",
+            skip_reason: null,
+            policy,
+            sessions_in_window: inWindowApproved.length,
+            sessions_selected: selected.length,
+            frontier_pending: counts.pending,
+            frontier_complete: counts.complete,
+            actionable_remaining: countActionableFrontier(db, policy.policy_id, discoveredById),
+            made_progress: scan.segments_enqueued > 0 || counts.complete + counts.excluded > terminalBefore,
+            canceled: true,
+            scan,
+        };
+    }
+    const processed = new Map(scan.processed_sessions.map((row) => [`${row.session_id}:${row.generation}`, row]));
+    (0, db_1.tx)(db, () => {
+        for (const sessionId of selected) {
+            const current = currentGeneration(db, sourceId, sessionId);
+            if (!current)
+                continue;
+            supersedeOlderGenerations(db, policy.policy_id, sessionId, current.generation);
+            const session = discovered.find((item) => item.session_id === sessionId);
+            if (session) {
+                upsertFrontierPending(db, policy.policy_id, sourceId, session, current.generation, current.source_file_id);
+            }
+            if (processed.has(`${sessionId}:${current.generation}`)) {
+                markFrontierComplete(db, policy.policy_id, sessionId, current.generation);
+            }
+        }
+    });
+    // Re-seed any still-in-window approved sessions that gained a new generation.
+    (0, db_1.tx)(db, () => {
+        for (const session of inWindowApproved) {
+            const current = currentGeneration(db, sourceId, session.session_id);
+            if (!current) {
+                upsertFrontierPending(db, policy.policy_id, sourceId, session, 1, null);
+                continue;
+            }
+            supersedeOlderGenerations(db, policy.policy_id, session.session_id, current.generation);
+            const frontier = db
+                .prepare("SELECT status FROM backfill_frontier WHERE policy_id = ? AND session_id = ? AND generation = ?")
+                .get(policy.policy_id, session.session_id, current.generation);
+            if (!frontier) {
+                upsertFrontierPending(db, policy.policy_id, sourceId, session, current.generation, current.source_file_id);
+            }
+        }
+    });
+    const finalPolicy = (0, db_1.tx)(db, () => maybeCompletePolicy(db, sourceId, readBackfillPolicy(db, sourceId) ?? policy));
+    const counts = frontierCounts(db, finalPolicy.policy_id);
+    const actionable = countActionableFrontier(db, finalPolicy.policy_id, discoveredById);
+    const madeProgress = scan.segments_enqueued > 0 || counts.complete + counts.excluded > terminalBefore;
+    return {
+        status: finalPolicy.status === "completed" ? "completed" : "ok",
+        skip_reason: null,
+        policy: finalPolicy,
+        sessions_in_window: inWindowApproved.length,
+        sessions_selected: selected.length,
+        frontier_pending: counts.pending,
+        frontier_complete: counts.complete,
+        actionable_remaining: actionable,
+        made_progress: madeProgress,
+        canceled: false,
+        scan,
+    };
+}
+/**
+ * CLI entry: mint/resume policy from `--since`, then run one local queue slice.
+ */
+function runBackfillStartPass(db, options) {
+    const adapter = options.adapter;
+    const policy = ensureBackfillPolicy(db, options.since, adapter);
+    const slice = runBackfillSlice(db, policy, options);
+    return {
+        status: slice.status === "completed" ? "completed" : "ok",
+        policy: slice.policy ?? policy,
+        sessions_in_window: slice.sessions_in_window,
+        sessions_selected: slice.sessions_selected,
+        frontier_pending: slice.frontier_pending,
+        frontier_complete: slice.frontier_complete,
+        scan: slice.scan,
+    };
+}
+/**
+ * Sync-worker continuation: continue an existing active policy only.
+ * Never calls `ensureBackfillPolicy` / never mints a new window.
+ */
+function runBackfillContinuePass(db, options) {
+    const adapter = options.adapter;
+    const policy = readBackfillPolicy(db, adapter.sourceId);
+    if (!policy || policy.status !== "active") {
+        return {
+            status: "skipped",
+            skip_reason: "no_active_policy",
+            policy: policy?.status === "completed" ? policy : null,
+            sessions_in_window: 0,
+            sessions_selected: 0,
+            frontier_pending: policy ? frontierCounts(db, policy.policy_id).pending : 0,
+            frontier_complete: policy ? frontierCounts(db, policy.policy_id).complete : 0,
+            actionable_remaining: 0,
+            made_progress: false,
+            canceled: false,
+            scan: emptyScanSummary(adapter.sourceId),
+        };
+    }
+    return runBackfillSlice(db, policy, { ...options, adapter });
+}
+function commandBackfillStart(options) {
+    if (!options.since) {
+        process.stderr.write("dreams backfill start requires --since <RFC3339>\n");
+        return 1;
+    }
+    const lock = (0, state_lock_1.acquireLocalStateLock)();
+    if (lock === null) {
+        if (options.json) {
+            console.log(JSON.stringify({ status: "busy", code: "local_state_busy", schema_version: 1 }));
+        }
+        else {
+            process.stderr.write("Another Dreams command is using local state. Try again after it finishes.\n");
+        }
+        return 1;
+    }
+    try {
+        const installation = (0, store_1.loadOrCreateInstallation)();
+        const db = (0, db_1.openDb)({
+            installationId: installation.installation_id,
+            installationCreatedAt: installation.created_at,
+        });
+        try {
+            const owner = (0, leases_1.acquireLease)(db, leases_1.SOURCE_LEASE);
+            if (owner === null) {
+                if (options.json)
+                    console.log(JSON.stringify({ status: "busy", code: "busy", schema_version: 1 }));
+                else
+                    process.stderr.write("Another dreams source operation holds the local lease.\n");
+                return 1;
+            }
+            let result;
+            try {
+                result = runBackfillStartPass(db, {
+                    installationId: installation.installation_id,
+                    leaseOwner: owner,
+                    since: options.since,
+                    adapter: (0, source_adapters_1.defaultSourceAdapter)(),
+                });
+            }
+            finally {
+                (0, leases_1.releaseLease)(db, leases_1.SOURCE_LEASE, owner);
+            }
+            const payload = {
+                schema_version: 1,
+                status: result.status,
+                policy: result.policy,
+                sessions_in_window: result.sessions_in_window,
+                sessions_selected: result.sessions_selected,
+                frontier_pending: result.frontier_pending,
+                frontier_complete: result.frontier_complete,
+                scan: result.scan,
+            };
+            if (options.json)
+                console.log(JSON.stringify(payload, null, 2));
+            else {
+                console.log([
+                    `Backfill ${result.status} for ${result.policy.since_at} → ${result.policy.until_at}`,
+                    "",
+                    `  Sessions in window: ${result.sessions_in_window}`,
+                    `  Sessions scanned:   ${result.sessions_selected}`,
+                    `  Frontier pending:   ${result.frontier_pending}`,
+                    `  Frontier complete:  ${result.frontier_complete}`,
+                    `  Segments enqueued:  ${result.scan.segments_enqueued}`,
+                    "",
+                    "Local queue only — wake sync to upload: dreams sync --force",
+                ].join("\n"));
+            }
+            return 0;
+        }
+        finally {
+            (0, db_1.closeDb)();
+        }
+    }
+    catch (error) {
+        if (error instanceof BackfillArgumentError || error instanceof BackfillPolicyConflictError) {
+            if (options.json) {
+                console.log(JSON.stringify({
+                    status: "error",
+                    schema_version: 1,
+                    code: error.code,
+                    message: error.message,
+                }));
+            }
+            else {
+                process.stderr.write(`${error.message}\n`);
+            }
+            return 1;
+        }
+        throw error;
+    }
+    finally {
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+    }
+}

package/dist/local/bindings.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Shared persistence for Cloud workspace/source bindings.
+ *
+ * Cloud is authoritative for lifecycle on register/re-register (LET-10231):
+ * create may set detected|active; re-register preserves lifecycle and returns
+ * the current status. Persist that remote status locally.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeRemoteSourceStatus = mergeRemoteSourceStatus;
+exports.persistSourceBindings = persistSourceBindings;
+const db_1 = require("./db");
+const leases_1 = require("./leases");
+/** Prefer Cloud's returned lifecycle; kept as a named helper for call sites/tests. */
+function mergeRemoteSourceStatus(_localStatus, remoteStatus) {
+    return remoteStatus;
+}
+function persistSourceBindings(db, localSourceId, registration, owner) {
+    const base = process.env.LETTA_BASE_URL || "https://api.letta.com";
+    return (0, db_1.tx)(db, () => {
+        (0, leases_1.assertLeaseHeld)(db, leases_1.SOURCE_LEASE, owner);
+        const existing = db.prepare("SELECT status FROM sources WHERE id = ?").get(localSourceId);
+        const status = mergeRemoteSourceStatus(existing?.status, registration.status);
+        db.prepare(`INSERT INTO workspace_bindings (id, api_base_url, workspace_id, organization_id, user_id, created_at, updated_at)
+       VALUES (1, ?, ?, NULL, NULL, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET api_base_url = excluded.api_base_url, workspace_id = excluded.workspace_id, updated_at = excluded.updated_at`).run(base, registration.workspaceId, (0, db_1.nowIso)(), (0, db_1.nowIso)());
+        db.prepare("UPDATE sources SET server_source_id = ?, status = ?, updated_at = ? WHERE id = ?").run(registration.serverSourceId, status, (0, db_1.nowIso)(), localSourceId);
+        return { status, serverSourceId: registration.serverSourceId, workspaceId: registration.workspaceId };
+    });
+}