@mulmoclaude/core 1.11.0 → 1.12.0

package/dist/google/calendarSyncDue.d.ts

@@ -0,0 +1,10 @@
+/** How long a fresh marker suppresses a sync: one interval, less the slack.
+ *  The slack is halved rather than subtracted flat for a very short configured
+ *  interval, where a fixed five minutes would swallow the window whole. */
+export declare function calendarSyncDueWindowMs(intervalMs: number): number;
+/** True iff no recent enough run stands in for this one.
+ *
+ *  A marker that cannot be read as a time is treated as due: a stuck calendar is
+ *  worse than a duplicate run, which the sync is built to tolerate anyway
+ *  (writes are upserts by event id). */
+export declare function isCalendarSyncDue(lastSyncedAt: string | null, windowMs: number, now?: number): boolean;

package/dist/google/calendarSyncStore.d.ts

@@ -3,5 +3,24 @@ export declare function calendarSyncStatePath(workspaceRoot?: string): string;
 export declare function loadCalendarSyncToken(calendarId?: string, workspaceRoot?: string): Promise<string | null>;
 export declare function saveCalendarSyncToken(calendarId: string | undefined, syncToken: string, workspaceRoot?: string): Promise<void>;
 /** Drop one calendar's token — used when Google answers 410, so the next run
- *  starts a clean full sync. */
+ *  starts a clean full sync. Leaves the sync marker alone: "restart the walk"
+ *  says nothing about "nobody is running". */
 export declare function clearCalendarSyncToken(calendarId?: string, workspaceRoot?: string): Promise<void>;
+export declare function loadCalendarLastSyncedAt(calendarId?: string, workspaceRoot?: string): Promise<string | null>;
+/** Stamp when a sync of this calendar started, but only if `mayClaim` accepts
+ *  what the marker currently says. Answers whether THIS call is the one that
+ *  claimed it.
+ *
+ *  The decision and the stamp share one pass through the queue on purpose.
+ *  Deciding from a snapshot read earlier — as a caller filtering a whole map of
+ *  calendars up front must — leaves both hosts believing the calendar is free,
+ *  which is the race this exists to close (Codex review #2680). What remains is
+ *  the read→write gap BETWEEN processes; closing that needs a real file lock
+ *  (#2679), and this stays a soft dedup until then.
+ *
+ *  The time is passed in rather than read here so the rule stays testable
+ *  without freezing the clock. */
+export declare function claimCalendarSyncIfDue(calendarId: string | undefined, startedAt: string, mayClaim: (lastSyncedAt: string | null) => boolean, workspaceRoot?: string): Promise<boolean>;
+/** Drop one calendar's marker, so the next tick — on either host — may sync it
+ *  immediately instead of waiting the window out. */
+export declare function clearCalendarLastSyncedAt(calendarId?: string, workspaceRoot?: string): Promise<void>;

package/dist/google/collectionSync.d.ts

@@ -74,6 +74,12 @@ export declare const unpushedFor: (unpushed: UnpushedBySlug, slug: string) => Re
  *  A `null` (unknown) entry contributes nothing, because that collection reports
  *  a retryable error instead — which stops the baseline being saved at all. */
 export declare const allUnpushed: (unpushed: UnpushedBySlug) => ReadonlySet<string>;
+/** Whether a run may take the calendar, given what the shared marker says.
+ *
+ *  The scheduled door defers to it; every user-facing door claims regardless,
+ *  because a Refresh click that silently returns nothing reads as an empty
+ *  calendar, not as "another host has this". */
+export type ClaimGuard = (lastSyncedAt: string | null) => boolean;
 /** Sync ONE calendar and fan its events out to every collection bound to it.
  *
  *  The fan-out is not an optimisation, it is correctness: the sync token is
@@ -88,8 +94,9 @@ export declare const allUnpushed: (unpushed: UnpushedBySlug) => ReadonlySet<stri
  *  load the SAME stored token and walk the same window. That is idempotent —
  *  writes are upserts by event id — but it is a wasted full walk. Queued, the
  *  second pass resumes from the token the first just stored and fetches only
- *  what is genuinely new. */
-export declare function syncCalendarGroup(calendarId: string | undefined, collections: readonly LoadedCollection[], workspaceRoot: string): Promise<CalendarCollectionSyncResult[]>;
+ *  what is genuinely new. That queue is module state, so it orders the doors
+ *  into THIS process only; `claimThenSync` is what other hosts can see. */
+export declare function syncCalendarGroup(calendarId: string | undefined, collections: readonly LoadedCollection[], workspaceRoot: string, mayClaim?: ClaimGuard): Promise<CalendarCollectionSyncResult[]>;
 /** The baseline this window establishes: what Google now says per event, and
  *  `null` for a cancelled one so a recreate cannot resume from a dead baseline.
  *
@@ -139,8 +146,15 @@ export declare function orphanedCalendarId(deleted: CalendarDeclaring, remaining
  *  Returns the cleared calendar id, or null when nothing was cleared. Never
  *  throws: a failed cleanup must not fail the delete it follows. */
 export declare function releaseOrphanedCalendarToken(deleted: CalendarDeclaring, workspaceRoot: string): Promise<string | null>;
-/** Sync every collection that declares `googleCalendar`. */
-export declare function syncDueCalendarCollections(workspaceRoot: string): Promise<CalendarCollectionSyncResult[]>;
+/** Sync every collection whose calendar is due — no host in this workspace has
+ *  started one within `intervalMs` (#2678). Without that gate this walked every
+ *  declaring group on every tick, so a second host registering the same task
+ *  simply doubled the runs, concurrently.
+ *
+ *  Dueness is not decided here, only described: the guard is handed down and
+ *  evaluated where the marker is written, so the answer cannot go stale between
+ *  deciding and claiming (Codex review #2680). */
+export declare function syncDueCalendarCollections(workspaceRoot: string, intervalMs?: number): Promise<CalendarCollectionSyncResult[]>;
 /** The groups whose calendar has never synced. A missing token IS the "created
  *  since the last sync" signal — nothing else distinguishes a new collection
  *  from an edited one on the write path this feeds (#2427).
@@ -184,7 +198,12 @@ export interface ManualCalendarSyncDeps {
  *  calendar sends them fixing the wrong thing. */
 export declare function syncCalendarForCollection(slug: string, workspaceRoot: string, deps?: ManualCalendarSyncDeps): Promise<ManualCalendarSyncOutcome>;
 /** Scheduler registration, shaped like `feedRefreshTaskDef` so hosts wire it
- *  with a single line. */
+ *  with a single line.
+ *
+ *  `run` reads the interval back off the definition instead of closing over the
+ *  option: a host rewrites `schedule` from its own overrides file AFTER this
+ *  returns, and the due window has to follow it. Frozen at the default, a
+ *  shortened interval would tick often and skip nearly every tick. */
 export declare function googleCalendarSyncTaskDef(opts?: {
     workspaceRoot?: string;
     intervalMs?: number;

package/dist/google/index.cjs

@@ -845,34 +845,128 @@ function calendarSyncStatePath(workspaceRoot) {
 	return node_path.default.join(workspaceRoot ?? require_discovery.getWorkspaceRoot(), "data", "calendar", ".sync-state.json");
 }
 var calendarKey = canonicalCalendarId;
+/** Read one map out of whatever is on disk. Tolerant on purpose: a file written
+*  before `lastSyncedAt` existed simply lacks the key, and a hand-edited one may
+*  hold anything. A dropped entry costs a full re-walk or a duplicate run, never
+*  data — throwing here would stop the sync entirely. */
+function stringRecord(value) {
+	if (typeof value !== "object" || value === null) return {};
+	return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
 async function readState$1(workspaceRoot) {
 	const stored = await readJsonOrNull(calendarSyncStatePath(workspaceRoot));
-	return stored?.tokens ? stored : { tokens: {} };
+	return {
+		tokens: stringRecord(stored?.tokens),
+		lastSyncedAt: stringRecord(stored?.lastSyncedAt)
+	};
 }
 var writeQueue$1 = { tail: Promise.resolve() };
-async function updateState$1(mutate, workspaceRoot) {
+/** Decide from the stored state and write the result, both inside the queue, so
+*  nothing in this process can read between the two. A `null` state skips the
+*  write; `result` is what the caller learns about the decision. */
+async function updateStateWith(decide, workspaceRoot) {
 	const run = writeQueue$1.tail.then(async () => {
-		const state = await readState$1(workspaceRoot);
-		await writeJsonAtomicWithMode(calendarSyncStatePath(workspaceRoot), { tokens: mutate(state.tokens) }, SYNC_STATE_MODE);
+		const { state, result } = decide(await readState$1(workspaceRoot));
+		if (state) await writeJsonAtomicWithMode(calendarSyncStatePath(workspaceRoot), state, SYNC_STATE_MODE);
+		return result;
 	});
 	writeQueue$1.tail = run.catch(() => void 0);
 	return await run;
 }
+async function updateState$1(mutate, workspaceRoot) {
+	await updateStateWith((state) => ({
+		state: mutate(state),
+		result: void 0
+	}), workspaceRoot);
+}
+var withoutKey = (record, dropped) => Object.fromEntries(Object.entries(record).filter(([key]) => key !== dropped));
 async function loadCalendarSyncToken(calendarId, workspaceRoot) {
 	return (await readState$1(workspaceRoot)).tokens[calendarKey(calendarId)] ?? null;
 }
 async function saveCalendarSyncToken(calendarId, syncToken, workspaceRoot) {
 	const stored = calendarKey(calendarId);
-	await updateState$1((tokens) => ({
-		...tokens,
-		[stored]: syncToken
+	await updateState$1((state) => ({
+		...state,
+		tokens: {
+			...state.tokens,
+			[stored]: syncToken
+		}
 	}), workspaceRoot);
 }
 /** Drop one calendar's token — used when Google answers 410, so the next run
-*  starts a clean full sync. */
+*  starts a clean full sync. Leaves the sync marker alone: "restart the walk"
+*  says nothing about "nobody is running". */
 async function clearCalendarSyncToken(calendarId, workspaceRoot) {
 	const dropped = calendarKey(calendarId);
-	await updateState$1((tokens) => Object.fromEntries(Object.entries(tokens).filter(([key]) => key !== dropped)), workspaceRoot);
+	await updateState$1((state) => ({
+		...state,
+		tokens: withoutKey(state.tokens, dropped)
+	}), workspaceRoot);
+}
+async function loadCalendarLastSyncedAt(calendarId, workspaceRoot) {
+	return (await readState$1(workspaceRoot)).lastSyncedAt[calendarKey(calendarId)] ?? null;
+}
+/** Stamp when a sync of this calendar started, but only if `mayClaim` accepts
+*  what the marker currently says. Answers whether THIS call is the one that
+*  claimed it.
+*
+*  The decision and the stamp share one pass through the queue on purpose.
+*  Deciding from a snapshot read earlier — as a caller filtering a whole map of
+*  calendars up front must — leaves both hosts believing the calendar is free,
+*  which is the race this exists to close (Codex review #2680). What remains is
+*  the read→write gap BETWEEN processes; closing that needs a real file lock
+*  (#2679), and this stays a soft dedup until then.
+*
+*  The time is passed in rather than read here so the rule stays testable
+*  without freezing the clock. */
+async function claimCalendarSyncIfDue(calendarId, startedAt, mayClaim, workspaceRoot) {
+	const stored = calendarKey(calendarId);
+	return await updateStateWith((state) => {
+		const claimed = mayClaim(state.lastSyncedAt[stored] ?? null);
+		return {
+			state: claimed ? {
+				...state,
+				lastSyncedAt: {
+					...state.lastSyncedAt,
+					[stored]: startedAt
+				}
+			} : null,
+			result: claimed
+		};
+	}, workspaceRoot);
+}
+/** Drop one calendar's marker, so the next tick — on either host — may sync it
+*  immediately instead of waiting the window out. */
+async function clearCalendarLastSyncedAt(calendarId, workspaceRoot) {
+	const dropped = calendarKey(calendarId);
+	await updateState$1((state) => ({
+		...state,
+		lastSyncedAt: withoutKey(state.lastSyncedAt, dropped)
+	}), workspaceRoot);
+}
+//#endregion
+//#region src/google/calendarSyncDue.ts
+/** Slack between a tick and the marker it writes. Without it a lone host reads
+*  its OWN marker as "not due yet" — elapsed lands a hair under the interval
+*  every time — and syncs every other hour. */
+var TICK_JITTER_TOLERANCE_MS = 300 * 1e3;
+/** How long a fresh marker suppresses a sync: one interval, less the slack.
+*  The slack is halved rather than subtracted flat for a very short configured
+*  interval, where a fixed five minutes would swallow the window whole. */
+function calendarSyncDueWindowMs(intervalMs) {
+	return intervalMs - Math.min(TICK_JITTER_TOLERANCE_MS, intervalMs / 2);
+}
+/** True iff no recent enough run stands in for this one.
+*
+*  A marker that cannot be read as a time is treated as due: a stuck calendar is
+*  worse than a duplicate run, which the sync is built to tolerate anyway
+*  (writes are upserts by event id). */
+function isCalendarSyncDue(lastSyncedAt, windowMs, now = Date.now()) {
+	if (!lastSyncedAt) return true;
+	const elapsed = now - Date.parse(lastSyncedAt);
+	if (!Number.isFinite(elapsed)) return true;
+	if (elapsed < -windowMs) return true;
+	return elapsed >= windowMs;
 }
 //#endregion
 //#region src/google/calendarPushState.ts
@@ -1786,6 +1880,7 @@ async function restartFullSync(accessToken, calendarId, workspaceRoot) {
 	await clearCalendarShadow(calendarId, workspaceRoot);
 	return await syncCalendarEvents(accessToken, { calendarId });
 }
+var ALWAYS_CLAIM = () => true;
 /** Sync ONE calendar and fan its events out to every collection bound to it.
 *
 *  The fan-out is not an optimisation, it is correctness: the sync token is
@@ -1800,9 +1895,59 @@ async function restartFullSync(accessToken, calendarId, workspaceRoot) {
 *  load the SAME stored token and walk the same window. That is idempotent —
 *  writes are upserts by event id — but it is a wasted full walk. Queued, the
 *  second pass resumes from the token the first just stored and fetches only
-*  what is genuinely new. */
-async function syncCalendarGroup(calendarId, collections, workspaceRoot) {
-	return await withCalendarLock(calendarId, () => syncCalendarGroupNow(calendarId, collections, workspaceRoot));
+*  what is genuinely new. That queue is module state, so it orders the doors
+*  into THIS process only; `claimThenSync` is what other hosts can see. */
+async function syncCalendarGroup(calendarId, collections, workspaceRoot, mayClaim = ALWAYS_CLAIM) {
+	return await withCalendarLock(calendarId, () => claimThenSync(calendarId, collections, workspaceRoot, mayClaim));
+}
+/** Take the workspace-shared marker BEFORE the calendar is touched, sync only if
+*  this run got it, and drop it again if the run could not happen at all.
+*
+*  Claiming first is the whole point: hosts tick in the same minute (interval
+*  schedules align to wall-clock boundaries), so a marker written on completion
+*  would leave the entire run — minutes, for a first full walk — open for a
+*  second host to start alongside this one and lose the push baseline it writes.
+*
+*  Released only when the sync could not run at all. A run that finished with
+*  retryable per-collection errors KEEPS the marker: it already held the token
+*  and the baseline back, so it replays on the next tick either way, and
+*  releasing would hand a permanently-failing calendar back to both hosts at
+*  once — the very overlap this guards (observed during Claude review). */
+async function claimThenSync(calendarId, collections, workspaceRoot, mayClaim) {
+	if (!await claimCalendarSync(calendarId, workspaceRoot, mayClaim)) {
+		log.info("google", "skipping a calendar this workspace synced recently — another host may be on it", { calendarId });
+		return [];
+	}
+	try {
+		return await syncCalendarGroupNow(calendarId, collections, workspaceRoot);
+	} catch (error) {
+		await releaseCalendarSyncClaim(calendarId, workspaceRoot);
+		throw error;
+	}
+}
+/** Never throws, and fails OPEN: the marker guards against duplicate work, it is
+*  not a precondition for syncing correctly. A workspace that cannot store it
+*  syncs the way it did before #2678. */
+async function claimCalendarSync(calendarId, workspaceRoot, mayClaim) {
+	try {
+		return await claimCalendarSyncIfDue(calendarId, (/* @__PURE__ */ new Date()).toISOString(), mayClaim, workspaceRoot);
+	} catch (error) {
+		log.warn("google", "could not stamp the calendar sync marker — another host may sync this calendar in parallel", {
+			calendarId,
+			error: String(error)
+		});
+		return true;
+	}
+}
+async function releaseCalendarSyncClaim(calendarId, workspaceRoot) {
+	try {
+		await clearCalendarLastSyncedAt(calendarId, workspaceRoot);
+	} catch (error) {
+		log.warn("google", "could not release the calendar sync marker after a failed run", {
+			calendarId,
+			error: String(error)
+		});
+	}
 }
 async function syncCalendarGroupNow(calendarId, collections, workspaceRoot) {
 	const unpushed = await pushAutoCollections(collections, workspaceRoot);
@@ -1963,6 +2108,7 @@ async function releaseOrphanedCalendarToken(deleted, workspaceRoot) {
 		if (orphaned === null) return null;
 		await clearCalendarSyncToken(orphaned, workspaceRoot);
 		await clearCalendarShadow(orphaned, workspaceRoot);
+		await clearCalendarLastSyncedAt(orphaned, workspaceRoot);
 		log.info("google", "cleared the sync token of a calendar no collection reads any more", { calendarId: orphaned });
 		return orphaned;
 	} catch (error) {
@@ -1979,19 +2125,27 @@ async function declaringGroups(workspaceRoot) {
 *  Authoring the collection before linking the account is an expected state,
 *  not a failure. Checking once here keeps it a quiet skip instead of an
 *  access-token throw per calendar, every hour, until the user links (#2188).
-*  A user-triggered sync answers differently — it says so out loud. */
+*  A user-triggered sync answers differently — it says so out loud.
+*
+*  Deliberately not phrased as a per-host state: the link lives in
+*  `~/.config/mulmo`, which carries no app name, so every host on the machine
+*  shares one answer. Reading it as "linked on this host only" is what made the
+*  calendar look implicitly exclusive when it never was (#2678). */
 async function backgroundSyncAllowed(groups) {
 	if (groups.size === 0) return false;
 	if (await isGoogleLinked()) return true;
-	log.info("google", "skipping calendar sync — no Google account linked on this host", { calendars: groups.size });
+	log.info("google", "skipping calendar sync — no Google account linked", { calendars: groups.size });
 	return false;
 }
 /** Run each group, isolating failures per calendar — one unreachable calendar
-*  (or a revoked grant) must not stop the others. */
-async function runCalendarGroups(groups, workspaceRoot) {
+*  (or a revoked grant) must not stop the others. `mayClaim` is evaluated per
+*  calendar as it comes up, never once for the whole map: an earlier calendar's
+*  full walk takes minutes, and a decision made before it started says nothing
+*  about who holds this one now. */
+async function runCalendarGroups(groups, workspaceRoot, mayClaim = ALWAYS_CLAIM) {
 	const results = [];
 	for (const [calendarId, collections] of groups) try {
-		results.push(...await syncCalendarGroup(calendarId, collections, workspaceRoot));
+		results.push(...await syncCalendarGroup(calendarId, collections, workspaceRoot, mayClaim));
 	} catch (error) {
 		log.warn("google", "calendar sync failed", {
 			calendarId,
@@ -2007,10 +2161,19 @@ async function runCalendarGroups(groups, workspaceRoot) {
 	}
 	return results;
 }
-/** Sync every collection that declares `googleCalendar`. */
-async function syncDueCalendarCollections(workspaceRoot) {
+/** Sync every collection whose calendar is due — no host in this workspace has
+*  started one within `intervalMs` (#2678). Without that gate this walked every
+*  declaring group on every tick, so a second host registering the same task
+*  simply doubled the runs, concurrently.
+*
+*  Dueness is not decided here, only described: the guard is handed down and
+*  evaluated where the marker is written, so the answer cannot go stale between
+*  deciding and claiming (Codex review #2680). */
+async function syncDueCalendarCollections(workspaceRoot, intervalMs = DEFAULT_SYNC_INTERVAL_MS) {
 	const groups = await declaringGroups(workspaceRoot);
-	return await backgroundSyncAllowed(groups) ? await runCalendarGroups(groups, workspaceRoot) : [];
+	if (!await backgroundSyncAllowed(groups)) return [];
+	const windowMs = calendarSyncDueWindowMs(intervalMs);
+	return await runCalendarGroups(groups, workspaceRoot, (lastSyncedAt) => isCalendarSyncDue(lastSyncedAt, windowMs));
 }
 /** The groups whose calendar has never synced. A missing token IS the "created
 *  since the last sync" signal — nothing else distinguishes a new collection
@@ -2056,10 +2219,21 @@ async function syncCalendarForCollection(slug, workspaceRoot, deps = liveManualS
 		results: await deps.runGroups(new Map(owning), workspaceRoot)
 	};
 }
+/** The interval this task is scheduled on right now. A non-interval schedule
+*  cannot be reached — the factory below builds an interval one — but the type
+*  allows it, so it falls back rather than asserting. */
+function scheduledIntervalMs(task) {
+	return task.schedule.type === _receptron_task_scheduler.SCHEDULE_TYPES.interval ? task.schedule.intervalMs : DEFAULT_SYNC_INTERVAL_MS;
+}
 /** Scheduler registration, shaped like `feedRefreshTaskDef` so hosts wire it
-*  with a single line. */
+*  with a single line.
+*
+*  `run` reads the interval back off the definition instead of closing over the
+*  option: a host rewrites `schedule` from its own overrides file AFTER this
+*  returns, and the due window has to follow it. Frozen at the default, a
+*  shortened interval would tick often and skip nearly every tick. */
 function googleCalendarSyncTaskDef(opts) {
-	return {
+	const def = {
 		id: GOOGLE_CALENDAR_SYNC_TASK_ID,
 		name: "Google Calendar sync",
 		description: "Pulls changed Google Calendar events into any collection declaring `googleCalendar`, without invoking the LLM.",
@@ -2068,8 +2242,9 @@ function googleCalendarSyncTaskDef(opts) {
 			intervalMs: opts?.intervalMs ?? DEFAULT_SYNC_INTERVAL_MS
 		},
 		missedRunPolicy: _receptron_task_scheduler.MISSED_RUN_POLICIES.runOnce,
-		run: () => syncDueCalendarCollections(opts?.workspaceRoot ?? require_discovery.getWorkspaceRoot()).then(() => {})
+		run: () => syncDueCalendarCollections(opts?.workspaceRoot ?? require_discovery.getWorkspaceRoot(), scheduledIntervalMs(def)).then(() => {})
 	};
+	return def;
 }
 //#endregion
 //#region src/google/tasks.ts
@@ -2297,11 +2472,14 @@ exports.buildTaskPatch = buildTaskPatch;
 exports.bySourceField = bySourceField;
 exports.calendarApiError = calendarApiError;
 exports.calendarPushStatePath = calendarPushStatePath;
+exports.calendarSyncDueWindowMs = calendarSyncDueWindowMs;
 exports.calendarSyncStatePath = calendarSyncStatePath;
 exports.canonicalCalendarId = canonicalCalendarId;
 exports.canonicalTaskListId = canonicalTaskListId;
+exports.claimCalendarSyncIfDue = claimCalendarSyncIfDue;
 exports.classifyDelete = classifyDelete;
 exports.classifyWrite = classifyWrite;
+exports.clearCalendarLastSyncedAt = clearCalendarLastSyncedAt;
 exports.clearCalendarShadow = clearCalendarShadow;
 exports.clearCalendarSyncToken = clearCalendarSyncToken;
 exports.clientSecretPresence = clientSecretPresence;
@@ -2331,6 +2509,7 @@ exports.googleConfigDir = googleConfigDir;
 exports.googleSecretsDir = googleSecretsDir;
 exports.googleTokenPath = googleTokenPath;
 exports.groupByCalendar = groupByCalendar;
+exports.isCalendarSyncDue = isCalendarSyncDue;
 exports.isClientSettableEventId = isClientSettableEventId;
 exports.isDeniedAccessRole = isDeniedAccessRole;
 exports.isGoogleApiError = isGoogleApiError;
@@ -2343,6 +2522,7 @@ exports.listCalendars = listCalendars;
 exports.listDriveFiles = listDriveFiles;
 exports.listTaskLists = listTaskLists;
 exports.listTasks = listTasks;
+exports.loadCalendarLastSyncedAt = loadCalendarLastSyncedAt;
 exports.loadCalendarShadow = loadCalendarShadow;
 exports.loadCalendarSyncToken = loadCalendarSyncToken;
 exports.loadClientSecret = loadClientSecret;