cursedbelt-server 1.0.0

package/src/server/storage/videoDerivativeKeys.ts

@@ -0,0 +1,172 @@
+/**
+ * ── The NAMES of every video derivative binary-server writes ────────────────────────────
+ *
+ * A derivative's key is COMPUTED from its source's, never bookkept. A consumer finds one by
+ * deriving the name and asking `/meta` whether it exists yet, so there is no webhook, no job
+ * id, no schema column and nothing to reconcile: the absence of the object IS the "not ready
+ * yet" state, and it answers itself.
+ *
+ * ── 🔴 Why these live in cursedbelt ─────────────────────────────────────────────────────
+ * Owner, 2026-08-14: *"Make it in cb because many apps may move to cloudflare and share the
+ * logic."* This contract is the seam between three repos that must never disagree —
+ * binary-server WRITES these names, `@satellites/satellite-kit` re-exports them for the
+ * satellite apps, and cursedbelt's own `binaryServerStore` mints the tokens that authorize
+ * them. A second hand-typed `${key}.web.mp4` anywhere in that triangle is a silent
+ * no-preview the day binary-server renames anything, and that has already happened once:
+ * `apps/collections` had the contract and `apps/family` shipped video without it, so family
+ * had no faststart stream, no scrub previews and no processing state at all.
+ *
+ * 🔴 What is shared here is the STRATEGY, never the media. Nothing in this module can resolve
+ * a stored object — every function is a pure string transform over a key the caller already
+ * holds. Each app is its own binary-server tenant with its own signing key, so family cannot
+ * reach a collections object through anything here, and that must stay true.
+ *
+ * ── 🔴 This is NOT the `fs*` keyspace in `./types.ts`, and they must not be merged ───────
+ * `fsHlsMasterKey(owner, id)` → `hls/<owner>/<id>/master.m3u8` and its siblings address the
+ * FileCatalogue: a caller that holds an owner and an item id, whose derivatives live in their
+ * own top-level namespaces. This module addresses a caller that holds a binary-server KEY and
+ * derives sibling names from it, which is what makes "ask /meta for a name you computed" work
+ * with no catalogue at all.
+ *
+ * Two consumers, two shapes, both correct:
+ *   · `fs*` — cursedbelt's own FileCatalogue / the `library` transcode strategy.
+ *   · this module — binary-server's derivative convention, used by the satellite apps.
+ *
+ * Collapsing either into the other renames objects that already exist in the store, and a
+ * renamed derivative is indistinguishable from an unbuilt one (absence is the "not ready"
+ * state) — so the visible result is every video in the fleet losing its previews at once,
+ * silently, with the rebuild costing hours of ffmpeg.
+ */
+
+/**
+ * The browser-playable remux: the same pictures with the index at the front.
+ *
+ * A phone MP4/MOV stores its `moov` index at the END, and a browser cannot decode frame one
+ * until it has that index — so it downloads the whole file first. Measured on the owner's
+ * 90,339,606-byte upload (2026-08-13): the index began at byte 90,305,514, 99.96% of the way
+ * in. That is the "videos stay on a spinner for minutes" report, and no amount of Range
+ * support, caching or edge tuning fixes it. A `+faststart` remux is a STREAM COPY for
+ * h264+aac sources, which is what phones produce: no re-encode, nothing lost.
+ */
+/**
+ * ── 🔴 THE ENCODER GENERATION IN THE NAME (2026-09-09) ──────────────────────────────────
+ *
+ * binary-server rebuilds every video derivative when its encoder improves, and a rebuild
+ * used to write **the same filename with different bytes**. That silently cancels out an
+ * `immutable` cache lifetime — a browser told `immutable` never re-checks, for a year, and
+ * **that cannot be revoked for a copy already on somebody's phone**. So the owner's decision
+ * (A, 2026-09-09) is that new bytes get a new address: `clip.web.mp4` → `clip.g2.web.mp4`.
+ *
+ * 🔴 **Generation 1 is UNTAGGED and always will be.** Every derivative in the store today is
+ * at the untagged name; tagging generation 1 would orphan all of them and re-encode the
+ * whole library for byte-identical output. Untagged is not a legacy case — it IS generation
+ * one.
+ *
+ * 🔴 **This constant must match binary-server's `VIDEO_ENCODER_GENERATION`**
+ * (`src/media/encoderGeneration.ts`). They are in different repos and neither can import the
+ * other, so binary-server carries a test that goes RED the moment somebody bumps its number,
+ * naming this file. If you are here because of that test: bump this in the same commit, and
+ * remember that `notes`, `collections` and `family` all reach these names through
+ * `@satellites/satellite-kit/video-derivatives`. Getting it wrong is not an error anywhere —
+ * it is a 404 that reads as "no preview available", on every video.
+ */
+export const VIDEO_KEY_GENERATION = 1;
+
+/** The generation tag a derivative's name carries. Empty for generation 1 — see above. */
+export const videoGenerationTag = (generation: number = VIDEO_KEY_GENERATION): string =>
+	generation <= 1 ? "" : `.g${generation}`;
+
+export const webPlayableKeyFor = (
+	key: string,
+	generation: number = VIDEO_KEY_GENERATION,
+): string => `${key}${videoGenerationTag(generation)}.web.mp4`;
+
+/** The scrub-preview sprite sheet — tiled frames from across the clip, as one JPEG. */
+export const spriteKeyFor = (key: string): string => `${key}.sprite.jpg`;
+
+/** The WebVTT mapping a playhead position onto a tile of {@link spriteKeyFor}. */
+export const spriteVttKeyFor = (key: string): string => `${key}.sprite.vtt`;
+
+/**
+ * The single still a gallery draws on a tile.
+ *
+ * Deliberately the SAME name a still photograph's thumbnail gets, so a consumer has one rule
+ * — *the tile for anything is `<key>.thumb.jpg`, and its absence means not ready* — rather
+ * than one rule per media kind. The sprite sheet is not a substitute: it is a GRID, so drawing
+ * it on a tile shows a contact sheet, and using one cell means every consumer carries the
+ * VTT's geometry in order to crop it.
+ */
+export const posterKeyFor = (key: string): string => `${key}.thumb.jpg`;
+
+/**
+ * ── The HLS tree: `<key>.hls/` ──────────────────────────────────────────────────────────
+ *
+ * 🔴 ONE container, and the trailing name is load-bearing. binary-server's `storage.ts`
+ * co-locates a container's whole subtree under a single shard and `removeContainer()` wipes it
+ * atomically — so a ladder that is one container is deleted, migrated and reconciled as one
+ * thing. Segments scattered under sibling keys would be none of those, and orphaning half a
+ * ladder is worse than having none: the master would keep advertising rungs whose segments
+ * 404, which a player retries rather than falls back from.
+ *
+ * 🔴 Why HLS at all, now that Range works. The Range bug (an edge Worker answering 200 + the
+ * whole 209 MB to a ranged read) was fixed 2026-08-14 and is NOT what this is for. A single
+ * progressive MP4, however well served, cannot ADAPT: a weak cell connection stalls on a
+ * 23 Mbps master instead of dropping to a lower rung. Each segment is also a small object that
+ * caches WHOLE at the edge, which sidesteps both the 512 MiB single-entry ceiling and the
+ * segment-assembly machinery that exists to work around it for big films.
+ */
+export const hlsPrefixFor = (
+	key: string,
+	generation: number = VIDEO_KEY_GENERATION,
+): string => `${key}${videoGenerationTag(generation)}.hls/`;
+
+/**
+ * The playlist a player is pointed at — the one object whose presence means "the ladder is
+ * ready". It is written LAST, after every rung, so a consumer that finds it can trust that
+ * what it names exists. Absence is normal and means "play the faststart remux".
+ */
+export const hlsMasterKeyFor = (
+	key: string,
+	generation: number = VIDEO_KEY_GENERATION,
+): string => `${hlsPrefixFor(key, generation)}master.m3u8`;
+
+/**
+ * Every derivative suffix, for the "is this key itself a derivative" question.
+ *
+ * 🔴 Load-bearing in three directions, each of which has already cost something:
+ *  1. A derivative must never become the source of another, or a sweep builds
+ *     `clip.web.mp4.web.mp4` and then `…web.mp4.web.mp4.web.mp4`, forever.
+ *  2. A sweep must not count a derivative as work still owed, or the backlog is permanently
+ *     non-empty and ffmpeg re-runs on every pass.
+ *  3. A duplicate scan must not propose a file against its own derivative. They share a title
+ *     by construction, so every video would pair with its own remux and a review queue would
+ *     contain nothing else.
+ */
+export const DERIVATIVE_SUFFIXES = [
+	".web.mp4",
+	".sprite.jpg",
+	".sprite.vtt",
+	".thumb.jpg",
+	".web.jpg",
+] as const;
+
+/**
+ * Is this key something binary-server DERIVED rather than something a person uploaded?
+ *
+ * The HLS tree is matched by its container segment rather than a suffix, because every object
+ * inside it (`master.m3u8`, `720/index.m3u8`, `720/000.ts`) is a derivative and none of them
+ * ends in a name from the list above.
+ */
+const DERIVATIVE_RE = new RegExp(
+	// 🔴 The optional `.g<N>` is the encoder generation a video derivative's name carries
+	// (see VIDEO_KEY_GENERATION above). Without it, `clip.g2.web.mp4` reads as a SOURCE — and
+	// then a sweep derives `clip.g2.web.mp4.web.mp4` from it, for ever. Built from the suffix
+	// list rather than written out, so the two cannot drift apart.
+	`(?:\\.g\\d+)?(?:${DERIVATIVE_SUFFIXES.map((x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})$`,
+);
+
+export const isDerivativeKey = (key: string): boolean =>
+	DERIVATIVE_RE.test(key) ||
+	key.includes(".hls/") ||
+	/-thumb\.(jpg|webp|png)$/.test(key) ||
+	/\.shot\.\d+\.jpg$/.test(key);

package/src/server/storage/videoProcessor.posterOnly.spec.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { isFfmpegAvailable } from '../media-bun';
+import { createDiskStore } from './diskStore';
+import { fsHlsMasterKey, fsPosterKey, fsSourceKey } from './types';
+import { processVideo } from './videoProcessor';
+
+const haveFfmpeg = await isFfmpegAvailable();
+
+/** Synthesize a short test clip with ffmpeg's lavfi sources. */
+async function makeSource(dest: string, duration = 2): Promise<void> {
+  const proc = Bun.spawn(
+    [
+      'ffmpeg',
+      '-hide_banner',
+      '-y',
+      '-f',
+      'lavfi',
+      '-i',
+      `testsrc=duration=${duration}:size=320x240:rate=15`,
+      '-pix_fmt',
+      'yuv420p',
+      '-c:v',
+      'libx264',
+      dest,
+    ],
+    { stdout: 'ignore', stderr: 'ignore' },
+  );
+  await proc.exited;
+  if (proc.exitCode !== 0) throw new Error('failed to synthesize test clip');
+}
+
+// posterOnly is the memory-constrained-host path: a poster + duration, but NO heavy HLS/re-encode.
+// SKIPPED on a host without ffmpeg/ffprobe — it synthesizes and decodes real media. Runs by default wherever ffmpeg is installed.
+describe.skipIf(!haveFfmpeg)('processVideo posterOnly', () => {
+  test('extracts a poster + duration, ready, no HLS', async () => {
+    const root = await mkdtemp(path.join(tmpdir(), 'cb-poster-only-'));
+    try {
+      const store = createDiskStore(root);
+      const owner = 'u1';
+      const id = 'v1';
+      const srcLocal = path.join(root, 'in.mp4');
+      await makeSource(srcLocal);
+      await store.put(
+        fsSourceKey(owner, id),
+        new Uint8Array(await Bun.file(srcLocal).arrayBuffer()),
+        'video/mp4',
+      );
+
+      const res = await processVideo({
+        store,
+        workDir: path.join(root, 'work'),
+        owner,
+        id,
+        sourceKey: fsSourceKey(owner, id),
+        posterOnly: true,
+      });
+
+      expect(res.status).toBe('ready');
+      expect(res.hasPoster).toBe(true);
+      expect(res.hasHls).toBe(false);
+      expect(res.hasSprite).toBe(false);
+      expect(res.durationSeconds).toBeGreaterThan(1);
+      // Poster is uploaded; the HLS master never is.
+      expect(await store.stat(fsPosterKey(owner, id))).not.toBeNull();
+      expect(await store.stat(fsHlsMasterKey(owner, id))).toBeNull();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  // Regression: a sub-1s clip (the 2026-07-04 prod `0:00` .mov) — the fixed `-ss 1` seek landed
+  // past EOF and produced no poster. extractPoster must clamp the seek / fall back to frame 0.
+  test('still extracts a poster for a very short (<1s) clip', async () => {
+    const root = await mkdtemp(path.join(tmpdir(), 'cb-poster-short-'));
+    try {
+      const store = createDiskStore(root);
+      const owner = 'u1';
+      const id = 'short1';
+      const srcLocal = path.join(root, 'in.mp4');
+      await makeSource(srcLocal, 0.5);
+      await store.put(
+        fsSourceKey(owner, id),
+        new Uint8Array(await Bun.file(srcLocal).arrayBuffer()),
+        'video/mp4',
+      );
+
+      const res = await processVideo({
+        store,
+        workDir: path.join(root, 'work'),
+        owner,
+        id,
+        sourceKey: fsSourceKey(owner, id),
+        posterOnly: true,
+      });
+
+      expect(res.status).toBe('ready');
+      expect(res.hasPoster).toBe(true);
+      expect(await store.stat(fsPosterKey(owner, id))).not.toBeNull();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/server/storage/videoProcessor.ts

@@ -0,0 +1,229 @@
+import { mkdir, readdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+import {
+  buildSpriteVtt,
+  canStreamCopy,
+  faststartArgs,
+  hlsLadderArgs,
+  isFfmpegAvailable,
+  LIBRARY_CRF,
+  planSprite,
+  posterArgs,
+  probeVideoStream,
+  resolveLadder,
+  runFfmpegProgress,
+  spriteArgs,
+} from '../media-bun';
+import {
+  fsHlsFileKey,
+  fsHlsMasterKey,
+  fsMp4Key,
+  fsPosterKey,
+  fsSpriteKey,
+  fsVttKey,
+  type MediaStore,
+} from './types';
+
+// Ingest→derivatives orchestrator: the store-aware glue on top of `server/media` (media-bun),
+// which owns the argv/codec work but nothing about *where bytes live*. Transcodes a raw upload
+// into web-safe derivatives (faststart MP4 fallback + HLS ladder + poster + sprite/VTT), uploads
+// each into the MediaStore, and reports progress. Best-effort: if ffmpeg is unavailable it marks
+// the video ready and lets it play raw (progressive Range).
+
+export type ProcessProgress = (status: ProcessingStatus, pct: number) => void;
+
+export type ProcessResult = {
+  status: ProcessingStatus;
+  durationSeconds: number;
+  hasHls: boolean;
+  hasSprite: boolean;
+  hasPoster: boolean;
+};
+
+export type ProcessOptions = {
+  store: MediaStore;
+  /** Scratch directory for ffmpeg inputs/outputs (cleaned up afterwards). */
+  workDir: string;
+  owner: string;
+  id: string;
+  /** Storage key of the already-persisted raw source. */
+  sourceKey: string;
+  /** HLS rung heights to attempt (clamped to the source height; never upscaled). */
+  ladderHeights?: number[];
+  /**
+   * Poster-only mode for memory-constrained hosts: probe duration + extract a single-frame
+   * poster (cheap, ~tens of MB peak) and skip the heavy re-encode/HLS/sprite work that OOM'd
+   * the 1GB prod box (2026-07-04). The raw source still plays progressively; this only buys a
+   * grid thumbnail + duration. Best-effort — a failed poster still lands the row `ready`.
+   */
+  posterOnly?: boolean;
+  onProgress?: ProcessProgress;
+};
+
+// Stream a produced local file into the store under `key` (no full heap copy).
+async function uploadFile(store: MediaStore, localPath: string, key: string, mime: string) {
+  const file = Bun.file(localPath);
+  if (!(await file.exists())) return;
+  await store.putStream(key, file.stream(), mime, { contentLength: file.size });
+}
+
+// Recursively upload an HLS output tree (master.m3u8 + <height>/playlist.m3u8 + segments).
+async function uploadHlsTree(store: MediaStore, dir: string, owner: string, id: string) {
+  const walk = async (rel: string): Promise<void> => {
+    const entries = await readdir(path.join(dir, rel), { withFileTypes: true });
+    for (const e of entries) {
+      const childRel = rel ? path.join(rel, e.name) : e.name;
+      if (e.isDirectory()) {
+        await walk(childRel);
+      } else {
+        const mime = e.name.endsWith('.m3u8') ? 'application/vnd.apple.mpegurl' : 'video/mp2t';
+        await uploadFile(store, path.join(dir, childRel), fsHlsFileKey(owner, id, childRel), mime);
+      }
+    }
+  };
+  await walk('');
+}
+
+// Extract a single JPEG poster, robust to very short clips: seek ~1s in to skip black intros, but
+// clamp the seek inside a short clip and fall back to frame 0 if the seek lands past EOF (which
+// otherwise decodes no frame and silently produces no poster — the 2026-07-04 `0:00` .mov case).
+async function extractPoster(
+  inPath: string,
+  outPath: string,
+  durationSeconds: number,
+): Promise<boolean> {
+  let stderrTail = '';
+  const onError = (tail: string) => {
+    stderrTail = tail;
+  };
+  const at = durationSeconds > 1.2 ? 1 : 0;
+  if (await runFfmpegProgress(posterArgs(inPath, outPath, at), 0, undefined, onError)) return true;
+  if (at !== 0 && (await runFfmpegProgress(posterArgs(inPath, outPath, 0), 0, undefined, onError)))
+    return true;
+  // Real poster failures AND the malformed/short-clip fixtures test suites deliberately
+  // feed ffmpeg land here — stderr alone can't tell them apart, so the message is tagged
+  // `[expected-in-tests]` (grep-filterable) instead of silenced, so a real prod
+  // regression still surfaces.
+  console.warn(
+    `[videoProcessor][expected-in-tests] poster extraction failed (duration=${durationSeconds}s): ${stderrTail.slice(-400)}`,
+  );
+  return false;
+}
+
+export async function processVideo(opts: ProcessOptions): Promise<ProcessResult> {
+  const { store, workDir, owner, id, sourceKey, onProgress } = opts;
+  const report = (s: ProcessingStatus, p: number) => onProgress?.(s, p);
+  const idle: ProcessResult = {
+    status: 'ready',
+    durationSeconds: 0,
+    hasHls: false,
+    hasSprite: false,
+    hasPoster: false,
+  };
+
+  if (!(await isFfmpegAvailable())) {
+    report('ready', 100);
+    return idle;
+  }
+
+  const jobDir = path.join(workDir, owner, id);
+  await mkdir(jobDir, { recursive: true });
+
+  try {
+    report('processing', 1);
+
+    // 1. Materialise the source locally for ffmpeg (use the backend's own path if local).
+    let srcPath = (await store.localPath?.(sourceKey)) ?? null;
+    if (!srcPath) {
+      const bytes = await store.get(sourceKey);
+      if (!bytes) throw new Error(`source missing: ${sourceKey}`);
+      srcPath = path.join(jobDir, 'source.bin');
+      await Bun.write(srcPath, bytes);
+    }
+
+    const probe = await probeVideoStream(srcPath);
+    const durationSeconds = probe.duration;
+
+    // Poster-only mode: extract one frame + report ready. No re-encode, no HLS, no sprite —
+    // the memory-heavy steps that OOM'd the 1GB host stay off; the raw source plays as-is.
+    if (opts.posterOnly) {
+      report('processing', 50);
+      const posterPath = path.join(jobDir, 'poster.jpg');
+      const okPoster = await extractPoster(srcPath, posterPath, durationSeconds);
+      if (okPoster) await uploadFile(store, posterPath, fsPosterKey(owner, id), 'image/jpeg');
+      report('ready', 100);
+      return {
+        status: 'ready',
+        durationSeconds,
+        hasHls: false,
+        hasSprite: false,
+        hasPoster: okPoster,
+      };
+    }
+
+    // 2. Faststart MP4 — the progressive Range fallback (streamUrl). Stream-copy when the
+    //    source is already web-safe, else re-encode to the shared web-safe ladder.
+    const mp4Path = path.join(jobDir, 'out.mp4');
+    const okMp4 = await runFfmpegProgress(
+      faststartArgs(srcPath, mp4Path, { copy: canStreamCopy(probe) }),
+      durationSeconds,
+      (pct) => report('processing', Math.round(pct * 0.4)),
+    );
+    if (okMp4) await uploadFile(store, mp4Path, fsMp4Key(owner, id), 'video/mp4');
+    // ffmpeg operates on the faststart output when it exists, else the raw source.
+    const encodeInput = okMp4 ? mp4Path : srcPath;
+
+    // 3. HLS ladder — the adaptive path (hlsUrl).
+    const heights = resolveLadder(opts.ladderHeights ?? [480, 720, 1080], probe.height);
+    const hlsDir = path.join(jobDir, 'hls');
+    await mkdir(hlsDir, { recursive: true });
+    const okHls = await runFfmpegProgress(
+      hlsLadderArgs(encodeInput, hlsDir, {
+        heights,
+        crf: Number(LIBRARY_CRF),
+        hasAudio: probe.hasAudio,
+      }),
+      durationSeconds,
+      (pct) => report('processing', 40 + Math.round(pct * 0.5)),
+    );
+    if (okHls) await uploadHlsTree(store, hlsDir, owner, id);
+
+    // 4. Poster (frame ~1s in).
+    report('processing', 92);
+    const posterPath = path.join(jobDir, 'poster.jpg');
+    const okPoster = await extractPoster(encodeInput, posterPath, durationSeconds);
+    if (okPoster) await uploadFile(store, posterPath, fsPosterKey(owner, id), 'image/jpeg');
+
+    // 5. Sprite sheet + WebVTT scrub track.
+    report('processing', 96);
+    let hasSprite = false;
+    if (durationSeconds > 0) {
+      const plan = planSprite(durationSeconds, 5, probe.width, probe.height);
+      const spritePath = path.join(jobDir, 'sprites.jpg');
+      if (await runFfmpegProgress(spriteArgs(encodeInput, spritePath, plan), 0)) {
+        await uploadFile(store, spritePath, fsSpriteKey(owner, id), 'image/jpeg');
+        await store.put(
+          fsVttKey(owner, id),
+          new TextEncoder().encode(buildSpriteVtt(plan, 'sprites.jpg')),
+          'text/vtt',
+        );
+        hasSprite = true;
+      }
+    }
+
+    report('ready', 100);
+    return {
+      status: 'ready',
+      durationSeconds,
+      hasHls: okHls && (await store.stat(fsHlsMasterKey(owner, id))) !== null,
+      hasSprite,
+      hasPoster: okPoster,
+    };
+  } catch {
+    report('failed', 0);
+    return { ...idle, status: 'failed' };
+  } finally {
+    await rm(jobDir, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/server/sync/alarm.spec.ts

@@ -0,0 +1,149 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createSyncAlarm } from "./alarm";
+
+/**
+ * 🔴 `tmpdir()`, not vault's `scratchDir()` — the seam moved when this engine did.
+ *
+ * In `apps/vault` this suite imported `scripts/testScratch`, an opt-in helper that
+ * hands out a directory under `$FORGE_STATE` and sweeps it. cursedbelt solves the
+ * same problem one level lower: `forceTestEnv.ts` is a bunfig PRELOAD that
+ * redirects `$TMPDIR` itself for every test process in the repo (rationale and the
+ * 4,950× measurement behind it are in `scripts/testTmpRoot.ts`). So a plain
+ * `mkdtempSync(join(tmpdir(), …))` here already lands in the small, swept root —
+ * and reaching back for the app's helper would be a cross-repo import that only
+ * resolves while the copy in vault still exists.
+ */
+const dirs: string[] = [];
+const scratchDir = (prefix: string): string => {
+	const dir = mkdtempSync(join(tmpdir(), `cb-${prefix}-`));
+	dirs.push(dir);
+	return dir;
+};
+afterAll(() => {
+	for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function makeAlarm(overrides: { threshold?: number; reRaiseMs?: number } = {}) {
+	const dir = scratchDir("sync-alarm");
+	const raised: string[] = [];
+	let clock = 1_000_000;
+	const alarm = createSyncAlarm({
+		statePath: join(dir, "alarm.json"),
+		threshold: overrides.threshold ?? 3,
+		reRaiseMs: overrides.reRaiseMs ?? 60_000,
+		notify: (_title, body) => raised.push(body),
+		now: () => clock,
+		appName: "station",
+	});
+	return { alarm, raised, tick: (ms: number) => (clock += ms) };
+}
+
+describe("sync alarm", () => {
+	test("raises after the threshold of paused rounds, not before", () => {
+		const { alarm, raised } = makeAlarm();
+		alarm.record("paused", "doc.set");
+		alarm.record("paused", "doc.set");
+		expect(raised).toHaveLength(0);
+		alarm.record("paused", "doc.set");
+		expect(raised).toHaveLength(1);
+		expect(raised[0]).toContain("doc.set");
+	});
+
+	test("re-raises only after the re-raise window", () => {
+		const { alarm, raised, tick } = makeAlarm();
+		for (let i = 0; i < 5; i++) alarm.record("paused", "k");
+		expect(raised).toHaveLength(1);
+		tick(59_000);
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(1);
+		tick(2_000);
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(2);
+	});
+
+	test("ok resets the counter; unreachable neither counts nor resets", () => {
+		const { alarm, raised } = makeAlarm();
+		alarm.record("paused", "k");
+		alarm.record("paused", "k");
+		// The nightly window: unreachable rounds must not walk the counter to the
+		// threshold, and must not clear a genuine pause streak either.
+		alarm.record("unreachable");
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(1);
+		alarm.record("ok");
+		alarm.record("paused", "k");
+		alarm.record("paused", "k");
+		expect(raised).toHaveLength(1); // streak restarted from zero
+	});
+
+	test("auth refusals raise with the re-link message", () => {
+		const { alarm, raised } = makeAlarm({ threshold: 1 });
+		alarm.record("auth");
+		expect(raised[0]).toContain("Re-link");
+	});
+
+	test("state survives a process restart (same state file)", () => {
+		const dir = scratchDir("sync-alarm");
+		const statePath = join(dir, "alarm.json");
+		const raised: string[] = [];
+		const make = () =>
+			createSyncAlarm({
+				statePath,
+				threshold: 3,
+				notify: (_t, b) => raised.push(b),
+				now: () => 5_000,
+			});
+		make().record("paused", "k");
+		make().record("paused", "k");
+		make().record("paused", "k");
+		expect(raised).toHaveLength(1);
+	});
+});
+
+/**
+ * 🔴 The outcome that was missing, and the eight days it cost.
+ *
+ * The console's subdomain cutover left the Mac's sync dialer aimed at a host
+ * that had become a 301. It followed the redirect into a Cloudflare Access login
+ * page and threw a JSON parse error every round — neither `paused` (nothing was
+ * version-skewed), nor `auth` (no token was refused), nor `unreachable` (the
+ * peer answered). So the alarm recorded NOTHING while every mirrored report on
+ * prod froze, each still rendering a confident age.
+ */
+describe("a sustained hard ERROR raises, exactly like a sustained pause", () => {
+	test("consecutive errors cross the threshold and the alarm names the real error", () => {
+		const { alarm, raised } = makeAlarm({ threshold: 3 });
+		alarm.record("error", "sync/info: 200 answered text/html, not JSON");
+		alarm.record("error", "sync/info: 200 answered text/html, not JSON");
+		expect(raised).toHaveLength(0);
+		alarm.record("error", "sync/info: 200 answered text/html, not JSON");
+		expect(raised).toHaveLength(1);
+		// The message carries the cause, because "failed (ignored)" being
+		// uninformative is the whole reason this outcome exists.
+		expect(raised[0]).toContain("text/html");
+	});
+
+	test("one good round clears the counter", () => {
+		const { alarm, raised } = makeAlarm({ threshold: 3 });
+		alarm.record("error", "boom");
+		alarm.record("error", "boom");
+		alarm.record("ok");
+		alarm.record("error", "boom");
+		alarm.record("error", "boom");
+		expect(raised).toHaveLength(0);
+	});
+
+	test("an UNREACHABLE peer between errors neither counts nor resets", () => {
+		// The nightly EC2 sleep sits in the middle of a real outage all the time.
+		const { alarm, raised } = makeAlarm({ threshold: 3 });
+		alarm.record("error", "boom");
+		alarm.record("unreachable");
+		alarm.record("error", "boom");
+		alarm.record("unreachable");
+		alarm.record("error", "boom");
+		expect(raised).toHaveLength(1);
+	});
+});