cursedbelt 2.6.1 → 2.7.0

package/dist/server/sync/alarm.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 🔴 `error` joined on 2026-08-21, and it is the outcome that was MISSING.
+ *
+ * The console's subdomain cutover left the Mac's `STATION_SYNC_URL` pointing at
+ * a host that had become a 301; the dialer followed it into a Cloudflare Access
+ * login page and threw `Failed to parse JSON` every round. That is neither
+ * `paused` (nothing is version-skewed) nor `auth` (no token was refused) nor
+ * `unreachable` (the peer answered), so it recorded NOTHING — the timer logged
+ * `[sync] failed (ignored)` and the alarm's counter sat at zero while every
+ * mirrored report on prod froze for days, each still rendering a confident age.
+ *
+ * A sustained hard error is exactly as bad as a sustained pause and is now
+ * counted the same. `unreachable` remains the one outcome that neither counts
+ * nor resets, because the nightly EC2 sleep must never false-alarm.
+ */
+export type AlarmOutcome = "ok" | "paused" | "auth" | "error" | "unreachable";
+export interface SyncAlarmOptions {
+    /** Where the counter lives (survives restarts). */
+    statePath: string;
+    /** Rounds of paused/auth before raising (with the round cadence, pick so the
+     *  threshold lands around ~45 min of sustained pause). */
+    threshold?: number;
+    /** Re-raise cadence while the condition persists. Default 4h. */
+    reRaiseMs?: number;
+    /** Present the alarm. Default: macOS notification via osascript. */
+    notify?: (title: string, body: string) => void;
+    now?: () => number;
+    appName?: string;
+}
+export interface SyncAlarm {
+    /** Record one sync round's outcome; raises when the threshold crosses. */
+    record(outcome: AlarmOutcome, reason?: string): void;
+}
+export declare function createSyncAlarm(options: SyncAlarmOptions): SyncAlarm;
+//# sourceMappingURL=alarm.d.ts.map

package/dist/server/sync/alarm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm.d.ts","sourceRoot":"","sources":["../../../src/server/sync/alarm.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAgB9E,MAAM,WAAW,gBAAgB;IAChC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB;8DAC0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACzB,0EAA0E;IAC1E,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD;AAeD,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA4DpE"}

package/dist/server/sync/alarm.js

@@ -0,0 +1,92 @@
+/**
+ * Pause-alarm escalation — notes' `syncAlarm` generalized. A sync that is version-
+ * skew paused or auth-refused for a sustained stretch is a real problem the owner
+ * must hear about (the 2026-07-31 notes incident: prod ran stale code most of a day
+ * and only an owner eyeballing counts caught it). An UNREACHABLE peer neither counts
+ * nor resets — the nightly EC2 sleep must never false-alarm.
+ *
+ * State is a small JSON file so the alarm survives process restarts; the notifier is
+ * a seam (macOS `osascript` by default) so tests and non-Mac hosts inject their own.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const EMPTY = {
+    consecutiveBad: 0,
+    firstBadAt: null,
+    lastRaisedAt: null,
+    lastReason: null,
+};
+function defaultNotify(title, body) {
+    try {
+        const esc = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        Bun.spawnSync([
+            "osascript",
+            "-e",
+            `display notification "${esc(body)}" with title "${esc(title)}"`,
+        ]);
+    }
+    catch {
+        // A notifier must never take the loop down.
+    }
+}
+export function createSyncAlarm(options) {
+    const threshold = options.threshold ?? 9;
+    const reRaiseMs = options.reRaiseMs ?? 4 * 60 * 60_000;
+    const notify = options.notify ?? defaultNotify;
+    const now = options.now ?? Date.now;
+    const appName = options.appName ?? "sync";
+    const load = () => {
+        try {
+            if (!existsSync(options.statePath))
+                return { ...EMPTY };
+            return {
+                ...EMPTY,
+                ...JSON.parse(readFileSync(options.statePath, "utf8")),
+            };
+        }
+        catch {
+            return { ...EMPTY };
+        }
+    };
+    const save = (state) => {
+        try {
+            mkdirSync(dirname(options.statePath), { recursive: true });
+            writeFileSync(options.statePath, JSON.stringify(state));
+        }
+        catch {
+            // Losing the counter degrades to a later alarm, never to a crash.
+        }
+    };
+    return {
+        record(outcome, reason) {
+            const state = load();
+            if (outcome === "ok") {
+                save({ ...EMPTY });
+                return;
+            }
+            if (outcome === "unreachable")
+                return; // neither counts nor resets
+            state.consecutiveBad += 1;
+            state.lastReason = reason ?? outcome;
+            if (state.firstBadAt === null)
+                state.firstBadAt = now();
+            const due = state.consecutiveBad >= threshold &&
+                (state.lastRaisedAt === null || now() - state.lastRaisedAt >= reRaiseMs);
+            if (due) {
+                state.lastRaisedAt = now();
+                const since = state.firstBadAt
+                    ? new Date(state.firstBadAt).toLocaleTimeString()
+                    : "a while";
+                notify(outcome === "error" ? `${appName}: sync is FAILING` : `${appName}: sync is paused`, outcome === "auth"
+                    ? `The sync token is being refused (since ${since}). Re-link the peer.`
+                    : outcome === "error"
+                        ? // Names the real error, because this alarm's whole reason for
+                            // existing is that "failed (ignored)" was invisible.
+                            `Every sync round has failed since ${since}: ${state.lastReason}`
+                        : `Push has been paused on "${state.lastReason}" since ${since} — the peer likely needs a deploy.`);
+            }
+            save(state);
+        },
+    };
+}
+//# sourceMappingURL=alarm.js.map

package/dist/server/sync/alarm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alarm.js","sourceRoot":"","sources":["../../../src/server/sync/alarm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC,MAAM,KAAK,GAAe;IACzB,cAAc,EAAE,CAAC;IACjB,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;CAChB,CAAC;AAqBF,SAAS,aAAa,CAAC,KAAa,EAAE,IAAY;IACjD,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzE,GAAG,CAAC,SAAS,CAAC;YACb,WAAW;YACX,IAAI;YACJ,yBAAyB,GAAG,CAAC,IAAI,CAAC,iBAAiB,GAAG,CAAC,KAAK,CAAC,GAAG;SAChE,CAAC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACR,4CAA4C;IAC7C,CAAC;AACF,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAyB;IACxD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAE1C,MAAM,IAAI,GAAG,GAAe,EAAE;QAC7B,IAAI,CAAC;YACJ,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC;gBAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;YACxD,OAAO;gBACN,GAAG,KAAK;gBACR,GAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAyB;aAC/E,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;QACrB,CAAC;IACF,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,CAAC,KAAiB,EAAQ,EAAE;QACxC,IAAI,CAAC;YACJ,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,aAAa,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACR,kEAAkE;QACnE,CAAC;IACF,CAAC,CAAC;IAEF,OAAO;QACN,MAAM,CAAC,OAAO,EAAE,MAAM;YACrB,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC;YACrB,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACtB,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;gBACnB,OAAO;YACR,CAAC;YACD,IAAI,OAAO,KAAK,aAAa;gBAAE,OAAO,CAAC,4BAA4B;YACnE,KAAK,CAAC,cAAc,IAAI,CAAC,CAAC;YAC1B,KAAK,CAAC,UAAU,GAAG,MAAM,IAAI,OAAO,CAAC;YACrC,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI;gBAAE,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC;YACxD,MAAM,GAAG,GACR,KAAK,CAAC,cAAc,IAAI,SAAS;gBACjC,CAAC,KAAK,CAAC,YAAY,KAAK,IAAI,IAAI,GAAG,EAAE,GAAG,KAAK,CAAC,YAAY,IAAI,SAAS,CAAC,CAAC;YAC1E,IAAI,GAAG,EAAE,CAAC;gBACT,KAAK,CAAC,YAAY,GAAG,GAAG,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU;oBAC7B,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,kBAAkB,EAAE;oBACjD,CAAC,CAAC,SAAS,CAAC;gBACb,MAAM,CACL,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,mBAAmB,CAAC,CAAC,CAAC,GAAG,OAAO,kBAAkB,EAClF,OAAO,KAAK,MAAM;oBACjB,CAAC,CAAC,0CAA0C,KAAK,sBAAsB;oBACvE,CAAC,CAAC,OAAO,KAAK,OAAO;wBACpB,CAAC,CAAC,8DAA8D;4BAC/D,qDAAqD;4BACrD,qCAAqC,KAAK,KAAK,KAAK,CAAC,UAAU,EAAE;wBAClE,CAAC,CAAC,4BAA4B,KAAK,CAAC,UAAU,WAAW,KAAK,oCAAoC,CACpG,CAAC;YACH,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,CAAC;QACb,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/server/sync/commands.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The command relay — notes' ask-responder shape generalized: the internet-facing
+ * instance PARKS an action it cannot perform (it has no Mac powers), and the Mac's
+ * resident worker long-polls for it, executes locally, and posts the outcome back.
+ * The Mac dials OUT; the receiving instance never reaches into the house.
+ *
+ * Delivery is a held GET (default hold 25s) — remember the two fleet traps: the
+ * host server needs `idleTimeoutSeconds` ABOVE the hold (Bun's 10s default closed
+ * notes' 25s poll and nginx reported a bogus 502), and the routes must be mounted
+ * BEFORE any browser-session gate.
+ *
+ * A command left `claimed` past the stale window is reclaimable — a worker that
+ * died mid-execution must not strand the queue. Executors must therefore be
+ * idempotent or cheap to re-run.
+ */
+import type { Database } from "bun:sqlite";
+import { Hono } from "hono";
+export type CommandStatus = "queued" | "claimed" | "done" | "failed";
+export interface SyncCommand {
+    uid: string;
+    kind: string;
+    args: unknown;
+    status: CommandStatus;
+    requestedBy: string;
+    createdAt: number;
+    claimedAt: number | null;
+    claimedBy: string | null;
+    finishedAt: number | null;
+    result: unknown;
+    error: string | null;
+}
+export interface CommandQueue {
+    enqueue(kind: string, args: unknown, requestedBy: string): SyncCommand;
+    /** Atomically claim the oldest queued (or stale-claimed) command. */
+    claimNext(claimedBy: string, staleMs?: number): SyncCommand | null;
+    complete(uid: string, result: unknown): boolean;
+    fail(uid: string, error: string): boolean;
+    get(uid: string): SyncCommand | null;
+    list(limit?: number): SyncCommand[];
+    pendingCount(): number;
+}
+export declare function createCommandQueue(db: Database): CommandQueue;
+export declare const DEFAULT_HOLD_MS = 25000;
+export interface CommandRoutesOptions {
+    queue: CommandQueue;
+    verifyToken: (presented: string) => boolean;
+    /** Cap on the held poll. The HOST SERVER's idleTimeout must exceed this. */
+    maxHoldMs?: number;
+    pollStepMs?: number;
+}
+/** GET /pending (held) + POST /pending/:uid — the worker's two verbs. */
+export declare function createCommandReceiver(options: CommandRoutesOptions): Hono;
+export interface CommandRemote {
+    poll(worker: string, waitMs: number): Promise<SyncCommand | null>;
+    report(uid: string, outcome: {
+        ok: boolean;
+        result?: unknown;
+        error?: string;
+    }): Promise<void>;
+}
+export declare function createCommandRemote(options: {
+    basePath: string;
+    token: string;
+    fetchImpl?: typeof fetch;
+    /** Host-scoped extras for this peer — see `createHttpRemote`'s note. */
+    extraHeaders?: Record<string, string>;
+}): CommandRemote;
+export interface CommandWorkerDeps {
+    /** Re-read every cycle, like the sync timer's peer — null = not linked. */
+    resolveRemote: () => CommandRemote | null;
+    execute: (command: SyncCommand) => Promise<unknown>;
+    worker?: string;
+    holdMs?: number;
+    /** Idle gap between an empty poll and the next (on top of the hold). */
+    idleGapMs?: number;
+    backoffMaxMs?: number;
+    log?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+export interface CommandWorkerHandle {
+    stop(): void;
+}
+/** The resident long-poll → execute → report loop. Unreachable remote backs off to
+ *  `backoffMaxMs` and recovers silently — the nightly window rule. */
+export declare function startCommandWorker(deps: CommandWorkerDeps): CommandWorkerHandle;
+//# sourceMappingURL=commands.d.ts.map

package/dist/server/sync/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../src/server/sync/commands.ts"],"names":[],"mappings":"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"}

package/dist/server/sync/commands.js

@@ -0,0 +1,242 @@
+import { randomUUID } from "node:crypto";
+import { Hono } from "hono";
+const STALE_CLAIM_MS = 5 * 60_000;
+const toCommand = (r) => ({
+    uid: r.uid,
+    kind: r.kind,
+    args: JSON.parse(r.args),
+    status: r.status,
+    requestedBy: r.requested_by,
+    createdAt: r.created_at,
+    claimedAt: r.claimed_at,
+    claimedBy: r.claimed_by,
+    finishedAt: r.finished_at,
+    result: r.result === null ? null : JSON.parse(r.result),
+    error: r.error,
+});
+export function createCommandQueue(db) {
+    db.exec(`
+		CREATE TABLE IF NOT EXISTS sync_commands (
+			uid TEXT PRIMARY KEY,
+			kind TEXT NOT NULL,
+			args TEXT NOT NULL,
+			status TEXT NOT NULL DEFAULT 'queued',
+			requested_by TEXT NOT NULL,
+			created_at INTEGER NOT NULL,
+			claimed_at INTEGER,
+			claimed_by TEXT,
+			finished_at INTEGER,
+			result TEXT,
+			error TEXT
+		);
+		CREATE INDEX IF NOT EXISTS idx_sync_commands_status ON sync_commands(status, created_at);
+	`);
+    const insert = db.prepare("INSERT INTO sync_commands (uid, kind, args, status, requested_by, created_at) VALUES (?, ?, ?, 'queued', ?, ?)");
+    const getStmt = db.prepare("SELECT * FROM sync_commands WHERE uid = ?");
+    const listStmt = db.prepare("SELECT * FROM sync_commands ORDER BY created_at DESC LIMIT ?");
+    const pendingStmt = db.prepare("SELECT COUNT(*) AS n FROM sync_commands WHERE status IN ('queued','claimed')");
+    // The atomic claim: one UPDATE whose WHERE picks the oldest eligible row. sqlite
+    // serializes writers, so two workers can never claim the same row.
+    const claimStmt = db.prepare(`
+		UPDATE sync_commands SET status = 'claimed', claimed_at = ?, claimed_by = ?
+		WHERE uid = (
+			SELECT uid FROM sync_commands
+			WHERE status = 'queued' OR (status = 'claimed' AND claimed_at < ?)
+			ORDER BY created_at ASC LIMIT 1
+		)
+		RETURNING *
+	`);
+    const finishStmt = db.prepare("UPDATE sync_commands SET status = ?, finished_at = ?, result = ?, error = ? WHERE uid = ? AND status IN ('queued','claimed')");
+    return {
+        enqueue(kind, args, requestedBy) {
+            const uid = `cmd-${randomUUID().slice(0, 18)}`;
+            insert.run(uid, kind, JSON.stringify(args ?? null), requestedBy, Date.now());
+            return toCommand(getStmt.get(uid));
+        },
+        claimNext(claimedBy, staleMs = STALE_CLAIM_MS) {
+            const now = Date.now();
+            const row = claimStmt.get(now, claimedBy, now - staleMs);
+            return row ? toCommand(row) : null;
+        },
+        complete: (uid, result) => finishStmt.run("done", Date.now(), JSON.stringify(result ?? null), null, uid).changes > 0,
+        fail: (uid, error) => finishStmt.run("failed", Date.now(), null, error, uid).changes > 0,
+        get: (uid) => {
+            const row = getStmt.get(uid);
+            return row ? toCommand(row) : null;
+        },
+        list: (limit = 100) => listStmt.all(limit).map(toCommand),
+        pendingCount: () => pendingStmt.get().n,
+    };
+}
+// ── the receiver routes (mount beside the sync receiver, same token gate) ────────
+const noStore = { "cache-control": "no-store" };
+export const DEFAULT_HOLD_MS = 25_000;
+/** GET /pending (held) + POST /pending/:uid — the worker's two verbs. */
+export function createCommandReceiver(options) {
+    const maxHold = options.maxHoldMs ?? DEFAULT_HOLD_MS;
+    const step = options.pollStepMs ?? 1_000;
+    const api = new Hono();
+    api.use("*", async (c, next) => {
+        const header = c.req.header("authorization") ?? "";
+        const presented = header.startsWith("Bearer ") ? header.slice(7) : "";
+        if (presented.length === 0 || !options.verifyToken(presented)) {
+            return c.json({ error: "unauthorized" }, 401, noStore);
+        }
+        await next();
+    });
+    api.get("/pending", async (c) => {
+        const worker = c.req.query("worker") ?? "worker";
+        const waitRaw = c.req.query("wait");
+        const wait = Math.min(maxHold, waitRaw !== undefined && /^\d+$/.test(waitRaw) ? Number(waitRaw) : maxHold);
+        const deadline = Date.now() + wait;
+        for (;;) {
+            const command = options.queue.claimNext(worker);
+            if (command)
+                return c.json({ command }, 200, noStore);
+            if (Date.now() >= deadline)
+                return c.json({ command: null }, 200, noStore);
+            await new Promise((resolve) => setTimeout(resolve, Math.min(step, Math.max(1, deadline - Date.now()))));
+        }
+    });
+    api.post("/pending/:uid", async (c) => {
+        const uid = c.req.param("uid");
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: "bad_request" }, 400, noStore);
+        }
+        const { ok, result, error } = (body ?? {});
+        if (typeof ok !== "boolean")
+            return c.json({ error: "bad_request" }, 400, noStore);
+        const changed = ok
+            ? options.queue.complete(uid, result ?? null)
+            : options.queue.fail(uid, typeof error === "string" ? error : "failed");
+        if (!changed)
+            return c.json({ error: "not_found" }, 404, noStore);
+        return c.json({ ok: true }, 200, noStore);
+    });
+    return api;
+}
+export function createCommandRemote(options) {
+    const base = options.basePath.replace(/\/$/, "");
+    const doFetch = options.fetchImpl ?? fetch;
+    const headers = (extra) => ({
+        authorization: `Bearer ${options.token}`,
+        ...(options.extraHeaders ?? {}),
+        ...(extra ?? {}),
+    });
+    /** 🔴 `redirect: "manual"`, for the reason in `http.ts`'s header: the relay
+     *  travels the same road as the sync, so a moved peer hostname must fail here
+     *  with the destination in the message rather than silently landing on a
+     *  Cloudflare Access login page and reporting a JSON parse error. */
+    const refuseRedirect = (r, path) => {
+        if (r.status >= 300 && r.status < 400)
+            throw new Error(`${path}: ${r.status} — the peer address redirects to ` +
+                `${r.headers.get("location") ?? "an unnamed destination"}; the relay URL points at a host that has moved.`);
+    };
+    return {
+        async poll(worker, waitMs) {
+            const r = await doFetch(`${base}/pending?worker=${encodeURIComponent(worker)}&wait=${waitMs}`, {
+                headers: headers(),
+                redirect: "manual",
+                // The abort budget must clear the hold plus network slack.
+                signal: AbortSignal.timeout(waitMs + 15_000),
+            });
+            refuseRedirect(r, "commands/pending");
+            if (!r.ok)
+                throw new Error(`commands/pending: ${r.status}`);
+            const body = (await r.json());
+            return body.command;
+        },
+        async report(uid, outcome) {
+            const r = await doFetch(`${base}/pending/${encodeURIComponent(uid)}`, {
+                method: "POST",
+                headers: headers({ "content-type": "application/json" }),
+                redirect: "manual",
+                body: JSON.stringify(outcome),
+                signal: AbortSignal.timeout(30_000),
+            });
+            refuseRedirect(r, "commands/report");
+            if (!r.ok)
+                throw new Error(`commands/report: ${r.status}`);
+        },
+    };
+}
+/** The resident long-poll → execute → report loop. Unreachable remote backs off to
+ *  `backoffMaxMs` and recovers silently — the nightly window rule. */
+export function startCommandWorker(deps) {
+    const worker = deps.worker ?? "mac";
+    const holdMs = deps.holdMs ?? DEFAULT_HOLD_MS;
+    const idleGapMs = deps.idleGapMs ?? 1_000;
+    const backoffMax = deps.backoffMaxMs ?? 10 * 60_000;
+    const log = deps.log ?? ((m) => console.log(m));
+    const warn = deps.warn ?? ((m) => console.error(m));
+    const setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h));
+    let stopped = false;
+    let handle = null;
+    let failures = 0;
+    let reportedUnreachable = false;
+    const schedule = (ms) => {
+        if (stopped)
+            return;
+        if (handle !== null)
+            clearTimer(handle);
+        handle = setTimer(cycle, ms);
+        handle?.unref?.();
+    };
+    const cycle = () => {
+        if (stopped)
+            return;
+        const remote = deps.resolveRemote();
+        if (remote === null) {
+            schedule(60_000);
+            return;
+        }
+        void remote
+            .poll(worker, holdMs)
+            .then(async (command) => {
+            failures = 0;
+            reportedUnreachable = false;
+            if (command === null)
+                return;
+            log(`[commands] executing ${command.kind} (${command.uid})`);
+            try {
+                const result = await deps.execute(command);
+                await remote.report(command.uid, { ok: true, result });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                warn(`[commands] ${command.kind} failed: ${message}`);
+                // Best-effort: a failed report leaves the row claimed; the stale-claim
+                // window re-serves it, which is why executors must tolerate a re-run.
+                await remote.report(command.uid, { ok: false, error: message }).catch(() => { });
+            }
+        })
+            .then(() => {
+            if (!stopped)
+                schedule(idleGapMs);
+        })
+            .catch((err) => {
+            failures += 1;
+            const wait = Math.min(backoffMax, 5_000 * 2 ** Math.min(failures - 1, 7));
+            if (!reportedUnreachable) {
+                const message = err instanceof Error ? err.message : String(err);
+                log(`[commands] remote unreachable (${message}) — backing off. This is normal offline.`);
+                reportedUnreachable = true;
+            }
+            schedule(wait);
+        });
+    };
+    schedule(1_000);
+    return {
+        stop: () => {
+            stopped = true;
+            if (handle !== null)
+                clearTimer(handle);
+        },
+    };
+}
+//# sourceMappingURL=commands.js.map

package/dist/server/sync/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../../src/server/sync/commands.ts"],"names":[],"mappings":"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"}

package/dist/server/sync/engine.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The dialer half (push-then-pull) and the batch applier. Pure over {@link RemoteApi}
+ * and {@link OpLog} so tests drive two REAL stores through the real receiver — no
+ * HTTP mocks (the notes/vault discipline).
+ *
+ * Push-before-pull is load-bearing: the push cursor must be current before the pull
+ * computes concurrency, so exactly ONE side materializes any given conflict artifact
+ * (vault's rule). Cursors advance only past durably-processed ops; a stopped batch
+ * advances exactly to the failure and the next run resumes there.
+ *
+ * Version skew (notes' hardest-won lesson): the peer's `/info` advertises `opKinds`;
+ * the push stops BEFORE the first op the peer cannot take and reports `blockedBy`
+ * instead of wedging with an error that reads like corruption. Nothing is dropped —
+ * the moment the peer is upgraded, the next push resumes from exactly that op.
+ */
+import type { OpLog } from "./opLog";
+import { type ApplyContext, type ApplyOne, type ApplyReport, type PeerInfo, type RemoteApi, type SyncOp, type SyncSummary } from "./types";
+/** Kit-owned dedupe + ledger insert around the app's per-op merge logic. Everything
+ *  for one op happens in one transaction: state change AND ledger insert, so a crash
+ *  can never apply without recording (double-apply) or record without applying
+ *  (silent drop). */
+export declare function createSyncApplier(log: OpLog, applyOne: ApplyOne): (ops: SyncOp[], ctx: ApplyContext) => ApplyReport;
+/** Hold back ops the far side must never see (vault values, local-only kinds).
+ *  Return null to hold; return a (possibly redacted) op to send. */
+export type ExportPolicy = (op: SyncOp) => SyncOp | null;
+/**
+ * A refusal the peer's `opKinds` cannot express — the SAME "stop before it, never drop
+ * it" contract, one layer deeper. Return a reason to block, or null to send.
+ *
+ * The kind check answers "can the peer take this SHAPE". It is not always the whole
+ * compatibility surface: notes negotiates `meta.set` a second time on the KEY, because
+ * `meta.set` has been a known kind since the log existed, so a NEW key rides a kind the
+ * peer recognizes and fails one layer deeper — as a skip on the receiver that looks like
+ * a delivered op, or, against a build predating that skip, as a wedged push.
+ *
+ * 🔴 This is deliberately NOT the {@link ExportPolicy}. A policy HOLDS an op back
+ * forever (the far side must never see it); a refusal PAUSES in front of it and keeps
+ * the cursor there, so the moment the peer is upgraded the next run resumes from exactly
+ * that op. Expressing "the peer is too old for this" as a hold would silently lose the
+ * mutation.
+ */
+export type PeerRefusal = (op: SyncOp, info: PeerInfo) => string | null;
+export interface EngineOptions {
+    log: OpLog;
+    /** The op kinds THIS build understands — advertised via /info and used to stop a
+     *  push into an older peer before the first op it cannot take. */
+    opKinds: readonly string[];
+    policy?: ExportPolicy;
+    /** Optional second compatibility check, finer than `opKinds`. See {@link PeerRefusal}. */
+    peerRefusal?: PeerRefusal;
+    /** Byte budget per push request (default ~1 MiB). A backlog of large ops is
+     *  sent as several requests instead of one that trips the proxy's body cap —
+     *  the 413 WEDGES otherwise: the batch never shrinks, the cursor never moves.
+     *  A single op larger than the budget still goes alone. */
+    maxPushBytes?: number;
+}
+/** Split ops into request-sized chunks by serialized payload weight. */
+export declare function chunkByBytes(ops: SyncOp[], maxBytes: number): SyncOp[][];
+export declare function pushToRemote(opts: EngineOptions, remote: RemoteApi): Promise<Pick<SyncSummary, "remoteId" | "pushed" | "held" | "conflicts" | "blockedBy">>;
+export declare function pullFromRemote(opts: EngineOptions, remote: RemoteApi, applyBatch: (ops: SyncOp[], ctx: ApplyContext) => ApplyReport): Promise<Pick<SyncSummary, "remoteId" | "pulled" | "conflicts">>;
+/** One full reconciliation: push, then pull. */
+export declare function runSync(opts: EngineOptions, remote: RemoteApi, applyBatch: (ops: SyncOp[], ctx: ApplyContext) => ApplyReport): Promise<SyncSummary>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/server/sync/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/server/sync/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,SAAS,EAEd,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,MAAM,SAAS,CAAC;AAIjB;;;qBAGqB;AACrB,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,IACvD,KAAK,MAAM,EAAE,EAAE,KAAK,YAAY,KAAG,WAAW,CAkCtD;AAED;oEACoE;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,KAAK,MAAM,GAAG,IAAI,CAAC;AAExE,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,KAAK,CAAC;IACX;sEACkE;IAClE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;+DAG2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAgBxE;AAED,wBAAsB,YAAY,CACjC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC,CA+ExF;AAED,wBAAsB,cAAc,CACnC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,YAAY,KAAK,WAAW,GAC3D,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC,CAAC,CA2BjE;AAED,gDAAgD;AAChD,wBAAsB,OAAO,CAC5B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,YAAY,KAAK,WAAW,GAC3D,OAAO,CAAC,WAAW,CAAC,CAItB"}