@mulmoclaude/core 1.3.0 → 1.5.0

package/README.md

@@ -0,0 +1,49 @@
+# @mulmoclaude/core
+
+Shared server-side core for **MulmoClaude** and **MulmoTerminal** — the
+subsystems the two hosts always ship together, consolidated behind subpath
+exports so they cannot drift apart.
+
+Not a general-purpose library: it exists so one implementation of collections,
+wiki, feeds, Google integration, scheduling and the rest serves both hosts.
+Every host specific (paths, logging, notification transport, …) is injected
+rather than imported, which is what lets the same code run under either.
+
+## Subpath exports
+
+| Area | Entries |
+| --- | --- |
+| Collections | `./collection`, `./collection/server`, `./collection/paths`, `./collection/registry`, `./collection/registry/server`, `./collection-watchers` |
+| Knowledge | `./wiki`, `./wiki/server`, `./wiki/paths`, `./feeds`, `./feeds/server`, `./feeds/paths` |
+| Google | `./google` — OAuth (loopback + PKCE), token store, Calendar / Tasks / Drive REST |
+| Runtime | `./scheduler`, `./notifier`, `./skill-bridge`, `./file-change`, `./workspace-setup`, `./artifacts` |
+| Remote | `./remote-host`, `./remote-host/server`, `./remote-view` |
+| Voice | `./whisper`, `./whisper/client` |
+| Plugin support | `./plugin-vue`, `./plugin-vue/i18n` |
+| Utilities | `./utils`, `./files`, `./fetch` |
+
+**Server-only**, except the browser-safe entries: `./artifacts`,
+`./whisper/client`, `./workspace-setup/slug`, `./translation/client`,
+`./remote-view`, `./remote-host` and `./plugin-vue`.
+
+The package also ships `assets/helps/*` — the help documents the agent reads at
+runtime — which is why a change there alone still warrants a release.
+
+## About MulmoClaude and MulmoTerminal
+
+- **[MulmoClaude](https://github.com/receptron/mulmoclaude)** — an AI-native
+  application platform built on Claude Code. Chat summons the right GUI for each
+  task (documents, charts, forms, wikis, spreadsheets, 3D scenes), and
+  everything your assistant accumulates stays as plain files in your own
+  workspace, on your own machine.
+- **[MulmoTerminal](https://github.com/receptron/mulmoterminal)** — run a whole
+  team of coding agents from your browser. Many Claude Code / Codex sessions at
+  once in a grid, colour-coded so you see which are working, which need you and
+  which are done, plus git worktrees, one-click PRs and cost readouts. One `npx`
+  command, no Electron, no config.
+
+📖 **User guide**: <https://receptron.github.io/mulmoterminal/> (日本語 / English)
+
+## License
+
+MIT

package/assets/helps/google-calendar-collection.md

@@ -5,8 +5,10 @@ Add a `googleCalendar` block to its `schema.json` and the host pulls changed
 events on a schedule and writes them as records — **without calling you**. No
 tool call, no tokens spent per sync, so hourly syncing is free.
 
-This is the only calendar mechanism: there is no calendar tool and no bundled
-calendar collection. You author the schema when the user asks for one.
+This is the mechanism for *keeping a collection fresh*. For one-off reads and
+for creating / editing / deleting events, use the `google` tool — see
+[The `google` tool](google.md). There is no bundled calendar collection: you
+author the schema when the user asks for one.
 
 ## Requirements
 
@@ -57,6 +59,15 @@ Declaring it in `map` is a schema error.
 Use `datetime` (not `date`) for start/end when events have real clock times —
 the calendar day view then draws each record as a proportional time block.
 
+## When sync runs
+
+- **On creation** — the first sync starts as soon as the schema lands, so the
+  collection is not empty while the user waits for the schedule. The same
+  applies when you add a `googleCalendar` block to an existing collection.
+- **Hourly** after that, in the background.
+- **On demand** — the collection view has a Sync button. Tell the user about it
+  if they want the calendar refreshed right now.
+
 ## What sync does
 
 - New or edited events are written, keyed by event id (existing records are

package/assets/helps/google.md

@@ -0,0 +1,94 @@
+# The `google` tool — Calendar, Tasks and Drive
+
+One tool, one `kind` per operation, against the Google account the user linked
+on this machine. The refresh token is stored locally in `~/.config/mulmo/` and
+goes only to Google, to mint access tokens — never to claude.ai or any other
+service. This works with no claude.ai Google connector involved.
+
+Call `kind: "status"` when unsure whether the account is linked. If a call fails
+with "Google account not linked", ask the user to link it in settings and retry
+the original call — do not fall back to guessing.
+
+## Two mechanisms, different jobs
+
+| You want | Use |
+| --- | --- |
+| Read or change specific events / tasks / files, right now | this tool |
+| A collection that mirrors a calendar and keeps itself fresh | a `googleCalendar` block — see [Google Calendar sync](google-calendar-collection.md) |
+
+The collection route costs no tokens per refresh, so prefer it for anything
+recurring. Use this tool for one-off work and for everything the collection
+route cannot do (creating, editing and deleting).
+
+## Calendar
+
+Events default to the user's **primary** calendar. Pass `calendarId` — obtained
+from `calendarListCalendars` — to target another.
+
+| kind | What it does |
+| --- | --- |
+| `calendarListCalendars` | The calendars the user has added/subscribed to: `id`, `summary`, `primary`, colours, `accessRole` |
+| `calendarColors` | Palettes mapping a `colorId` to hex, for events and for calendars |
+| `calendarListEvents` | Upcoming events. Optional `calendarId`, `timeMin`, `maxResults` (1-50, default 10) |
+| `calendarSync` | Only what CHANGED since the last sync, via a stored token. Returns counts plus a capped sample |
+| `calendarCreateEvent` | Create. Requires `summary`, `start`, `end`; optional `description`, `calendarId`, `colorId` |
+| `calendarUpdateEvent` | Edit in place. Requires `eventId` + at least one of `summary`, `start`, `end`, `description`, `colorId` |
+| `calendarDeleteEvent` | Delete. Requires `eventId` |
+
+**Date-times must carry a timezone offset** — `2026-07-17T09:00:00+09:00`, not
+`2026-07-17` and not `2026-07-17T09:00:00`. Calendar rejects the others with an
+opaque 400.
+
+**Editing is a patch.** Fields you omit keep their current value, so changing a
+title needs `eventId` + `summary` and nothing else. `description: ""` clears the
+body. Moving one end of an event still has to leave the start before the end.
+
+**`eventId` comes from `calendarListEvents` or `calendarSync`** — never invent
+one. For a recurring event those kinds return per-occurrence ids, so editing or
+deleting one affects that single occurrence.
+
+**Deleting is not reversible** and removes the event for every attendee. Confirm
+with the user before calling `calendarDeleteEvent`, and say which event you are
+about to remove.
+
+## Tasks
+
+Operate on the user's default task list unless `taskListId` is given.
+
+| kind | What it does |
+| --- | --- |
+| `taskListsList` | The user's task lists (`id`, `title`). Only needed for a non-default list |
+| `tasksList` | List tasks. Optional `taskListId`, `maxResults` (1-50, default 10), `showCompleted` (default false) |
+| `tasksCreate` | Add a task. Requires `title`; optional `notes`, `due`, `taskListId` |
+| `tasksUpdate` | Edit. Requires `taskId` + at least one of `title`, `notes`, `due`. `notes: ""` clears them; `due` can be changed but **not** cleared |
+| `tasksComplete` | Mark done. Requires `taskId` |
+| `tasksDelete` | Delete. Requires `taskId` — not reversible, so confirm first |
+
+`tasksUpdate` does not change status: `tasksComplete` owns that transition.
+
+**Google stores a DATE only for `due`** — the time part is accepted and then
+ignored, so never promise the user a time of day on a task.
+
+## Drive
+
+In practice this app sees **only the files it created itself**, never the user's
+wider Drive. Never claim to have searched their Drive.
+
+(The `drive.file` scope also covers files the user hands to an app through a
+Google Picker, but this app has no Picker — so app-created is the whole set.)
+
+| kind | What it does |
+| --- | --- |
+| `driveList` | Files this app created. Optional `maxResults` (1-50, default 10) |
+| `driveCreate` | Create a text file. Requires `name`, `content`; optional `mimeType` (default `text/plain`) |
+| `driveRead` | Read one of this app's files. Requires `fileId`. Text only |
+
+## Failure modes
+
+- **"Google account not linked"** — the user has not linked, or the token was
+  revoked. Ask them to link in settings; do not retry blindly.
+- **HTTP 403 naming an API** — that API is not enabled for the user's Cloud
+  project. The message says which one.
+- **HTTP 400 on a create/update** — almost always a date-time without an offset,
+  or a start that is not before the end.
+- **HTTP 410 on delete** — the event was already gone.

package/assets/helps/index.md

@@ -72,6 +72,7 @@ See [Wiki](config/helps/wiki.md) for details on how it works.
 - [Remote host](config/helps/remote-host.md) — drive MulmoClaude from a phone at mulmoserver.web.app: Google sign-in connect, host online vs. offline (queued chats, 7-day expiry), photo attachments, and the security model
 - [Feeds](config/helps/feeds.md) — register a self-refreshing data feed (RSS/Atom/JSON) by authoring `feeds/<slug>/schema.json`: schema shape, the `ingest` block, raw-item field mapping, and `maxItems` retention
 - [Google Calendar sync](config/helps/google-calendar-collection.md) — mirror a Google calendar into a collection with a `googleCalendar` block: field mapping, why the primary field holds the event id, and how deletions propagate
+- [The `google` tool](config/helps/google.md) — every `kind` for Calendar, Tasks and Drive: reading, creating, editing and deleting events and tasks, the timezone-offset rule, patch semantics, and what `drive.file` scope cannot see
 - [GitHub repositories in the workspace](config/helps/github.md) — clone-destination rules under `github/<name>/` and how to handle existing directories with matching or different remotes
 - [Collection skills](config/helps/collection-skills.md) — build a data app (model + UI + relations + computed fields + action buttons) by authoring a `schema.json` collection skill: the DSL, field types, derived formulas, actions, records
 - [Custom views](config/helps/custom-view.md) — give a collection a view the built-ins don't cover (year/quarter overview, Gantt): an HTML file under `views/`, registered in `schema.json`, rendered in a sandboxed iframe over the records

package/dist/google/calendar.d.ts

@@ -14,6 +14,20 @@ export interface CalendarEventInput {
     /** Event colour (Google event palette id "1".."11"); omit to inherit the calendar's colour. */
     colorId?: string;
 }
+export interface UpdateCalendarEventInput {
+    eventId: string;
+    summary?: string;
+    startDateTime?: string;
+    endDateTime?: string;
+    /** `""` clears the description; omit to leave it untouched. */
+    description?: string;
+    calendarId?: string;
+    colorId?: string;
+}
+export interface DeleteCalendarEventInput {
+    eventId: string;
+    calendarId?: string;
+}
 export interface ListEventsInput {
     timeMin?: string;
     maxResults?: number;
@@ -58,6 +72,20 @@ export declare const toCalendarSummary: (value: unknown) => CalendarSummary;
  *  helper now carries the wording. */
 export declare const calendarApiError: (status: number, body: string) => Error;
 export declare function createCalendarEvent(accessToken: string, input: CalendarEventInput): Promise<CalendarEventSummary>;
+/** PATCH body for an event edit — only the fields the caller actually supplied.
+ *
+ *  `undefined` means "leave as is" and `""` means "clear it", so the two cannot
+ *  be collapsed: dropping `description: ""` would silently ignore a request to
+ *  empty the body text. Pure so the distinction is testable without network. */
+export declare const buildEventPatch: (input: UpdateCalendarEventInput) => Record<string, unknown>;
+/** Edit an existing event in place. PATCH, not PUT — a PUT would need the whole
+ *  event and would drop every field the caller never read (attendees,
+ *  reminders, recurrence). */
+export declare function updateCalendarEvent(accessToken: string, input: UpdateCalendarEventInput): Promise<CalendarEventSummary>;
+/** Remove an event. Google answers 204 with no body, so there is nothing to
+ *  return; a second delete of the same id answers 410, which surfaces as a
+ *  GoogleApiError rather than being swallowed. */
+export declare function deleteCalendarEvent(accessToken: string, input: DeleteCalendarEventInput): Promise<void>;
 export declare function listCalendarEvents(accessToken: string, input?: ListEventsInput): Promise<CalendarEventSummary[]>;
 export interface SyncEventsInput {
     /** Calendar to sync; defaults to the user's primary. */

package/dist/google/collectionSync.d.ts

@@ -39,6 +39,13 @@ type ApplyOutcome = {
 };
 export declare function classifyWrite(eventId: string, kind: WriteItemResult["kind"]): ApplyOutcome;
 export declare function classifyDelete(eventId: string, kind: DeleteItemResult["kind"]): ApplyOutcome;
+/** Serialise `run` against whatever is already running for `key`.
+ *
+ *  `locks` is passed in so the queuing rule is testable without module state;
+ *  the key is dropped once nothing is queued behind it, so the map cannot grow
+ *  an entry per calendar forever. A failed predecessor still releases the
+ *  queue — `then(run, run)`. */
+export declare function withKeyedLock<T>(locks: Map<string, Promise<unknown>>, key: string, run: () => Promise<T>): Promise<T>;
 /** 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
@@ -46,7 +53,14 @@ export declare function classifyDelete(eventId: string, kind: DeleteItemResult["
  *  first collection advance the shared token and leave every later collection
  *  on the same calendar reading an already-consumed window — silently missing
  *  those events forever. Fetch once, apply to all, then advance the token.
- *  (Codex + CodeRabbit review on #2184.) */
+ *  (Codex + CodeRabbit review on #2184.)
+ *
+ *  Queued per calendar for the same reason the fan-out exists: two passes over
+ *  one calendar (a Refresh click landing during the scheduled run) would each
+ *  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[]>;
 /** Liveness of the collections a sync just wrote to, checked against the skill
  *  dir `deleteCollection` removes. `exists` is injected so the rule is testable
@@ -87,10 +101,50 @@ 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`. Failures are isolated
- *  per calendar — one unreachable calendar (or a revoked grant) must not stop
- *  the others. */
+/** Sync every collection that declares `googleCalendar`. */
 export declare function syncDueCalendarCollections(workspaceRoot: string): 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).
+ *
+ *  Self-silencing by construction: the first sync stores a token, so a calendar
+ *  matches at most once. `loadToken` is injected so the rule is testable without
+ *  a workspace on disk. */
+export declare function unsyncedGroups<T>(groups: Map<string, T>, loadToken: (calendarId: string) => Promise<string | null>): Promise<Map<string, T>>;
+/** Sync only the calendars that have never synced — the first sync for a
+ *  just-created collection, which otherwise stays empty until the hourly
+ *  scheduler run (#2427). Cheap and safe to call on every config write. */
+export declare function syncNewCalendarCollections(workspaceRoot: string): Promise<CalendarCollectionSyncResult[]>;
+/** A user-triggered sync's outcome. `not-a-calendar` and `not-linked` are
+ *  states the caller must report rather than swallow: a Refresh click that
+ *  quietly returns "0 written" reads as an empty calendar, not as a setup gap. */
+export type ManualCalendarSyncOutcome = {
+    kind: "synced";
+    results: CalendarCollectionSyncResult[];
+} | {
+    kind: "not-a-calendar";
+} | {
+    kind: "not-linked";
+};
+/** The I/O a manual sync crosses, injectable so the three outcomes can be
+ *  exercised with fakes instead of a workspace on disk and a live Google grant
+ *  (CodeRabbit review #2566). */
+export interface ManualCalendarSyncDeps {
+    loadGroups: (workspaceRoot: string) => Promise<Map<string, LoadedCollection[]>>;
+    isLinked: () => Promise<boolean>;
+    runGroups: (groups: Map<string, LoadedCollection[]>, workspaceRoot: string) => Promise<CalendarCollectionSyncResult[]>;
+}
+/** Sync the calendar ONE collection reads, on demand (the Refresh button).
+ *
+ *  Deliberately syncs the whole group, not just `slug`: the sync token is keyed
+ *  by calendar, so consuming a window for one collection would leave the others
+ *  on that calendar reading an already-consumed one. Returns every result of the
+ *  group so the caller can report the requested slug's own counts.
+ *
+ *  "Does this collection sync at all" is answered BEFORE "is Google linked":
+ *  telling someone to link their account for a collection that never declared a
+ *  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. */
 export declare function googleCalendarSyncTaskDef(opts?: {

package/dist/google/index.cjs

@@ -655,6 +655,34 @@ async function createCalendarEvent(accessToken, input) {
 		body: JSON.stringify(body)
 	}));
 }
+var eventUrl = (calendarId, eventId) => `${eventsUrl(calendarId)}/${encodeURIComponent(eventId)}`;
+/** PATCH body for an event edit — only the fields the caller actually supplied.
+*
+*  `undefined` means "leave as is" and `""` means "clear it", so the two cannot
+*  be collapsed: dropping `description: ""` would silently ignore a request to
+*  empty the body text. Pure so the distinction is testable without network. */
+var buildEventPatch = (input) => ({
+	...input.summary !== void 0 ? { summary: input.summary } : {},
+	...input.description !== void 0 ? { description: input.description } : {},
+	...input.startDateTime !== void 0 ? { start: { dateTime: input.startDateTime } } : {},
+	...input.endDateTime !== void 0 ? { end: { dateTime: input.endDateTime } } : {},
+	...input.colorId ? { colorId: input.colorId } : {}
+});
+/** Edit an existing event in place. PATCH, not PUT — a PUT would need the whole
+*  event and would drop every field the caller never read (attendees,
+*  reminders, recurrence). */
+async function updateCalendarEvent(accessToken, input) {
+	return toEventSummary(await googleRequest(CALENDAR_API_LABEL, accessToken, eventUrl(input.calendarId, input.eventId), {
+		method: "PATCH",
+		body: JSON.stringify(buildEventPatch(input))
+	}));
+}
+/** Remove an event. Google answers 204 with no body, so there is nothing to
+*  return; a second delete of the same id answers 410, which surfaces as a
+*  GoogleApiError rather than being swallowed. */
+async function deleteCalendarEvent(accessToken, input) {
+	await googleRequest(CALENDAR_API_LABEL, accessToken, eventUrl(input.calendarId, input.eventId), { method: "DELETE" });
+}
 async function listCalendarEvents(accessToken, input = {}) {
 	const params = new URLSearchParams({
 		timeMin: input.timeMin ?? (/* @__PURE__ */ new Date()).toISOString(),
@@ -883,6 +911,26 @@ async function restartFullSync(accessToken, calendarId, workspaceRoot) {
 	await clearCalendarSyncToken(calendarId, workspaceRoot);
 	return await syncCalendarEvents(accessToken, { calendarId });
 }
+/** Serialise `run` against whatever is already running for `key`.
+*
+*  `locks` is passed in so the queuing rule is testable without module state;
+*  the key is dropped once nothing is queued behind it, so the map cannot grow
+*  an entry per calendar forever. A failed predecessor still releases the
+*  queue — `then(run, run)`. */
+async function withKeyedLock(locks, key, run) {
+	const result = (locks.get(key) ?? Promise.resolve()).then(run, run);
+	const tail = result.then(() => void 0, () => void 0);
+	locks.set(key, tail);
+	try {
+		return await result;
+	} finally {
+		if (locks.get(key) === tail) locks.delete(key);
+	}
+}
+/** In-flight sync per canonical calendar id. Module state on purpose: the
+*  scheduler, the create trigger and the Refresh button are three doors into
+*  the same calendar (CodeRabbit review #2566). */
+var calendarLocks = /* @__PURE__ */ new Map();
 /** 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
@@ -890,8 +938,18 @@ async function restartFullSync(accessToken, calendarId, workspaceRoot) {
 *  first collection advance the shared token and leave every later collection
 *  on the same calendar reading an already-consumed window — silently missing
 *  those events forever. Fetch once, apply to all, then advance the token.
-*  (Codex + CodeRabbit review on #2184.) */
+*  (Codex + CodeRabbit review on #2184.)
+*
+*  Queued per calendar for the same reason the fan-out exists: two passes over
+*  one calendar (a Refresh click landing during the scheduled run) would each
+*  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 withKeyedLock(calendarLocks, canonicalCalendarId(calendarId), () => syncCalendarGroupNow(calendarId, collections, workspaceRoot));
+}
+async function syncCalendarGroupNow(calendarId, collections, workspaceRoot) {
 	const accessToken = await getGoogleAccessToken();
 	const first = await syncCalendarEvents(accessToken, {
 		calendarId,
@@ -1014,18 +1072,27 @@ async function releaseOrphanedCalendarToken(deleted, workspaceRoot) {
 		return null;
 	}
 }
-/** Sync every collection that declares `googleCalendar`. Failures are isolated
-*  per calendar — one unreachable calendar (or a revoked grant) must not stop
-*  the others. */
-async function syncDueCalendarCollections(workspaceRoot) {
-	const declaring = (await require_discovery.discoverCollections({ workspaceRoot })).filter((collection) => collection.schema.googleCalendar);
-	if (declaring.length === 0) return [];
-	if (!await isGoogleLinked()) {
-		log.info("google", "skipping calendar sync — no Google account linked on this host", { collections: declaring.length });
-		return [];
-	}
+/** Every declaring collection, grouped by the calendar it reads. */
+async function declaringGroups(workspaceRoot) {
+	return groupByCalendar((await require_discovery.discoverCollections({ workspaceRoot })).filter((collection) => collection.schema.googleCalendar));
+}
+/** Whether a background sync of these groups may run at all.
+*
+*  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. */
+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 });
+	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) {
 	const results = [];
-	for (const [calendarId, collections] of groupByCalendar(declaring)) try {
+	for (const [calendarId, collections] of groups) try {
 		results.push(...await syncCalendarGroup(calendarId, collections, workspaceRoot));
 	} catch (error) {
 		log.warn("google", "calendar sync failed", {
@@ -1042,6 +1109,55 @@ async function syncDueCalendarCollections(workspaceRoot) {
 	}
 	return results;
 }
+/** Sync every collection that declares `googleCalendar`. */
+async function syncDueCalendarCollections(workspaceRoot) {
+	const groups = await declaringGroups(workspaceRoot);
+	return await backgroundSyncAllowed(groups) ? await runCalendarGroups(groups, workspaceRoot) : [];
+}
+/** 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).
+*
+*  Self-silencing by construction: the first sync stores a token, so a calendar
+*  matches at most once. `loadToken` is injected so the rule is testable without
+*  a workspace on disk. */
+async function unsyncedGroups(groups, loadToken) {
+	const checked = await Promise.all([...groups].map(async (entry) => await loadToken(entry[0]) === null ? entry : null));
+	return new Map(checked.filter((entry) => entry !== null));
+}
+/** Sync only the calendars that have never synced — the first sync for a
+*  just-created collection, which otherwise stays empty until the hourly
+*  scheduler run (#2427). Cheap and safe to call on every config write. */
+async function syncNewCalendarCollections(workspaceRoot) {
+	const pending = await unsyncedGroups(await declaringGroups(workspaceRoot), (calendarId) => loadCalendarSyncToken(calendarId, workspaceRoot));
+	if (!await backgroundSyncAllowed(pending)) return [];
+	log.info("google", "running the first sync for newly declared calendars", { calendars: [...pending.keys()] });
+	return await runCalendarGroups(pending, workspaceRoot);
+}
+var liveManualSyncDeps = {
+	loadGroups: declaringGroups,
+	isLinked: isGoogleLinked,
+	runGroups: runCalendarGroups
+};
+/** Sync the calendar ONE collection reads, on demand (the Refresh button).
+*
+*  Deliberately syncs the whole group, not just `slug`: the sync token is keyed
+*  by calendar, so consuming a window for one collection would leave the others
+*  on that calendar reading an already-consumed one. Returns every result of the
+*  group so the caller can report the requested slug's own counts.
+*
+*  "Does this collection sync at all" is answered BEFORE "is Google linked":
+*  telling someone to link their account for a collection that never declared a
+*  calendar sends them fixing the wrong thing. */
+async function syncCalendarForCollection(slug, workspaceRoot, deps = liveManualSyncDeps) {
+	const owning = [...await deps.loadGroups(workspaceRoot)].filter(([, collections]) => collections.some((collection) => collection.slug === slug));
+	if (owning.length === 0) return { kind: "not-a-calendar" };
+	if (!await deps.isLinked()) return { kind: "not-linked" };
+	return {
+		kind: "synced",
+		results: await deps.runGroups(new Map(owning), workspaceRoot)
+	};
+}
 /** Scheduler registration, shaped like `feedRefreshTaskDef` so hosts wire it
 *  with a single line. */
 function googleCalendarSyncTaskDef(opts) {
@@ -1063,6 +1179,7 @@ var TASKS_BASE_URL = "https://tasks.googleapis.com/tasks/v1";
 var TASKS_API_LABEL = "Google Tasks API";
 var DEFAULT_TASK_LIST_ID = "@default";
 var TASK_STATUS_COMPLETED = "completed";
+var TASK_STATUS_NEEDS_ACTION = "needsAction";
 var MAX_TASK_LISTS = 50;
 var toTaskListSummary = (value) => {
 	const record = asRecord(value);
@@ -1081,7 +1198,12 @@ var toTaskSummary = (value) => {
 		notes: stringField(record, "notes")
 	};
 };
-var tasksUrl = (taskListId, suffix = "") => `${TASKS_BASE_URL}/lists/${encodeURIComponent(taskListId ?? DEFAULT_TASK_LIST_ID)}/tasks${suffix}`;
+/** Resolve a declared taskListId to the one the API addresses. `||` (not `??`)
+*  so a blank string also falls back instead of building a malformed
+*  `/lists//tasks` URL — the same rule, and the same reason, as
+*  `canonicalCalendarId`. */
+var canonicalTaskListId = (taskListId) => taskListId?.trim() || DEFAULT_TASK_LIST_ID;
+var tasksUrl = (taskListId, suffix = "") => `${TASKS_BASE_URL}/lists/${encodeURIComponent(canonicalTaskListId(taskListId))}/tasks${suffix}`;
 async function listTaskLists(accessToken) {
 	return itemsOf(await googleRequest(TASKS_API_LABEL, accessToken, `${TASKS_BASE_URL}/users/@me/lists?maxResults=${MAX_TASK_LISTS}`)).map(toTaskListSummary);
 }
@@ -1103,12 +1225,47 @@ async function createTask(accessToken, input) {
 		body: JSON.stringify(body)
 	}));
 }
+/** PATCH body for a task edit — only the fields the caller supplied. As with
+*  events, `undefined` means "leave as is" and `""` means "clear it", so the
+*  two must stay distinct. `status` is deliberately absent: `completeTask` /
+*  `uncompleteTask` own that transition, and two ways to set it would drift
+*  apart. */
+var buildTaskPatch = (input) => ({
+	...input.title !== void 0 ? { title: input.title } : {},
+	...input.notes !== void 0 ? { notes: input.notes } : {},
+	...input.due !== void 0 ? { due: input.due } : {}
+});
+async function updateTask(accessToken, input) {
+	return toTaskSummary(await googleRequest(TASKS_API_LABEL, accessToken, tasksUrl(input.taskListId, `/${encodeURIComponent(input.taskId)}`), {
+		method: "PATCH",
+		body: JSON.stringify(buildTaskPatch(input))
+	}));
+}
 async function completeTask(accessToken, input) {
 	return toTaskSummary(await googleRequest(TASKS_API_LABEL, accessToken, tasksUrl(input.taskListId, `/${encodeURIComponent(input.taskId)}`), {
 		method: "PATCH",
 		body: JSON.stringify({ status: TASK_STATUS_COMPLETED })
 	}));
 }
+/** Send a completed task back to the to-do list.
+*
+*  Its own function rather than a flag on `completeTask`, and deliberately not
+*  a `status` field on `updateTask`: one kind per target state keeps the name
+*  honest and leaves exactly one code path setting each value.
+*
+*  The patch carries `status` alone — mirroring `completeTask`, which also
+*  sets only `status` and lets Google fill in the `completed` timestamp. Note
+*  that whether Google *clears* that timestamp on the way back is its
+*  behaviour, not ours, and is unverified here: `TaskSummary` doesn't carry
+*  `completed`, so nothing in this codebase would show a stale one. If a
+*  reopened task ever displays a completion date in Google's own UI, this is
+*  the place to add `completed: null` to the patch. */
+async function uncompleteTask(accessToken, input) {
+	return toTaskSummary(await googleRequest(TASKS_API_LABEL, accessToken, tasksUrl(input.taskListId, `/${encodeURIComponent(input.taskId)}`), {
+		method: "PATCH",
+		body: JSON.stringify({ status: TASK_STATUS_NEEDS_ACTION })
+	}));
+}
 async function deleteTask(accessToken, input) {
 	await googleRequest(TASKS_API_LABEL, accessToken, tasksUrl(input.taskListId, `/${encodeURIComponent(input.taskId)}`), { method: "DELETE" });
 }
@@ -1223,10 +1380,13 @@ exports.brokerBaseUrl = brokerBaseUrl;
 exports.brokerExchange = brokerExchange;
 exports.brokerRefresh = brokerRefresh;
 exports.brokerStart = brokerStart;
+exports.buildEventPatch = buildEventPatch;
 exports.buildMultipartBody = buildMultipartBody;
+exports.buildTaskPatch = buildTaskPatch;
 exports.calendarApiError = calendarApiError;
 exports.calendarSyncStatePath = calendarSyncStatePath;
 exports.canonicalCalendarId = canonicalCalendarId;
+exports.canonicalTaskListId = canonicalTaskListId;
 exports.classifyDelete = classifyDelete;
 exports.classifyWrite = classifyWrite;
 exports.clearCalendarSyncToken = clearCalendarSyncToken;
@@ -1239,6 +1399,7 @@ exports.createCalendarEvent = createCalendarEvent;
 exports.createDriveFile = createDriveFile;
 exports.createGoogleAuthFlow = createGoogleAuthFlow;
 exports.createTask = createTask;
+exports.deleteCalendarEvent = deleteCalendarEvent;
 exports.deleteDriveFile = deleteDriveFile;
 exports.deleteGoogleTokens = deleteGoogleTokens;
 exports.deleteTask = deleteTask;
@@ -1272,8 +1433,10 @@ exports.releaseOrphanedCalendarToken = releaseOrphanedCalendarToken;
 exports.saveCalendarSyncToken = saveCalendarSyncToken;
 exports.saveGoogleTokens = saveGoogleTokens;
 exports.syncCalendarEvents = syncCalendarEvents;
+exports.syncCalendarForCollection = syncCalendarForCollection;
 exports.syncCalendarGroup = syncCalendarGroup;
 exports.syncDueCalendarCollections = syncDueCalendarCollections;
+exports.syncNewCalendarCollections = syncNewCalendarCollections;
 exports.toCalendarSummary = toCalendarSummary;
 exports.toCollectionDateTime = toCollectionDateTime;
 exports.toCollectionRecord = toCollectionRecord;
@@ -1281,7 +1444,12 @@ exports.toDriveFileSummary = toDriveFileSummary;
 exports.toEventSummary = toEventSummary;
 exports.toTaskListSummary = toTaskListSummary;
 exports.toTaskSummary = toTaskSummary;
+exports.uncompleteTask = uncompleteTask;
 exports.unlinkGoogle = unlinkGoogle;
+exports.unsyncedGroups = unsyncedGroups;
+exports.updateCalendarEvent = updateCalendarEvent;
+exports.updateTask = updateTask;
 exports.waitForAuthCode = waitForAuthCode;
+exports.withKeyedLock = withKeyedLock;
 
 //# sourceMappingURL=index.cjs.map