@remnic/core 9.15.2 → 9.16.0

package/src/activity/scheduler.test.ts

@@ -0,0 +1,303 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { ACTIVITY_SYNC_DEFAULT_INTERVAL_MS, ActivitySyncScheduler } from "./scheduler.js";
+import { runActivitySyncOnce, type ActivitySyncRunSummary } from "./runner.js";
+import { ActivityStore } from "./store.js";
+import { activityCursorKey } from "./pipeline.js";
+import type { ActivityConfig, ActivitySnapshot, ActivitySourceClient } from "./types.js";
+
+/** A hand-driven timer: records armed callbacks + intervals, fires on demand. */
+function fakeTimer(): {
+  setTimer: (fn: () => void, ms: number) => number;
+  clearTimer: (handle: unknown) => void;
+  armed: Array<{ fn: () => void; ms: number }>;
+  cleared: number;
+} {
+  const armed: Array<{ fn: () => void; ms: number }> = [];
+  let cleared = 0;
+  return {
+    armed,
+    get cleared() {
+      return cleared;
+    },
+    setTimer(fn, ms) {
+      armed.push({ fn, ms });
+      return armed.length;
+    },
+    clearTimer() {
+      cleared += 1;
+    },
+  };
+}
+
+/** Drain the microtask queue so a fired tick's async invoke chain settles. */
+function flush(): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setImmediate(resolve);
+  return promise;
+}
+
+const SUMMARY: ActivitySyncRunSummary = {
+  ranAt: "2026-07-22T18:00:00.000Z",
+  enabled: true,
+  ranCount: 1,
+  errorCount: 0,
+  reindexErrorCount: 0,
+  totalInserted: 0,
+  results: [],
+};
+
+function enabledConfig(): ActivityConfig {
+  return {
+    enabled: true,
+    timezone: "UTC",
+    syncDays: 1,
+    autoSyncIntervalMinutes: 15,
+    sources: [{ machineLabel: "workstation-a", baseUrl: "http://127.0.0.1:8760" }],
+  };
+}
+
+function disabledConfig(): ActivityConfig {
+  return {
+    enabled: false,
+    timezone: "UTC",
+    syncDays: 1,
+    autoSyncIntervalMinutes: 15,
+    sources: [{ machineLabel: "workstation-a", baseUrl: "http://127.0.0.1:8760" }],
+  };
+}
+
+test("default-off: start registers no timer and never invokes", async () => {
+  const timer = fakeTimer();
+  let calls = 0;
+  const scheduler = new ActivitySyncScheduler({
+    config: disabledConfig(),
+    memoryDir: "/tmp/unused-activity-scheduler",
+    invoke: async () => {
+      calls += 1;
+      return SUMMARY;
+    },
+    setTimer: timer.setTimer,
+    clearTimer: timer.clearTimer,
+  });
+
+  const registration = scheduler.start();
+
+  assert.equal(registration.registered, false);
+  assert.equal(registration.intervalMs, ACTIVITY_SYNC_DEFAULT_INTERVAL_MS);
+  assert.equal(timer.armed.length, 0, "no timer armed while disabled");
+  await flush();
+  assert.equal(calls, 0, "disabled scheduler never invokes the runner");
+});
+
+test("enabled: registers a periodic timer that invokes the runner on cadence", async () => {
+  const timer = fakeTimer();
+  const summaries: ActivitySyncRunSummary[] = [];
+  let calls = 0;
+  const scheduler = new ActivitySyncScheduler({
+    config: enabledConfig(),
+    memoryDir: "/tmp/unused-activity-scheduler",
+    invoke: async () => {
+      calls += 1;
+      return SUMMARY;
+    },
+    setTimer: timer.setTimer,
+    clearTimer: timer.clearTimer,
+    onRun: (summary) => summaries.push(summary),
+  });
+
+  const registration = scheduler.start();
+  assert.equal(registration.registered, true);
+  assert.equal(registration.intervalMs, ACTIVITY_SYNC_DEFAULT_INTERVAL_MS);
+  assert.equal(timer.armed.length, 1, "exactly one periodic timer armed");
+  assert.equal(timer.armed[0].ms, ACTIVITY_SYNC_DEFAULT_INTERVAL_MS);
+
+  // Each cadence tick invokes one durable sync pass.
+  for (let i = 0; i < 3; i++) {
+    timer.armed[0].fn();
+    await flush();
+  }
+  assert.equal(calls, 3, "three ticks -> three sync invocations");
+  assert.equal(summaries.length, 3, "each run's summary is surfaced");
+});
+
+test("cadence override is honored; default applies when omitted", () => {
+  const timer = fakeTimer();
+  new ActivitySyncScheduler({
+    config: enabledConfig(),
+    memoryDir: "/tmp/unused",
+    intervalMs: 1_000,
+    invoke: async () => SUMMARY,
+    setTimer: timer.setTimer,
+    clearTimer: timer.clearTimer,
+  }).start();
+  assert.equal(timer.armed[0].ms, 1_000, "explicit cadence used");
+
+  // Issue #1899 contracts activity.autoSyncIntervalMinutes default 15, i.e. a
+  // 15-minute effective cadence — not connectors' 5-minute poll.
+  assert.equal(ACTIVITY_SYNC_DEFAULT_INTERVAL_MS, 15 * 60_000, "default cadence is 15 minutes (#1899)");
+  const defaulted = fakeTimer();
+  new ActivitySyncScheduler({
+    config: enabledConfig(),
+    memoryDir: "/tmp/unused",
+    invoke: async () => SUMMARY,
+    setTimer: defaulted.setTimer,
+    clearTimer: defaulted.clearTimer,
+  }).start();
+  assert.equal(defaulted.armed[0].ms, 900_000, "omitted cadence uses the 15-minute default");
+});
+
+test("stop cancels the timer so no later tick invokes", async () => {
+  const timer = fakeTimer();
+  let calls = 0;
+  const scheduler = new ActivitySyncScheduler({
+    config: enabledConfig(),
+    memoryDir: "/tmp/unused-activity-scheduler",
+    invoke: async () => {
+      calls += 1;
+      return SUMMARY;
+    },
+    setTimer: timer.setTimer,
+    clearTimer: timer.clearTimer,
+  });
+
+  scheduler.start();
+  timer.armed[0].fn();
+  await flush();
+  assert.equal(calls, 1);
+
+  await scheduler.stop();
+  assert.equal(timer.cleared, 1, "stop cancels the underlying timer");
+
+  // A stray callback firing after stop must not invoke (latched-stop guard).
+  timer.armed[0].fn();
+  await flush();
+  assert.equal(calls, 1, "no invocation after stop");
+
+  // Restart after stop is a no-op: a stopped scheduler stays stopped.
+  const restart = scheduler.start();
+  assert.equal(restart.registered, false);
+  assert.equal(timer.armed.length, 1, "no new timer armed after stop");
+});
+
+test("overlapping ticks do not stack: a slow sync blocks the next tick", async () => {
+  const timer = fakeTimer();
+  let calls = 0;
+  let releaseFirst: () => void = () => {};
+  const scheduler = new ActivitySyncScheduler({
+    config: enabledConfig(),
+    memoryDir: "/tmp/unused-activity-scheduler",
+    invoke: () => {
+      calls += 1;
+      const { promise, resolve } = Promise.withResolvers<ActivitySyncRunSummary>();
+      releaseFirst = () => resolve(SUMMARY);
+      return promise;
+    },
+    setTimer: timer.setTimer,
+    clearTimer: timer.clearTimer,
+  });
+
+  scheduler.start();
+  timer.armed[0].fn(); // starts a sync that stays in-flight
+  await flush();
+  timer.armed[0].fn(); // second tick while the first is unresolved
+  await flush();
+  assert.equal(calls, 1, "the in-flight guard drops the overlapping tick");
+
+  releaseFirst();
+  await flush();
+  // Once the first settles, a later tick runs again.
+  timer.armed[0].fn();
+  await flush();
+  assert.equal(calls, 2, "a tick after the sync settles invokes again");
+});
+
+test("parser -> scheduler -> durable sync: a tick performs a real durable sync", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-activity-scheduler-"));
+  const store = ActivityStore.open(memoryDir);
+  try {
+    const snapshot: ActivitySnapshot = {
+      machine: "wire-label",
+      capturedAtUtc: "2026-07-22T14:00:00.000Z",
+      app: "Browser",
+      windowTitle: "Example",
+      text: "synthetic snapshot",
+      textSource: "ax",
+      contentHash: "hash-1",
+    };
+    const client: ActivitySourceClient = {
+      machineLabel: "workstation-a",
+      async verify() {
+        return { ok: true };
+      },
+      async fetchSnapshots() {
+        return { snapshots: [snapshot], nextCursor: null };
+      },
+    };
+
+    const timer = fakeTimer();
+    const scheduler = new ActivitySyncScheduler({
+      config: enabledConfig(),
+      memoryDir,
+      // Real durable runner, fixture daemon + shared store — the scheduler
+      // drives the same code path the default invoke uses.
+      invoke: (signal) =>
+        runActivitySyncOnce({
+          config: enabledConfig(),
+          memoryDir,
+          store,
+          now: new Date("2026-07-22T18:00:00.000Z"),
+          signal,
+          createSourceClient: () => client,
+        }),
+      setTimer: timer.setTimer,
+      clearTimer: timer.clearTimer,
+    });
+
+    scheduler.start();
+    timer.armed[0].fn();
+    await flush();
+
+    assert.equal(store.getCursor(activityCursorKey("workstation-a", "2026-07-22")), null, "cursor advanced by the durable sync");
+    const rows = store.listSnapshotsForDay(null, "2026-07-22T00:00:00.000Z", "2026-07-23T00:00:00.000Z");
+    assert.equal(rows.length, 1, "the tick persisted the snapshot durably");
+  } finally {
+    store.close();
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("stop aborts an in-flight tick and drains before resolving", async () => {
+  const timer = fakeTimer();
+  let observedSignal: AbortSignal | undefined;
+  let unwound = false;
+  const scheduler = new ActivitySyncScheduler({
+    config: enabledConfig(),
+    memoryDir: "/tmp/unused-activity-scheduler",
+    invoke: (signal) =>
+      new Promise<ActivitySyncRunSummary>((_resolve, reject) => {
+        observedSignal = signal;
+        signal?.addEventListener("abort", () => {
+          unwound = true;
+          reject(new Error("aborted"));
+        });
+      }),
+    setTimer: timer.setTimer,
+    clearTimer: timer.clearTimer,
+    onError: () => {}, // swallow the abort rejection so the drain resolves
+  });
+
+  scheduler.start();
+  timer.armed[0].fn(); // launch a sync that stays in-flight until aborted
+  await flush();
+  assert.ok(observedSignal, "tick threads an abort signal into invoke");
+  assert.equal(observedSignal?.aborted, false, "not aborted while running");
+
+  await scheduler.stop();
+  assert.equal(observedSignal?.aborted, true, "stop aborts the in-flight tick");
+  assert.equal(unwound, true, "stop waited for the aborted sync to unwind");
+});

package/src/activity/scheduler.ts

@@ -0,0 +1,147 @@
+/**
+ * In-process periodic driver for activity (screen-capture) sync (issue #1900).
+ *
+ * The parser (config.ts) validates `config.activity` and the runner
+ * (runner.ts) performs one durable sync pass, but nothing drove that pass on a
+ * cadence — parsed config alone never synced. This scheduler is the missing
+ * link: parser -> scheduler -> durable sync. It registers a repeating timer
+ * that invokes the runner, and cancels it on stop.
+ *
+ * Master default-off: when `config.activity.enabled` is false, `start()`
+ * registers no timer and never invokes — source config alone starts nothing.
+ * `stop()` clears the timer and latches so no later tick invokes, which is what
+ * a runtime teardown (or a config disable + restart) needs. Ticks are
+ * overlap-guarded (a slow sync never stacks) and never throw out of the timer.
+ *
+ * Host-agnostic: the timer and clock are injectable, so a host schedules
+ * through this without any OpenClaw import, and tests drive it deterministically.
+ */
+
+import { runActivitySyncOnce, type ActivitySyncRunSummary } from "./runner.js";
+import type { ActivityConfig } from "./types.js";
+
+/**
+ * Default sync cadence: 15 minutes. Issue #1899 contracts
+ * `activity.autoSyncIntervalMinutes` with a default of 15, so the effective
+ * default interval is 15 * 60_000 = 900_000 ms. Overridable via `intervalMs`.
+ */
+export const ACTIVITY_SYNC_DEFAULT_INTERVAL_MS = 900_000;
+
+/** An opaque timer handle from whichever timer implementation is injected. */
+type TimerHandle = unknown;
+
+export interface ActivitySyncSchedulerOptions {
+  config: ActivityConfig;
+  memoryDir: string;
+  /** Cadence in ms; defaults to ACTIVITY_SYNC_DEFAULT_INTERVAL_MS. */
+  intervalMs?: number;
+  /** The sync pass to run each tick; defaults to the durable runner. */
+  invoke?: (signal?: AbortSignal) => Promise<ActivitySyncRunSummary>;
+  /** Search-index refresh forwarded to the default runner as `reindexSearch`. */
+  reindexSearch?: (signal?: AbortSignal) => Promise<void>;
+  /** Timer factory (injectable for tests); defaults to an unref'd setInterval. */
+  setTimer?: (fn: () => void, ms: number) => TimerHandle;
+  /** Timer canceller matching setTimer; defaults to clearInterval. */
+  clearTimer?: (handle: TimerHandle) => void;
+  /** Called with each successful run's summary (telemetry/tests). */
+  onRun?: (summary: ActivitySyncRunSummary) => void;
+  /** Called when a tick's sync rejects; defaults to swallowing (best-effort). */
+  onError?: (error: unknown) => void;
+}
+
+export interface ActivitySyncRegistration {
+  /** True when a periodic timer was armed (feature enabled). */
+  registered: boolean;
+  /** The cadence the timer runs at (reported even when not registered). */
+  intervalMs: number;
+}
+
+/**
+ * Registers/cancels a periodic activity sync. One instance per memory dir;
+ * `start()` and `stop()` are both idempotent.
+ */
+export class ActivitySyncScheduler {
+  private readonly config: ActivityConfig;
+  private readonly memoryDir: string;
+  private readonly intervalMs: number;
+  private readonly invoke: (signal?: AbortSignal) => Promise<ActivitySyncRunSummary>;
+  private readonly setTimer: (fn: () => void, ms: number) => TimerHandle;
+  private readonly clearTimer: (handle: TimerHandle) => void;
+  private readonly onRun: ((summary: ActivitySyncRunSummary) => void) | undefined;
+  private readonly onError: ((error: unknown) => void) | undefined;
+
+  private handle: TimerHandle = null;
+  private stopped = false;
+  private inFlight = false;
+  private inFlightPromise: Promise<void> | null = null;
+  private readonly abortController = new AbortController();
+
+  constructor(options: ActivitySyncSchedulerOptions) {
+    this.config = options.config;
+    this.memoryDir = options.memoryDir;
+    this.intervalMs = options.intervalMs ?? ACTIVITY_SYNC_DEFAULT_INTERVAL_MS;
+    this.invoke =
+      options.invoke ??
+      ((signal) =>
+        runActivitySyncOnce({
+          config: this.config,
+          memoryDir: this.memoryDir,
+          signal,
+          ...(options.reindexSearch === undefined ? {} : { reindexSearch: options.reindexSearch }),
+        }));
+    this.setTimer =
+      options.setTimer ??
+      ((fn, ms) => {
+        const timer = setInterval(fn, ms);
+        // Never keep the host process alive solely for the sync cadence.
+        timer.unref?.();
+        return timer;
+      });
+    this.clearTimer =
+      options.clearTimer ?? ((handle) => clearInterval(handle as NodeJS.Timeout));
+    this.onRun = options.onRun;
+    this.onError = options.onError;
+  }
+
+  /**
+   * Arm the periodic sync. Disabled config (default-off) registers nothing.
+   * Idempotent: a second call while running (or after stop) re-arms nothing.
+   */
+  start(): ActivitySyncRegistration {
+    if (this.handle !== null || this.stopped || !this.config.enabled) {
+      return { registered: this.handle !== null, intervalMs: this.intervalMs };
+    }
+    this.handle = this.setTimer(() => this.tick(), this.intervalMs);
+    return { registered: true, intervalMs: this.intervalMs };
+  }
+
+  /**
+   * Cancel the periodic sync and abort any in-flight tick, then resolve once it
+   * has unwound. The abort + timer-clear + stop-latch happen synchronously, so
+   * even a caller that cannot await (a sync teardown) still signals the running
+   * sync to stop; async callers can await the returned drain. Idempotent.
+   */
+  async stop(): Promise<void> {
+    this.stopped = true;
+    this.abortController.abort();
+    if (this.handle !== null) {
+      this.clearTimer(this.handle);
+      this.handle = null;
+    }
+    await this.inFlightPromise?.catch(() => undefined);
+  }
+
+  private tick(): void {
+    // Latched-stop and overlap guards: a callback that fires after stop(), or
+    // while a prior slow sync is still running, must not invoke.
+    if (this.stopped || this.inFlight) return;
+    this.inFlight = true;
+    this.inFlightPromise = this.invoke(this.abortController.signal)
+      .then((summary) => this.onRun?.(summary))
+      .catch((error) => this.onError?.(error))
+      .finally(() => {
+        this.inFlight = false;
+        this.inFlightPromise = null;
+      });
+  }
+}

package/src/activity/source-client.test.ts

@@ -0,0 +1,208 @@
+import assert from "node:assert/strict";
+import { createServer, type RequestListener } from "node:http";
+import test from "node:test";
+
+import { ActivityHttpSourceClient } from "./source-client.js";
+
+async function withServer(
+  handler: RequestListener,
+  run: (baseUrl: string) => Promise<void>,
+): Promise<void> {
+  const server = createServer(handler);
+  const listening = Promise.withResolvers<void>();
+  server.listen(0, "127.0.0.1", listening.resolve);
+  await listening.promise;
+  try {
+    const address = server.address();
+    assert.ok(address && typeof address !== "string");
+    await run(`http://127.0.0.1:${address.port}`);
+  } finally {
+    const closed = Promise.withResolvers<void>();
+    server.close((error) => (error ? closed.reject(error) : closed.resolve()));
+    await closed.promise;
+  }
+}
+
+test("ActivityHttpSourceClient authenticates and maps a snapshot page", async () => {
+  await withServer((request, response) => {
+    assert.equal(request.headers.authorization, "Bearer fixture-token");
+    assert.equal(request.url, "/v1/snapshots?date=2026-07-22&timezone=America%2FChicago&cursor=next%20cursor");
+    response.setHeader("content-type", "application/json");
+    response.end(
+      JSON.stringify({
+        snapshots: [
+          {
+            capturedAtUtc: "2026-07-22T14:00:00.000Z",
+            app: "Browser",
+            windowTitle: "Fixture",
+            text: "synthetic text",
+            textSource: "ax",
+            contentHash: "abc123",
+          },
+        ],
+        nextCursor: "cursor-2",
+      }),
+    );
+  }, async (baseUrl) => {
+    const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl, token: "fixture-token" });
+    const page = await client.fetchSnapshots({ date: "2026-07-22", timezone: "America/Chicago", cursor: "next cursor" });
+
+    assert.deepEqual(page, {
+      snapshots: [
+        {
+          machine: "fixture-machine",
+          capturedAtUtc: "2026-07-22T14:00:00.000Z",
+          app: "Browser",
+          windowTitle: "Fixture",
+          text: "synthetic text",
+          textSource: "ax",
+          contentHash: "abc123",
+        },
+      ],
+      nextCursor: "cursor-2",
+    });
+  });
+});
+
+test("ActivityHttpSourceClient treats an omitted nextCursor as end-of-pagination", async () => {
+  await withServer((_request, response) => {
+    response.setHeader("content-type", "application/json");
+    // Daemon omits nextCursor entirely (not JSON null) on the final page.
+    response.end(
+      JSON.stringify({
+        snapshots: [
+          {
+            capturedAtUtc: "2026-07-22T14:00:00.000Z",
+            app: "Browser",
+            windowTitle: "Fixture",
+            text: "synthetic text",
+            textSource: "ax",
+            contentHash: "abc123",
+          },
+        ],
+      }),
+    );
+  }, async (baseUrl) => {
+    const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl });
+    const page = await client.fetchSnapshots({ date: "2026-07-22", timezone: "UTC" });
+    assert.equal(page.nextCursor, null, "a missing nextCursor is normal completion, not an error");
+    assert.equal(page.snapshots.length, 1);
+  });
+});
+
+test("ActivityHttpSourceClient reports an unreachable health probe without treating it as an empty source", async () => {
+  await withServer((_request, response) => {
+    response.statusCode = 503;
+    response.end("temporarily unavailable");
+  }, async (baseUrl) => {
+    const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl });
+    assert.deepEqual(await client.verify(), { ok: false, detail: "HTTP 503" });
+    await assert.rejects(
+      client.fetchSnapshots({ date: "2026-07-22", timezone: "UTC" }),
+      /HTTP 503/,
+    );
+  });
+});
+
+test("ActivityHttpSourceClient aborts a stalled request via the default timeout", async () => {
+  await withServer((request) => {
+    // Never respond: hold the request open so only the client-side timeout can
+    // end it. The socket is destroyed when fetch aborts, so teardown proceeds.
+    request.resume();
+  }, async (baseUrl) => {
+    const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl, timeoutMs: 50 });
+    assert.deepEqual((await client.verify()).ok, false);
+    await assert.rejects(client.fetchSnapshots({ date: "2026-07-22", timezone: "UTC" }));
+  });
+});
+
+test("ActivityHttpSourceClient honors a caller-supplied abort signal", async () => {
+  await withServer((request) => {
+    request.resume();
+  }, async (baseUrl) => {
+    const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl });
+    await assert.rejects(client.fetchSnapshots({ date: "2026-07-22", timezone: "UTC", signal: AbortSignal.abort() }));
+  });
+});
+
+test("ActivityHttpSourceClient rejects a non-positive timeout", () => {
+  assert.throws(
+    () => new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl: "http://127.0.0.1:4319", timeoutMs: 0 }),
+    /timeoutMs must be a positive number/,
+  );
+});
+
+async function closedLoopbackBaseUrl(): Promise<string> {
+  // Reserve an ephemeral loopback port, then close it so the connection is
+  // deterministically refused (no reliance on a fixed low port being free).
+  const server = createServer();
+  const listening = Promise.withResolvers<void>();
+  server.listen(0, "127.0.0.1", listening.resolve);
+  await listening.promise;
+  const address = server.address();
+  assert.ok(address && typeof address !== "string");
+  const port = address.port;
+  const closed = Promise.withResolvers<void>();
+  server.close((error) => (error ? closed.reject(error) : closed.resolve()));
+  await closed.promise;
+  return `http://127.0.0.1:${port}`;
+}
+
+test("ActivityHttpSourceClient.verify returns a sanitized detail for network errors", async () => {
+  const baseUrl = await closedLoopbackBaseUrl();
+  const port = new URL(baseUrl).port;
+  const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl });
+  const check = await client.verify();
+  assert.equal(check.ok, false);
+  assert.ok(check.detail && check.detail.length > 0, "a failure carries some detail");
+  assert.ok(!check.detail?.includes("127.0.0.1"), "detail does not echo the host");
+  assert.ok(!check.detail?.includes(port), "detail does not echo the port");
+});
+
+test("ActivityHttpSourceClient accepts an empty window title and text (untitled/blank window)", async () => {
+  await withServer((_request, response) => {
+    response.setHeader("content-type", "application/json");
+    response.end(
+      JSON.stringify({
+        snapshots: [
+          {
+            capturedAtUtc: "2026-07-22T14:00:00.000Z",
+            app: "",
+            windowTitle: "",
+            text: "",
+            textSource: "ocr",
+            contentHash: "abc123",
+          },
+        ],
+        nextCursor: null,
+      }),
+    );
+  }, async (baseUrl) => {
+    const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl });
+    const page = await client.fetchSnapshots({ date: "2026-07-22", timezone: "UTC" });
+    // A legitimate no-text/untitled foreground window must parse, not throw —
+    // else the runner errors the day and the cursor never advances past it.
+    assert.equal(page.snapshots.length, 1);
+    assert.equal(page.snapshots[0]?.windowTitle, "");
+    assert.equal(page.snapshots[0]?.text, "");
+    assert.equal(page.snapshots[0]?.app, "");
+  });
+});
+
+test("ActivityHttpSourceClient still rejects a missing contentHash identifier", async () => {
+  await withServer((_request, response) => {
+    response.setHeader("content-type", "application/json");
+    response.end(
+      JSON.stringify({
+        snapshots: [
+          { capturedAtUtc: "2026-07-22T14:00:00.000Z", app: "Browser", windowTitle: "T", text: "x", textSource: "ax" },
+        ],
+        nextCursor: null,
+      }),
+    );
+  }, async (baseUrl) => {
+    const client = new ActivityHttpSourceClient({ machineLabel: "fixture-machine", baseUrl });
+    // Identity/dedup fields are still required and non-empty.
+    await assert.rejects(client.fetchSnapshots({ date: "2026-07-22", timezone: "UTC" }), /contentHash/);
+  });
+});