@remnic/core 9.15.3 → 9.16.0

package/src/activity/runner.ts

@@ -0,0 +1,237 @@
+/**
+ * Host-agnostic activity sync runner (issue #1900).
+ *
+ * Bridges parsed `config.activity` to the durable sync pipeline: the parser
+ * (config.ts) validates settings but never contacts a daemon, and
+ * `syncActivitySource` (pipeline.ts) syncs one source for one day. This runner
+ * is the missing middle — it instantiates one `ActivityHttpSourceClient` per
+ * configured source from the parsed config and drives a sync across the
+ * `syncDays` local-day window, but ONLY when the feature is enabled.
+ *
+ * The feature is master default-off: source config alone never starts a sync.
+ * When `config.enabled` is false the runner opens no store, builds no client,
+ * and makes no HTTP call or write — it returns a disabled summary. This mirrors
+ * `runLiveConnectorsOnce`'s disabled-vs-result reporting so a host scheduler
+ * (CLI, cron) can trigger it through the runtime with no OpenClaw imports.
+ *
+ * Cursor semantics are delegated wholesale to `syncActivitySource`: the
+ * per-machine cursor advances only after every page and the digest are durable,
+ * so a runtime failure (or an aborted stop) leaves the cursor unadvanced and a
+ * restart resumes from the persisted position. A per-source failure is captured
+ * as an error item and never aborts the other sources or the host flow.
+ */
+
+import { ActivityStore } from "./store.js";
+import { syncActivitySource } from "./pipeline.js";
+import { ActivityHttpSourceClient } from "./source-client.js";
+import { displayErrorDetail } from "../runtime/better-sqlite.js";
+import type { ActivityConfig, ActivitySourceClient, ActivitySourceConfig } from "./types.js";
+
+type ActivityNow = Date | (() => Date);
+
+/** One configured source's aggregate result across the synced day window. */
+export interface ActivitySourceRunItem {
+  machineLabel: string;
+  /** True when at least one day synced durably (no error). */
+  ran: boolean;
+  fetched: number;
+  inserted: number;
+  duplicates: number;
+  digestsWritten: number;
+  /** Persisted cursor after the run; unadvanced from prior on failure. */
+  cursor: string | null;
+  /** Set when the source failed; distinguishes a fault from an empty page. */
+  error?: string;
+  /**
+   * Set when a durable day synced but its post-digest search reindex failed.
+   * The rows/digest/cursor are committed; the index is stale until the next
+   * refresh, so this is a signal (not a sync failure) for the scheduler.
+   */
+  reindexError?: string;
+}
+
+export interface ActivitySyncRunSummary {
+  ranAt: string;
+  /** False means the feature is off: no client built, no HTTP, no write. */
+  enabled: boolean;
+  ranCount: number;
+  errorCount: number;
+  /** Sources whose durable sync succeeded but whose search reindex failed. */
+  reindexErrorCount: number;
+  totalInserted: number;
+  results: ActivitySourceRunItem[];
+}
+
+export interface ActivitySyncRunOptions {
+  config: ActivityConfig;
+  memoryDir: string;
+  /** Injectable store; opened from memoryDir when omitted (and closed here). */
+  store?: ActivityStore;
+  /** Clock injection for deterministic day-window resolution in tests. */
+  now?: ActivityNow;
+  /** Abort a run in flight (stop); an aborted source leaves its cursor intact. */
+  signal?: AbortSignal;
+  /** Injectable client factory; builds an ActivityHttpSourceClient by default. */
+  createSourceClient?: (source: ActivitySourceConfig) => ActivitySourceClient;
+  /**
+   * Search-index refresh forwarded to each source sync as `afterWrites`, run
+   * after a digest is (re)written so it becomes discoverable (rule 31).
+   * Host wires the core index seam (SearchBackend.update); best-effort.
+   */
+  reindexSearch?: (signal?: AbortSignal) => Promise<void>;
+}
+
+/** Format a Date as YYYY-MM-DD in an IANA timezone (local calendar day). */
+function localDateInTimezone(instant: Date, timezone: string): string {
+  try {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).formatToParts(instant);
+    const get = (type: string): string => parts.find((part) => part.type === type)?.value ?? "";
+    return `${get("year")}-${get("month")}-${get("day")}`;
+  } catch {
+    return instant.toISOString().slice(0, 10);
+  }
+}
+
+/** Previous calendar date via pure date arithmetic (no DST wall-clock drift). */
+function previousIsoDate(date: string): string {
+  const parsed = new Date(`${date}T00:00:00Z`);
+  parsed.setUTCDate(parsed.getUTCDate() - 1);
+  return parsed.toISOString().slice(0, 10);
+}
+
+/**
+ * The local-day window to sync, oldest first: today back `syncDays` calendar
+ * days in the configured timezone. Walking by calendar days (not fixed 24h
+ * intervals) keeps the window correct across DST transitions.
+ */
+export function resolveActivitySyncDates(syncDays: number, timezone: string, now: Date): string[] {
+  const dates: string[] = [];
+  let cursor = localDateInTimezone(now, timezone);
+  for (let count = 0; count < syncDays; count++) {
+    dates.unshift(cursor);
+    cursor = previousIsoDate(cursor);
+  }
+  return dates;
+}
+
+/**
+ * Operator-facing detail for a per-source/per-day sync fault. Our own
+ * controlled messages (activity.../Invalid activity...) are informative and
+ * safe to surface; opaque network/runtime errors can embed hostnames or paths,
+ * so they are reduced to a sanitized name+code (matches ActivityHttpSourceClient.verify).
+ */
+function sanitizedSyncError(error: unknown): string {
+  return error instanceof Error && /^(activity|Invalid activity)/.test(error.message)
+    ? error.message
+    : displayErrorDetail(error) || "activity sync failed";
+}
+
+/**
+ * Run one activity sync pass across every configured source. Disabled config
+ * short-circuits before any store/client/HTTP work; an enabled config syncs
+ * each source across the `syncDays` window and isolates per-source faults.
+ */
+export async function runActivitySyncOnce(options: ActivitySyncRunOptions): Promise<ActivitySyncRunSummary> {
+  const ranAt = typeof options.now === "function" ? options.now() : options.now ?? new Date();
+
+  if (!options.config.enabled) {
+    return {
+      ranAt: ranAt.toISOString(),
+      enabled: false,
+      ranCount: 0,
+      errorCount: 0,
+      reindexErrorCount: 0,
+      totalInserted: 0,
+      results: [],
+    };
+  }
+
+  const dates = resolveActivitySyncDates(options.config.syncDays, options.config.timezone, ranAt);
+  const createSourceClient =
+    options.createSourceClient ??
+    ((source: ActivitySourceConfig): ActivitySourceClient =>
+      new ActivityHttpSourceClient({
+        machineLabel: source.machineLabel,
+        baseUrl: source.baseUrl,
+        ...(source.token === undefined ? {} : { token: source.token }),
+      }));
+  const ownStore = options.store === undefined;
+  const store = options.store ?? ActivityStore.open(options.memoryDir);
+  const results: ActivitySourceRunItem[] = [];
+
+  try {
+    for (const sourceConfig of options.config.sources) {
+      const item: ActivitySourceRunItem = {
+        machineLabel: sourceConfig.machineLabel,
+        ran: false,
+        fetched: 0,
+        inserted: 0,
+        duplicates: 0,
+        digestsWritten: 0,
+        // Cursors are now per (machine, date); report the last synced day's
+        // cursor. Null until a day advances it.
+        cursor: null,
+      };
+      try {
+        const client = createSourceClient(sourceConfig);
+        for (const date of dates) {
+          try {
+            const result = await syncActivitySource(client, {
+              date,
+              timezone: options.config.timezone,
+              memoryDir: options.memoryDir,
+              store,
+              signal: options.signal,
+              ...(options.reindexSearch === undefined ? {} : { afterWrites: options.reindexSearch }),
+            });
+            item.fetched += result.fetched;
+            item.inserted += result.inserted;
+            item.duplicates += result.duplicates;
+            if (result.digestWritten) item.digestsWritten += 1;
+            item.cursor = result.cursor;
+            // A day that synced durably counts as ran, even if a later day in
+            // the window fails (ran = at least one durable day).
+            item.ran = true;
+            // The day's rows/digest/cursor are durable; a failed post-digest
+            // reindex is a separate, already-sanitized signal (not a sync
+            // failure) so the scheduler can observe a stale index.
+            if (result.reindexError !== undefined) item.reindexError = result.reindexError;
+          } catch (dateError) {
+            // One bad day (a malformed historical snapshot, a per-day daemon
+            // error) must not starve the remaining dates — record it and move
+            // on. Dates are processed oldest-first, so continuing keeps today's
+            // sync alive when an old backfill day is broken. An abort, though,
+            // halts the whole run.
+            item.error = sanitizedSyncError(dateError);
+            if (options.signal?.aborted) break;
+          }
+        }
+      } catch (error) {
+        // Client construction failed: no date could run for this source.
+        item.error = sanitizedSyncError(error);
+      }
+      results.push(item);
+      // An abort halts the WHOLE run: the in-flight source above is recorded
+      // (its fast-failing attempt reports an error), but no later source builds
+      // a client or contacts a daemon — teardown settles promptly.
+      if (options.signal?.aborted) break;
+    }
+  } finally {
+    if (ownStore) store.close();
+  }
+
+  return {
+    ranAt: ranAt.toISOString(),
+    enabled: true,
+    ranCount: results.filter((item) => item.ran).length,
+    errorCount: results.filter((item) => item.error !== undefined).length,
+    reindexErrorCount: results.filter((item) => item.reindexError !== undefined).length,
+    totalInserted: results.reduce((sum, item) => sum + item.inserted, 0),
+    results,
+  };
+}

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;
+      });
+  }
+}