@plinth-music/cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 Notable changes to `@plinth-music/cli`. Grouped by what a user notices, not by PR.
 
+## 0.7.0 — 2026-08-23
+
+One PR and one docs commit since `0.6.0` (`v0.6.0..71c775c`). The mirror gains a
+calendar the agent can read without opening one.
+
+### Each artist's calendar is projected into the mirror
+
+`plinth start` now runs a second loop on its own 15-minute timer
+(`PLINTH_CALENDAR_INTERVAL_MS`, one run at boot), writing `views/calendar/` into the
+mirror: a file per mapped artist plus an `upcoming.md` across all of them.
+Deliberately not the 15-second pull loop — one tick fans out to one Google call per
+mapped calendar, which would breach the server route's 20/min limit inside a minute.
+
+`/plinth:start` gains a step that reads one of those files. It still does not open a
+calendar, and the generated text says so.
+
+**An empty cache and a clear diary are not allowed to look alike.** `events: []` means
+exactly one thing and is refused on any row that did not actually fetch; a failed
+refresh keeps every body and rewrites only the header, so a stale view says it is
+stale rather than saying nothing is on; an artist with no mapped calendar is named in
+`upcoming.md` rather than silently absent.
+
+**Requires the server's `GET /api/sync/calendar`** (`plinth` #257), live in
+production. A 0.6.0 client is unaffected: it never calls it.
+
 ## 0.6.0 — 2026-08-20
 
 Eleven PRs since `0.5.0` (`v0.5.0..af8c7df`). A session in a mirror now opens and

package/README.md

@@ -24,7 +24,7 @@ plinth start                      # run the daemon: continuous pull + watch + pu
 
 - `plinth login --workspace <slug>` — issue a personal access token in the browser, paste it back, store it in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager).
 - `plinth sync [--workspace <slug>]` — one-shot pull into `~/Plinth/<workspace>/`. Also generates the workspace-root `CLAUDE.md` (a thin TOC + entity model + skill pointers), an empty `CLAUDE.local.md` stub on first sync, and the two session-boundary commands (below), and silently refreshes `CLAUDE.md` on a schema-version change. Defaults to the active workspace if `--workspace` is omitted.
-- `plinth start` — run the long-running sync daemon: pull the latest, then watch the mirror for local edits and push them. Logs to `~/.plinth/daemon.log`.
+- `plinth start` — run the long-running sync daemon: pull the latest, then watch the mirror for local edits and push them. It also projects each mapped artist's Google calendar into `views/calendar/` in the mirror — a file per artist plus an `upcoming.md` — on its own 15-minute timer (`PLINTH_CALENDAR_INTERVAL_MS`), with one run at boot. That is deliberately not the 15-second pull cadence: one tick makes a Google call per mapped calendar, which would breach the server route's rate limit inside a minute. A refresh that fails keeps the last known bodies and rewrites only the header, so a stale view says it is stale rather than reading as an empty diary. Logs to `~/.plinth/daemon.log`.
 - `plinth status` — local sync state: daemon liveness, last sync and per-type counts, and any destructive batches being held. Warns when a source install's `dist/` is behind its checkout.
 - `plinth confirm` — review and release destructive batches the daemon has quarantined (apply, or `--discard`).
 - `plinth refresh-context [--workspace <slug>]` — force-regenerate the workspace-root `CLAUDE.md` **and the two generated commands** from the current Plinth schema + workspace. The user-customisable block between the `<!-- BEGIN: user-customisable -->` / `<!-- END -->` markers is always preserved verbatim in every generated file; `CLAUDE.local.md` is never touched.

package/dist/build-stamp.json

@@ -1,5 +1,5 @@
 {
-  "sha": "8ae75780594f0715a00b4ee07af7d49ec055c3fd",
+  "sha": "c8ca82b2d16c0ed618813268f475e63ba0c4d26d",
   "dirty": false,
-  "built_at": "2026-08-20T17:35:39.314Z"
+  "built_at": "2026-08-23T13:01:01.515Z"
 }

package/dist/cli.js

@@ -9193,7 +9193,7 @@ async function runMain(cmd, opts = {}) {
 // package.json
 var package_default = {
   name: "@plinth-music/cli",
-  version: "0.6.0",
+  version: "0.7.0",
   description: "Plinth capstone sync daemon and CLI",
   type: "module",
   private: false,
@@ -25237,6 +25237,79 @@ function deleteExtractedText(workspaceSlug, relPath) {
     throw err;
   }
 }
+var CALENDAR_VIEW_DIR = "calendar";
+var CALENDAR_UPCOMING_NAME = "upcoming";
+var CALENDAR_INTERNAL_NAME = "_internal";
+var CALENDAR_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+function calendarViewRelPath(name) {
+  return `${VIEWS_SUBTREE}/${CALENDAR_VIEW_DIR}/${name}.md`;
+}
+function calendarViewPath(workspaceSlug, name) {
+  if (name !== CALENDAR_INTERNAL_NAME && !CALENDAR_NAME_RE.test(name)) {
+    throw new MirrorPathError(`Invalid calendar view name: ${JSON.stringify(name)}`);
+  }
+  if (name.length > 200) {
+    throw new MirrorPathError(`Calendar view name too long: ${name.length}`);
+  }
+  const ws = workspaceMirrorPath(workspaceSlug);
+  const posix = calendarViewRelPath(name);
+  const native = sep2 === "/" ? posix : posix.split("/").join(sep2);
+  const target = resolve(join2(ws, native));
+  const prefix = join2(ws, VIEWS_SUBTREE, CALENDAR_VIEW_DIR) + sep2;
+  if (!target.startsWith(prefix)) {
+    throw new MirrorPathError(`Resolved calendar-view path escapes the views/calendar subtree`);
+  }
+  return target;
+}
+function writeCalendarView(workspaceSlug, name, content) {
+  const target = calendarViewPath(workspaceSlug, name);
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  mkdirSync(dirname(target), { recursive: true, mode: 448 });
+  writeFileSync(tmp, content, { mode: 384 });
+  try {
+    renameSync(tmp, target);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {}
+    throw err;
+  }
+}
+function readCalendarView(workspaceSlug, name) {
+  try {
+    return readFileSync(calendarViewPath(workspaceSlug, name), "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT")
+      return null;
+    throw err;
+  }
+}
+function deleteCalendarView(workspaceSlug, name) {
+  const target = calendarViewPath(workspaceSlug, name);
+  try {
+    unlinkSync(target);
+    return true;
+  } catch (err) {
+    if (err?.code === "ENOENT")
+      return false;
+    throw err;
+  }
+}
+function listCalendarViews(workspaceSlug) {
+  let dir;
+  try {
+    dir = join2(workspaceMirrorPath(workspaceSlug), VIEWS_SUBTREE, CALENDAR_VIEW_DIR);
+  } catch {
+    return [];
+  }
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e2) => e2.isFile() && e2.name.endsWith(".md")).map((e2) => e2.name.slice(0, -3)).sort();
+}
 function contextFilePath(workspaceSlug, relativePath) {
   const ws = workspaceMirrorPath(workspaceSlug);
   const resolved = resolve(join2(ws, relativePath));
@@ -26837,7 +26910,7 @@ function buildGroundingBlock(today, workspaceRules = null, workspaceMemory = nul
     ``,
     `Write through the canonical surface. In this cockpit the file tree is your edit ` + `surface, so reach for it before the most direct tool. Change prose (document ` + `bodies, free-form notes, anything textual) by editing the mirror markdown ` + `file; the daemon syncs it up. An artist's master context is the clearest case: ` + `it lives in the body of that artist's \`artists/<slug>/_artist.md\` mirror file, ` + `the file the web context pane renders, and one of only two files under ` + `\`artists/<slug>/\` the daemon syncs both ways (\`memory.md\` is the other), ` + `so change it by editing that body, never by creating ` + `a separate document or context entity (e.g. \`create_document\`) the pane won't ` + `render. One carve-out inside that file: a block labelled as rendered from ` + `Plinth is regenerated on every sync and your edits to it are discarded, so ` + `write those through the tool the block names. Change structured fields (task ` + `status, priority, assignees, due dates, a project's category) through the ` + `Plinth MCP (\`mcp__plinth__*\`) or the task file's frontmatter, which is ` + `row-canonical but still written through the validated API. Make a bulk or ` + `destructive change (a mass delete, a gutting overwrite) by editing the file ` + `path, so the daemon's confirm-gate can quarantine it for \`plinth confirm\`. ` + `Never write the database directly, which rules out raw SQL and ` + `\`execute_sql\`, \`apply_migration\` and \`psql\`: those bypass the daemon, the ` + `mirror, the confirm-gate, canonicality, and API validation.`,
     ``,
-    `Dates belong on the calendar, not in \`key_dates\`. The date surface for an artist ` + `is their mapped Google Calendar; the \`key_dates\` table is retired. Never create ` + `or update a key date: do not call \`create_key_date\` or \`update_key_date\` (they ` + `write to the retired table and are being removed from the tool surface). Reading ` + `dates is fine (\`list_key_dates\`, \`list_artist_calendars\`).`,
+    `Dates belong on the calendar, not in \`key_dates\`. The date surface for an artist ` + `is their mapped Google Calendar; the \`key_dates\` table is retired. Never create ` + `or update a key date: do not call \`create_key_date\` or \`update_key_date\` (they ` + `write to the retired table and are being removed from the tool surface). Reading ` + `dates is fine, and this mirror already holds them: the daemon projects every ` + `mapped calendar into \`views/calendar/upcoming.md\` and ` + `\`views/calendar/<slug>.md\`, so read those before reaching for a tool ` + `(\`list_artist_calendars\`, \`list_key_dates\`). They are derived and overwritten, ` + `so they are current only as of the \`generated_at\` in their header - quote that ` + `stamp, never edit them, and check the status line, because a calendar Plinth ` + `could not reach is unknown rather than empty.`,
     ``,
     `Read the calendar, and hand a date over rather than writing it yourself. An ` + `artist's dates live on their mapped Google Calendar and reading them is yours: ` + `resolve the calendar through \`mcp__plinth__list_artist_calendars\` and use its ` + `\`calendar_id\` field, not the mapping row's \`id\`, because the default ` + `\`primary\` is almost never theirs. Writing it is not yours. When a date needs ` + `adding or correcting (a show, a hold, a release, a deadline), say plainly what ` + `the change is, say that it goes in through Plinth's calendar view, and say that ` + `a person makes that change rather than you. Say the reason too, because a date ` + `left looking handled is worse than one openly outstanding: a calendar write ` + `goes out to everyone invited the moment it lands, and it cannot be recalled. ` + `This is not a puzzle to route around. Do not reach for a shell command line to ` + `do it, the Google Workspace one included, and do not go looking for another ` + `tool that writes a calendar. Those tools are denied to you wherever Plinth has ` + `configured this workspace, and where a deny has not reached, the rule is the ` + `same and you are the only thing holding it.`,
     ``,
@@ -29237,7 +29310,7 @@ function withUserBlock(lines) {
 function buildStartCommandMd() {
   return withUserBlock([
     "---",
-    "description: Open a Plinth session in this workspace. Reads both memory files, pulls what is unread, gives a three-line brief, then asks what you want to work on.",
+    "description: Open a Plinth session in this workspace. Reads both memory files, pulls what is unread, reads the projected calendar, gives a three-line brief, then asks what you want to work on.",
     "---",
     "",
     OWNERSHIP_NOTE,
@@ -29260,23 +29333,37 @@ function buildStartCommandMd() {
     "",
     "Pull **unread notifications** from the Plinth MCP (`list_notifications`). If the Plinth MCP is not connected, say so in one line and carry on from the injected indexes rather than failing.",
     "",
-    "**That one call is the whole budget, and the list below is exhaustive rather than indicative.** Do not sweep tasks, do not list projects, do not open a calendar, do not read an artist folder, and do not re-read the memory files. If a fact is not in the two injected indexes or in the notifications, it does not belong in this brief.",
+    "**That one call plus the single file read in Step 3 are the whole budget, and the list below is exhaustive rather than indicative.** Do not sweep tasks, do not list projects, do not open a calendar, do not read an artist folder, and do not re-read the memory files. If a fact is not in the two injected indexes, in the notifications, or in that one file, it does not belong in this brief.",
+    "",
+    "## Step 3: what is coming up",
+    "",
+    "Read **one file**: `views/calendar/upcoming.md` at the mirror root. It is Plinth's projection of every artist's calendar, written into the mirror by the daemon.",
+    "",
+    "**This is a FILE READ, not a calendar call, and the rule in Step 2 stands unchanged: you still never open a calendar tool.** The file is here so that you do not have to.",
     "",
-    "## Step 3: brief, in three lines",
+    '**Brief it as of its own `generated_at` stamp, and say the stamp.** A projection is a cache. It is exactly as current as the header says it is and no more, so "nothing on this week" is only ever true as of that moment.',
+    "",
+    "**Read its calendar-status list before you read the dates, and escalate anything that was not read.** A calendar Plinth could not reach is UNKNOWN, not empty, and the file says which. Briefing an unread calendar as a clear diary is the one failure this file exists to prevent - if a line says NOT READ, say so out loud in the brief.",
+    "",
+    "If the file carries `fetch_state: stale`, the last refresh failed: say how old the dates are rather than reporting them as current. If the file is absent altogether, say the projection has not run yet and carry on without it.",
+    "",
+    "**Dates are read here and changed by a person, in Plinth's calendar view.** If something needs moving, say what the change is and hand it over.",
+    "",
+    "## Step 4: brief, in three lines",
     "",
     "Then stop reading and report. **Three lines, and not a summary of what you read:**",
     "",
-    "1. Today, and anything with a clock on it that the injected indexes or the notifications **have already named**. Do not go looking for more.",
+    "1. Today, and anything with a clock on it that the injected indexes, the notifications or the calendar file **have already named** - with the calendar's own stamp when you use it. Do not go looking for more.",
     "2. The unread count, and the one or two that actually matter.",
     "3. Anything blocked or waiting on someone.",
     "",
     'Then ask: **"What do you want to work on?"** If the user already said so in the same message, skip the question and load that context now.',
     "",
-    "## Step 4: offer the sweep, do not run it",
+    "## Step 5: offer the sweep, do not run it",
     "",
     `A full roster sweep, every artist's overdue and upcoming work plus calendars and project status, is useful and it is **not** part of opening a session. **Offer it in one clause ("want the roster sweep?") and stop there.** Reporting a sweep you ran anyway is the failure this step exists to prevent: it is the same cost the user did not ask for, with the offer bolted on afterwards.`,
     "",
-    "**The budget is the one call in Step 2, and it is a ceiling rather than a target.** Every new session pays this command before the user has asked for anything, so a second call needs a reason you would defend out loud. An opener that takes half a minute gets turned off, and an opener nobody runs banks nothing at the other end.",
+    "**The budget is the one call in Step 2 and the one file read in Step 3, and it is a ceiling rather than a target.** Every new session pays this command before the user has asked for anything, so a second call needs a reason you would defend out loud. An opener that takes half a minute gets turned off, and an opener nobody runs banks nothing at the other end.",
     "",
     "## Loading area context",
     "",
@@ -30609,6 +30696,17 @@ function pullNoticeLine(kind) {
   const token = kind === "auth" ? "PULL_PAUSED" : "PULL_DEGRADED";
   return `[${token} reason=${kind}]`;
 }
+function calendarProjectedLine(f3) {
+  return `[CALENDAR_PROJECTED written=${f3.written} pruned=${f3.pruned} ` + `calendars=${f3.calendars} not_read=${f3.notRead}]`;
+}
+function calendarFailedLine(f3) {
+  const serverPart = f3.serverMessage ? ` server_msg="${f3.serverMessage}"` : "";
+  return `[CALENDAR_FAILED status=${f3.status} reason=${f3.reason} staled=${f3.staled}${serverPart}]`;
+}
+function calendarNoticeLine(kind) {
+  const token = kind === "auth" ? "CALENDAR_PAUSED" : kind === "unsupported" ? "CALENDAR_UNSUPPORTED" : "CALENDAR_DEGRADED";
+  return `[${token} reason=${kind}]`;
+}
 
 // src/lib/rejected.ts
 import { relative as relative3 } from "node:path";
@@ -35363,6 +35461,753 @@ class PullLoop {
   }
 }
 
+// src/lib/calendar-loop.ts
+var DEFAULT_CALENDAR_INTERVAL_MS = 900000;
+var CALENDAR_BACKOFF_CAP_MS = 3600000;
+var CALENDAR_AUTH_RETRY_MS = 300000;
+function calendarIntervalMs() {
+  const raw = process.env.PLINTH_CALENDAR_INTERVAL_MS;
+  if (raw) {
+    const n2 = Number(raw);
+    if (Number.isFinite(n2) && n2 > 0)
+      return n2;
+  }
+  return DEFAULT_CALENDAR_INTERVAL_MS;
+}
+
+class CalendarLoop {
+  runOnce;
+  onProjected;
+  notice;
+  loginHint;
+  intervalMs;
+  capMs;
+  authRetryMs;
+  setTimer;
+  clearTimer;
+  timer = null;
+  inFlight = false;
+  stopped = false;
+  failures = 0;
+  authAnnounced = false;
+  degradedAnnounced = false;
+  constructor(deps) {
+    this.runOnce = deps.runOnce;
+    this.onProjected = deps.onProjected;
+    this.notice = deps.notice;
+    this.loginHint = deps.loginHint;
+    this.intervalMs = deps.intervalMs ?? calendarIntervalMs();
+    this.capMs = deps.capMs ?? CALENDAR_BACKOFF_CAP_MS;
+    this.authRetryMs = deps.authRetryMs ?? CALENDAR_AUTH_RETRY_MS;
+    this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    this.clearTimer = deps.clearTimer ?? ((t2) => clearTimeout(t2));
+  }
+  startNow() {
+    this.tick();
+  }
+  start() {
+    this.schedule(this.intervalMs);
+  }
+  stop() {
+    this.stopped = true;
+    if (this.timer !== null) {
+      this.clearTimer(this.timer);
+      this.timer = null;
+    }
+  }
+  schedule(ms) {
+    if (this.stopped)
+      return;
+    this.timer = this.setTimer(() => {
+      this.tick();
+    }, ms);
+  }
+  async tick() {
+    if (this.stopped || this.inFlight)
+      return;
+    this.inFlight = true;
+    let nextDelay;
+    try {
+      const result = await this.runOnce();
+      nextDelay = result.ok ? this.onSuccess(result) : this.onFailure(result.failure);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : "unknown error";
+      nextDelay = this.onFailure({ kind: "transient", reason });
+    } finally {
+      this.inFlight = false;
+    }
+    if (nextDelay !== null)
+      this.schedule(nextDelay);
+  }
+  onSuccess(result) {
+    this.failures = 0;
+    this.authAnnounced = false;
+    this.degradedAnnounced = false;
+    if (result.written > 0 || result.pruned > 0) {
+      this.onProjected(result.written, result.pruned);
+    }
+    return this.intervalMs;
+  }
+  onFailure(failure) {
+    if (failure.kind === "unsupported") {
+      this.stop();
+      this.notice("unsupported", `Calendar projection is off: this Plinth server has no calendar route. ` + `Nothing under views/calendar/ will be written or updated. Restart the ` + `daemon once the server is up to date.`);
+      return null;
+    }
+    if (failure.kind === "auth") {
+      if (!this.authAnnounced) {
+        this.authAnnounced = true;
+        this.notice("auth", `Calendar refresh paused - the server rejected the token. Run ` + `\`${this.loginHint}\`, then RESTART the daemon: the token is read once ` + `at startup, so a re-login is not picked up until it does. Files ` + `under views/calendar/ keep their last good read and say they are stale.`);
+      }
+      return this.authRetryMs;
+    }
+    this.failures += 1;
+    let delay;
+    if (failure.kind === "rate_limit" && failure.retryAfterMs !== undefined) {
+      delay = Math.min(Math.max(failure.retryAfterMs, 1000), this.capMs);
+    } else {
+      delay = Math.min(this.intervalMs * 2 ** (this.failures - 1), this.capMs);
+    }
+    if (delay >= this.capMs && !this.degradedAnnounced) {
+      this.degradedAnnounced = true;
+      const mins = Math.round(this.capMs / 60000);
+      this.notice("degraded", `Calendar refresh degraded - repeated failures, retrying about every ` + `${mins}m. Files under views/calendar/ still show the last good read ` + `and say that they are stale.`);
+    }
+    return delay;
+  }
+}
+function classifyCalendarFailure(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 404)
+      return { kind: "unsupported", reason: err.message };
+    if (err.status === 401 || err.status === 403) {
+      return { kind: "auth", reason: err.message };
+    }
+    if (err.status === 429) {
+      return {
+        kind: "rate_limit",
+        reason: err.message,
+        retryAfterMs: err.retryAfterMs
+      };
+    }
+    return { kind: "transient", reason: err.message };
+  }
+  return {
+    kind: "transient",
+    reason: err instanceof Error ? err.message : "unknown error"
+  };
+}
+
+// src/lib/calendar/api.ts
+class CalendarContractError extends ApiError {
+  constructor(status, message) {
+    super(status, message);
+    this.name = "CalendarContractError";
+  }
+}
+var CalendarEventSchema = exports_external.object({
+  id: exports_external.string(),
+  title: exports_external.string(),
+  start: exports_external.string().min(1),
+  end: exports_external.string().min(1),
+  all_day: exports_external.boolean(),
+  location: exports_external.string().nullish().transform((v2) => v2 ?? null),
+  booking_status: exports_external.enum(["confirmed", "hold"]),
+  url: exports_external.string()
+});
+var CALENDAR_STATUSES = [
+  "fetched",
+  "no-token",
+  "token-expired",
+  "google-error"
+];
+var CalendarRowSchema = exports_external.object({
+  artist_id: exports_external.string().nullable(),
+  artist_slug: exports_external.string().nullable(),
+  artist_name: exports_external.string().nullable(),
+  calendar_id: exports_external.string(),
+  calendar_name: exports_external.string(),
+  status: exports_external.enum(CALENDAR_STATUSES),
+  events: exports_external.array(CalendarEventSchema).nullable(),
+  error: exports_external.object({ upstream_status: exports_external.number(), message: exports_external.string() }).nullish().transform((v2) => v2 ?? null),
+  truncated: exports_external.boolean().optional().default(false)
+});
+var CalendarResponseSchema = exports_external.object({
+  generated_at: exports_external.string().min(1),
+  window: exports_external.object({
+    time_min: exports_external.string().min(1),
+    time_max: exports_external.string().min(1)
+  }),
+  artist_count: exports_external.number().int().nonnegative(),
+  mapped_artist_count: exports_external.number().int().nonnegative(),
+  calendars: exports_external.array(CalendarRowSchema)
+}).superRefine((body, ctx) => {
+  for (const [i2, row] of body.calendars.entries()) {
+    const isFetched = row.status === "fetched";
+    if (isFetched && row.events === null) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        path: ["calendars", i2, "events"],
+        message: `status "fetched" must carry an events array, not null`
+      });
+    }
+    if (!isFetched && row.events !== null) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        path: ["calendars", i2, "events"],
+        message: `status "${row.status}" must carry events: null, not an array`
+      });
+    }
+  }
+});
+async function fetchCalendar(args) {
+  const { baseUrl, pat, fetchImpl = fetch } = args;
+  const url2 = `${baseUrl.replace(/\/$/, "")}/api/sync/calendar`;
+  let res;
+  try {
+    res = await fetchImpl(url2, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${pat}`,
+        Accept: "application/json"
+      }
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "network error";
+    throw new ApiError(0, `Could not reach ${url2}: ${msg}`);
+  }
+  if (res.status === 401) {
+    throw new ApiError(401, "Token was rejected by the server. Run `plinth login --workspace <slug>` to refresh.");
+  }
+  if (res.status === 404) {
+    throw new ApiError(404, "This Plinth server has no /api/sync/calendar route.");
+  }
+  if (res.status === 429) {
+    throw new ApiError(429, "Rate limited by the server. Wait a few seconds and retry.", parseRetryAfterMs(res.headers.get("retry-after")));
+  }
+  if (!res.ok) {
+    throw new ApiError(res.status, `sync calendar failed with HTTP ${res.status}`);
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    throw new CalendarContractError(res.status, "sync calendar response was not JSON");
+  }
+  const parsed = CalendarResponseSchema.safeParse(body);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.slice(0, 3).map((i2) => `${i2.path.join(".") || "(root)"}: ${i2.message}`).join("; ");
+    throw new CalendarContractError(res.status, `sync calendar response did not match the contract: ${detail}`);
+  }
+  return parsed.data;
+}
+
+// src/lib/calendar/render.ts
+var CALENDAR_BODY_MARKER = "<!-- PLINTH:CALENDAR-BODY -->";
+var OWNERSHIP_NOTE2 = [
+  "<!-- Generated by Plinth from the calendars mapped in this workspace. This file",
+  "     is DERIVED: one-way, overwritten on every refresh, and never uploaded.",
+  "     Your edits here are lost. Dates are changed in Plinth's calendar view, by a",
+  "     person - not from this file and not by an agent. -->"
+].join(`
+`);
+var DEFAULT_USER_LABEL = "the Plinth account this mirror syncs with";
+var WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+var MONTHS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec"
+];
+var DAY_MS = 86400000;
+var FULL_BAND_DAYS = 14;
+function yamlString(value) {
+  return JSON.stringify(value);
+}
+function oneLine(value, maxLength = 200) {
+  const flattened = value.replace(/[\u0000-\u001F\u007F]+/g, " ").replace(/<!--/g, "<! --").replace(/\s+/g, " ").trim();
+  if (flattened.length === 0)
+    return "(untitled)";
+  if (flattened.length <= maxLength)
+    return flattened;
+  return `${flattened.slice(0, maxLength - 3)}...`;
+}
+function dateParts(value) {
+  const m2 = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+  if (!m2)
+    return null;
+  return { y: Number(m2[1]), m: Number(m2[2]), d: Number(m2[3]) };
+}
+function timeParts(value) {
+  const m2 = /T(\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?(Z|[+-]\d{2}:\d{2})?$/.exec(value);
+  if (!m2)
+    return null;
+  const rawOffset = m2[3];
+  const offset = rawOffset === undefined ? "" : rawOffset === "Z" ? "UTC" : rawOffset;
+  return { hh: m2[1], mi: m2[2], offset };
+}
+function utcMs(parts) {
+  return Date.UTC(parts.y, parts.m - 1, parts.d);
+}
+function shiftDays(parts, days) {
+  const d2 = new Date(utcMs(parts) + days * DAY_MS);
+  return { y: d2.getUTCFullYear(), m: d2.getUTCMonth() + 1, d: d2.getUTCDate() };
+}
+function formatDay(parts, referenceYear) {
+  const weekday = WEEKDAYS[new Date(utcMs(parts)).getUTCDay()] ?? "";
+  const month = MONTHS[parts.m - 1] ?? "";
+  const year = parts.y === referenceYear ? "" : ` ${parts.y}`;
+  return `${weekday} ${parts.d} ${month}${year}`;
+}
+function sortInstant(event) {
+  if (!event.all_day) {
+    const ms = Date.parse(event.start);
+    if (!Number.isNaN(ms))
+      return ms;
+  }
+  const parts = dateParts(event.start);
+  if (parts)
+    return utcMs(parts);
+  return Number.MAX_SAFE_INTEGER;
+}
+function describeWhen(event, referenceYear) {
+  const start = dateParts(event.start);
+  if (!start)
+    return oneLine(event.start, 60);
+  if (event.all_day) {
+    const end2 = dateParts(event.end);
+    const last = end2 ? shiftDays(end2, -1) : start;
+    const single = !end2 || utcMs(last) <= utcMs(start);
+    return single ? `${formatDay(start, referenceYear)} (all day)` : `${formatDay(start, referenceYear)} to ${formatDay(last, referenceYear)} (all day)`;
+  }
+  const startTime = timeParts(event.start);
+  const end = dateParts(event.end);
+  const endTime = timeParts(event.end);
+  if (!startTime)
+    return formatDay(start, referenceYear);
+  const suffix = startTime.offset ? ` ${startTime.offset}` : "";
+  if (!end || !endTime) {
+    return `${formatDay(start, referenceYear)}, ${startTime.hh}:${startTime.mi}${suffix}`;
+  }
+  if (utcMs(end) === utcMs(start)) {
+    return `${formatDay(start, referenceYear)}, ${startTime.hh}:${startTime.mi}-${endTime.hh}:${endTime.mi}${suffix}`;
+  }
+  const endSuffix = endTime.offset ? ` ${endTime.offset}` : "";
+  return `${formatDay(start, referenceYear)} ${startTime.hh}:${startTime.mi}${suffix}` + ` to ${formatDay(end, referenceYear)} ${endTime.hh}:${endTime.mi}${endSuffix}`;
+}
+function fullLine(event, referenceYear, artistPrefix, includeUrl) {
+  const parts = [
+    `**${describeWhen(event, referenceYear)}**`,
+    artistPrefix,
+    `${oneLine(event.title)} (${event.booking_status})`
+  ].filter((p) => p.length > 0);
+  if (event.location)
+    parts.push(oneLine(event.location, 80));
+  if (includeUrl && event.url)
+    parts.push(oneLine(event.url, 300));
+  return `- ${parts.join(" - ")}`;
+}
+function compactLine(event, referenceYear, artistPrefix) {
+  const parts = [
+    describeWhen(event, referenceYear),
+    artistPrefix,
+    `${oneLine(event.title)} (${event.booking_status})`
+  ].filter((p) => p.length > 0);
+  return `- ${parts.join(" - ")}`;
+}
+function humanStamp(iso) {
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms))
+    return iso;
+  const d2 = new Date(ms);
+  const day = formatDay({ y: d2.getUTCFullYear(), m: d2.getUTCMonth() + 1, d: d2.getUTCDate() }, -1);
+  const hh = String(d2.getUTCHours()).padStart(2, "0");
+  const mi = String(d2.getUTCMinutes()).padStart(2, "0");
+  return `${day}, ${hh}:${mi} UTC`;
+}
+function windowLine(timeMin, timeMax) {
+  const from = dateParts(timeMin);
+  const to = dateParts(timeMax);
+  if (!from || !to)
+    return `${timeMin} to ${timeMax}`;
+  return `${formatDay(from, -1)} to ${formatDay(to, -1)}`;
+}
+function statusLine(args) {
+  const { status, eventCount, error: error52, truncated, stamp, userLabel } = args;
+  switch (status) {
+    case "fetched": {
+      if (eventCount === 0) {
+        return `**Read fine as of ${stamp}. Nothing in this window.** The diary really ` + `is clear across the dates above. This is a successful read of an empty ` + `calendar, not a failed read - if it had failed, this line would say so.`;
+      }
+      const truncatedNote = truncated ? " **This list is INCOMPLETE**: Google had more entries than one page and the rest were not collected." : "";
+      return `**Read fine as of ${stamp}.** ${eventCount} ` + `${eventCount === 1 ? "entry" : "entries"} in the window.${truncatedNote}`;
+    }
+    case "no-token":
+      return `**NOT READ - Google is not connected for ${userLabel}.** Nothing is listed ` + `below because Plinth could not look, NOT because the diary is clear. ` + `Connect Google in Plinth to fill this in, and until then treat this ` + `calendar as unknown rather than empty.`;
+    case "token-expired":
+      return `**NOT READ - the Google connection for ${userLabel} has expired.** Plinth ` + `still holds a connection but could not refresh it, so nothing below is ` + `current. Reconnect Google in Plinth. Treat this calendar as unknown ` + `rather than empty.`;
+    case "google-error":
+      return `**NOT READ - Google refused the request` + `${error52 ? ` (HTTP ${error52.upstream_status})` : ""}.** ` + `${error52 ? oneLine(error52.message, 300) : "No detail was returned."} ` + `A calendar that was unshared or deleted in Google reads exactly like this. ` + `Nothing below is current; treat this calendar as unknown rather than empty.`;
+  }
+}
+function shortStatus(row) {
+  switch (row.status) {
+    case "fetched": {
+      const n2 = row.events?.length ?? 0;
+      if (n2 === 0)
+        return "read fine, nothing in this window";
+      return `read fine, ${n2} ${n2 === 1 ? "entry" : "entries"}${row.truncated ? " (INCOMPLETE - more than one page)" : ""}`;
+    }
+    case "no-token":
+      return "NOT READ - Google is not connected; unknown, not empty";
+    case "token-expired":
+      return "NOT READ - the Google connection has expired; unknown, not empty";
+    case "google-error":
+      return `NOT READ - Google refused` + `${row.error ? ` (HTTP ${row.error.upstream_status}): ${oneLine(row.error.message, 120)}` : ""}` + `; unknown, not empty`;
+  }
+}
+function rowFileName(row, internalName) {
+  return row.artist_slug ?? internalName;
+}
+function rowDisplayName(row) {
+  if (row.artist_name)
+    return oneLine(row.artist_name, 80);
+  return `${oneLine(row.calendar_name, 80)} (internal)`;
+}
+function splitBands(events, generatedAt) {
+  const base2 = Date.parse(generatedAt);
+  const boundary = Number.isNaN(base2) ? Number.MAX_SAFE_INTEGER : base2 + FULL_BAND_DAYS * DAY_MS;
+  const full = [];
+  const rest = [];
+  for (const e2 of events) {
+    (sortInstant(e2) < boundary ? full : rest).push(e2);
+  }
+  return { full, rest };
+}
+function renderArtistCalendar(args) {
+  const { row, generatedAt, window: window2 } = args;
+  const userLabel = args.userLabel ?? DEFAULT_USER_LABEL;
+  const events = row.events ?? [];
+  const stamp = humanStamp(generatedAt);
+  const referenceYear = new Date(Date.parse(generatedAt) || 0).getUTCFullYear();
+  const title = rowDisplayName(row);
+  const header = [
+    "---",
+    "plinth_generated: true",
+    "view: calendar",
+    `artist_slug: ${row.artist_slug === null ? "null" : yamlString(row.artist_slug)}`,
+    `artist_name: ${row.artist_name === null ? "null" : yamlString(row.artist_name)}`,
+    `calendar_name: ${yamlString(row.calendar_name)}`,
+    `generated_at: ${yamlString(generatedAt)}`,
+    `window_start: ${yamlString(window2.time_min)}`,
+    `window_end: ${yamlString(window2.time_max)}`,
+    `status: ${row.status}`,
+    "fetch_state: fresh",
+    `entry_count: ${events.length}`,
+    `truncated: ${row.truncated}`,
+    "---",
+    "",
+    OWNERSHIP_NOTE2,
+    "",
+    `# ${title} - calendar`,
+    ""
+  ].join(`
+`);
+  const body = [
+    "",
+    statusLine({
+      status: row.status,
+      eventCount: events.length,
+      error: row.error,
+      truncated: row.truncated,
+      stamp,
+      userLabel
+    }),
+    "",
+    `**Window:** ${windowLine(window2.time_min, window2.time_max)}.`,
+    "",
+    "**Dates are read here and changed in Plinth's calendar view, by a person.** If something below needs moving, say what the change is and hand it over.",
+    "",
+    renderBands(events, generatedAt, referenceYear, "")
+  ].join(`
+`);
+  return `${header}${CALENDAR_BODY_MARKER}
+${body}`;
+}
+function renderBands(events, generatedAt, referenceYear, artistPrefix) {
+  if (events.length === 0)
+    return "";
+  const { full, rest } = splitBands(events, generatedAt);
+  const out = [""];
+  out.push(`## Next ${FULL_BAND_DAYS} days`, "");
+  if (full.length === 0) {
+    out.push(`_Nothing in the next ${FULL_BAND_DAYS} days._`);
+  } else {
+    for (const e2 of full)
+      out.push(fullLine(e2, referenceYear, artistPrefix, true));
+  }
+  out.push("", "## Rest of the window", "");
+  if (rest.length === 0) {
+    out.push("_Nothing further in the window._");
+  } else {
+    for (const e2 of rest)
+      out.push(compactLine(e2, referenceYear, artistPrefix));
+  }
+  out.push("");
+  return out.join(`
+`);
+}
+function renderUpcoming(args) {
+  const {
+    rows,
+    unmappedArtists,
+    generatedAt,
+    window: window2,
+    artistCount,
+    mappedArtistCount,
+    internalName
+  } = args;
+  const stamp = humanStamp(generatedAt);
+  const referenceYear = new Date(Date.parse(generatedAt) || 0).getUTCFullYear();
+  const fetched = rows.filter((r3) => r3.status === "fetched");
+  const failed = rows.filter((r3) => r3.status !== "fetched");
+  const truncatedAnywhere = rows.some((r3) => r3.truncated);
+  const merged = fetched.flatMap((row) => (row.events ?? []).map((event) => ({ event, row }))).sort((a2, b2) => sortInstant(a2.event) - sortInstant(b2.event));
+  const { full, rest } = splitBands(merged.map((m2) => m2.event), generatedAt);
+  const fullSet = new Set(full);
+  const restSet = new Set(rest);
+  const header = [
+    "---",
+    "plinth_generated: true",
+    "view: calendar",
+    "scope: workspace",
+    `generated_at: ${yamlString(generatedAt)}`,
+    `window_start: ${yamlString(window2.time_min)}`,
+    `window_end: ${yamlString(window2.time_max)}`,
+    `artist_count: ${artistCount}`,
+    `mapped_artist_count: ${mappedArtistCount}`,
+    `calendars_read: ${fetched.length}`,
+    `calendars_not_read: ${failed.length}`,
+    "fetch_state: fresh",
+    `truncated: ${truncatedAnywhere}`,
+    "---",
+    "",
+    OWNERSHIP_NOTE2,
+    "",
+    "# Upcoming - every calendar in this workspace",
+    ""
+  ].join(`
+`);
+  const preamble = [
+    "",
+    `**As of ${stamp}.** Window ${windowLine(window2.time_min, window2.time_max)}.`,
+    "",
+    failed.length === 0 ? `**All ${fetched.length} mapped ${fetched.length === 1 ? "calendar was" : "calendars were"} read.**` : `**${fetched.length} of ${rows.length} mapped ${rows.length === 1 ? "calendar" : "calendars"} read; ${failed.length} could NOT be read.**` + ` Anything on an unread calendar is missing from the lists below - unknown, not absent.`,
+    "",
+    `${artistCount} ${artistCount === 1 ? "artist" : "artists"} in the roster; ` + `${mappedArtistCount} ${mappedArtistCount === 1 ? "has" : "have"} a calendar mapped in Plinth.`,
+    "",
+    "**Dates are read here and changed in Plinth's calendar view, by a person.** If something below needs moving, say what the change is and hand it over.",
+    "",
+    "## Calendar status",
+    "",
+    ...rows.map((row) => `- **${rowDisplayName(row)}**` + `${row.artist_slug ? ` (\`${oneLine(row.artist_slug, 80)}\`)` : ""}` + ` - ${shortStatus(row)} - \`views/calendar/${rowFileName(row, internalName)}.md\``),
+    ...unmappedArtists.map((a2) => `- **${oneLine(a2.name, 80)}** (\`${oneLine(a2.slug, 80)}\`) - NO CALENDAR MAPPED in Plinth, so there is nothing to read and no file for them. Map one in Plinth if they should have dates.`),
+    ""
+  ].join(`
+`);
+  const body = [preamble];
+  body.push(`## Next ${FULL_BAND_DAYS} days`, "", "_Links are in the per-artist file named beside each calendar above._", "");
+  const fullMerged = merged.filter((m2) => fullSet.has(m2.event));
+  if (fullMerged.length === 0) {
+    body.push(fetched.length === 0 ? `_No calendar could be read, so nothing can be listed for the next ${FULL_BAND_DAYS} days._` : `_Nothing in the next ${FULL_BAND_DAYS} days on any calendar that was read._`);
+  } else {
+    for (const { event, row } of fullMerged) {
+      body.push(fullLine(event, referenceYear, `**${rowDisplayName(row)}**`, false));
+    }
+  }
+  body.push("", "## Rest of the window", "");
+  const restMerged = merged.filter((m2) => restSet.has(m2.event));
+  if (restMerged.length === 0) {
+    body.push(fetched.length === 0 ? "_No calendar could be read, so nothing can be listed._" : "_Nothing further in the window on any calendar that was read._");
+  } else {
+    for (const { event, row } of restMerged) {
+      body.push(compactLine(event, referenceYear, `**${rowDisplayName(row)}**`));
+    }
+  }
+  body.push("");
+  return `${header}${CALENDAR_BODY_MARKER}
+${body.join(`
+`)}`;
+}
+function splitCalendarFile(content) {
+  const at = content.indexOf(CALENDAR_BODY_MARKER);
+  if (at === -1)
+    return null;
+  return {
+    header: content.slice(0, at),
+    body: content.slice(at + CALENDAR_BODY_MARKER.length)
+  };
+}
+function headerField(header, key) {
+  const re = new RegExp(`^${key}: (.*)$`, "m");
+  const m2 = re.exec(header);
+  if (!m2)
+    return null;
+  const raw = m2[1].trim();
+  if (raw === "null")
+    return null;
+  if (raw.startsWith('"')) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  return raw;
+}
+function renderStaleFile(existing, args) {
+  const split = splitCalendarFile(existing);
+  if (!split)
+    return null;
+  const previousGeneratedAt = headerField(split.header, "generated_at");
+  const title = /^# (.+)$/m.exec(split.header)?.[1]?.trim() ?? "Calendar";
+  const fmMatch = /^---\n([\s\S]*?)\n---\n/.exec(split.header);
+  const carried = (fmMatch?.[1] ?? "").split(`
+`).filter((line) => !/^(fetch_state|last_refresh_attempt|last_refresh_error):/.test(line));
+  const stamp = previousGeneratedAt ? humanStamp(previousGeneratedAt) : "an earlier refresh";
+  const header = [
+    "---",
+    ...carried,
+    "fetch_state: stale",
+    `last_refresh_attempt: ${yamlString(args.attemptedAt)}`,
+    `last_refresh_error: ${yamlString(oneLine(args.reason, 300))}`,
+    "---",
+    "",
+    OWNERSHIP_NOTE2,
+    "",
+    `# ${title}`,
+    "",
+    `**STALE - the last refresh FAILED and nothing below was updated.** Attempted ` + `${humanStamp(args.attemptedAt)} and it did not succeed: ` + `${oneLine(args.reason, 300)}`,
+    "",
+    `**What is below was last read at ${stamp}** and has not moved since. Anything ` + `changed in Google after that is not here, and something cancelled after that ` + `is still listed. Say the age out loud rather than briefing it as current.`,
+    ""
+  ].join(`
+`);
+  return `${header}${CALENDAR_BODY_MARKER}${split.body}`;
+}
+
+// src/lib/calendar/project.ts
+function writeIfChanged(workspaceSlug, name, content) {
+  if (readCalendarView(workspaceSlug, name) === content)
+    return false;
+  writeCalendarView(workspaceSlug, name, content);
+  return true;
+}
+function projectCalendar(args) {
+  const { workspaceSlug, response, roster, userLabel } = args;
+  const { generated_at: generatedAt, window: window2 } = response;
+  let written = 0;
+  let unchanged = 0;
+  let collided = 0;
+  const seen = new Set;
+  const rows = [];
+  for (const row of response.calendars) {
+    const name = rowFileName(row, CALENDAR_INTERNAL_NAME);
+    if (seen.has(name) || name === CALENDAR_UPCOMING_NAME) {
+      collided += 1;
+      continue;
+    }
+    seen.add(name);
+    rows.push(row);
+    const content = renderArtistCalendar({
+      row,
+      generatedAt,
+      window: window2,
+      userLabel
+    });
+    if (writeIfChanged(workspaceSlug, name, content))
+      written += 1;
+    else
+      unchanged += 1;
+  }
+  const mapped = new Set(response.calendars.map((r3) => r3.artist_slug).filter((s2) => s2 !== null));
+  const unmappedArtists = roster.filter((a2) => !mapped.has(a2.slug) && a2.status !== "archived").map((a2) => ({ slug: a2.slug, name: a2.name }));
+  const upcoming = renderUpcoming({
+    rows,
+    unmappedArtists,
+    generatedAt,
+    window: window2,
+    artistCount: response.artist_count,
+    mappedArtistCount: response.mapped_artist_count,
+    internalName: CALENDAR_INTERNAL_NAME,
+    userLabel
+  });
+  if (writeIfChanged(workspaceSlug, CALENDAR_UPCOMING_NAME, upcoming))
+    written += 1;
+  else
+    unchanged += 1;
+  const expected = new Set([...seen, CALENDAR_UPCOMING_NAME]);
+  let pruned = 0;
+  for (const name of listCalendarViews(workspaceSlug)) {
+    if (expected.has(name))
+      continue;
+    if (!ownsFile(workspaceSlug, name))
+      continue;
+    try {
+      if (deleteCalendarView(workspaceSlug, name))
+        pruned += 1;
+    } catch {}
+  }
+  return { written, unchanged, pruned, collided };
+}
+function ownsFile(workspaceSlug, name) {
+  try {
+    const existing = readCalendarView(workspaceSlug, name);
+    return existing !== null && existing.includes(CALENDAR_BODY_MARKER);
+  } catch {
+    return false;
+  }
+}
+function markCalendarStale(args) {
+  const { workspaceSlug, attemptedAt, reason } = args;
+  let rewritten = 0;
+  let unchanged = 0;
+  let skipped = 0;
+  for (const name of listCalendarViews(workspaceSlug)) {
+    let existing;
+    try {
+      existing = readCalendarView(workspaceSlug, name);
+    } catch {
+      skipped += 1;
+      continue;
+    }
+    if (existing === null)
+      continue;
+    const staled = renderStaleFile(existing, { attemptedAt, reason });
+    if (staled === null) {
+      skipped += 1;
+      continue;
+    }
+    try {
+      if (writeIfChanged(workspaceSlug, name, staled))
+        rewritten += 1;
+      else
+        unchanged += 1;
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { rewritten, unchanged, skipped };
+}
+
 // src/lib/pull-suppression.ts
 var PULL_SUPPRESS_TTL_MS = 1e4;
 
@@ -36474,7 +37319,7 @@ import { existsSync as existsSync5, readFileSync as readFileSync18, statSync as
 // src/lib/files/extracted-text.ts
 import { createHash as createHash3 } from "node:crypto";
 var DERIVED_TEXT_VERSION = 2;
-function yamlString(value) {
+function yamlString2(value) {
   return JSON.stringify(value);
 }
 var PARTIAL_WARNING = [
@@ -36513,8 +37358,8 @@ function renderExtractedText(doc2) {
   const frontmatter = [
     "---",
     "plinth_generated: true",
-    `source_file: ${doc2.bytesInMirror ? yamlString(`files/${doc2.relPath}`) : "null"}`,
-    `source_uri: ${doc2.sourceUri === undefined ? "unknown" : doc2.sourceUri === null ? "null" : yamlString(doc2.sourceUri)}`,
+    `source_file: ${doc2.bytesInMirror ? yamlString2(`files/${doc2.relPath}`) : "null"}`,
+    `source_uri: ${doc2.sourceUri === undefined ? "unknown" : doc2.sourceUri === null ? "null" : yamlString2(doc2.sourceUri)}`,
     `content_quality: ${doc2.quality ?? "unchecked"}`,
     `body_withheld: ${withheld}`,
     `extracted_chars: ${withheld ? 0 : doc2.text.length}`,
@@ -38327,9 +39172,76 @@ async function runStart(workspaceSlug, deps = {}) {
     loginHint: `plinth login --workspace ${slug}`
   });
   pullLoop.start();
+  let contractMismatchAnnounced = false;
+  let collisionAnnounced = false;
+  const calendarLoop = new CalendarLoop({
+    runOnce: async () => {
+      const attemptedAt = (deps.now?.() ?? new Date).toISOString();
+      try {
+        const response = await fetchCalendar({
+          baseUrl: entry2.api_base_url,
+          pat,
+          fetchImpl
+        });
+        const result = projectCalendar({
+          workspaceSlug: slug,
+          response,
+          roster: readRoster(slug)
+        });
+        const notRead = response.calendars.filter((c3) => c3.status !== "fetched").length;
+        daemonLog.log(calendarProjectedLine({
+          written: result.written,
+          pruned: result.pruned,
+          calendars: response.calendars.length,
+          notRead
+        }));
+        if (result.collided > 0 && !collisionAnnounced) {
+          collisionAnnounced = true;
+          spinner.warn(`${result.collided} calendar row${result.collided === 1 ? "" : "s"} ` + `shared a file name with another and ${result.collided === 1 ? "was" : "were"} skipped.`);
+          spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
+        }
+        contractMismatchAnnounced = false;
+        return { ok: true, written: result.written, pruned: result.pruned };
+      } catch (err) {
+        const failure = classifyCalendarFailure(err);
+        let staled = 0;
+        try {
+          staled = markCalendarStale({
+            workspaceSlug: slug,
+            attemptedAt,
+            reason: failure.reason
+          }).rewritten;
+        } catch (staleErr) {
+          out.log(`[CALENDAR_STALE_FAILED ${categorizeError(staleErr).reason}]`);
+        }
+        daemonLog.log(calendarFailedLine({ ...categorizeError(err), staled }));
+        if (err instanceof CalendarContractError && !contractMismatchAnnounced) {
+          contractMismatchAnnounced = true;
+          spinner.warn(`Calendar refresh: the server's response did not match the contract ` + `this daemon was built against. ${err.message}`);
+          spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
+        }
+        return { ok: false, failure };
+      }
+    },
+    onProjected: (written, pruned) => {
+      const parts = [`${written} calendar file${written === 1 ? "" : "s"}`];
+      if (pruned > 0)
+        parts.push(`${pruned} pruned`);
+      spinner.success(`↻ ${parts.join(", ")}`);
+      spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
+    },
+    notice: (kind, message) => {
+      daemonLog.log(calendarNoticeLine(kind));
+      spinner.warn(message);
+      spinner.update(`Watching ${slug} · ${watchingSummary(state)}`);
+    },
+    loginHint: `plinth login --workspace ${slug}`
+  });
+  calendarLoop.startNow();
   const shutdown = (signal) => {
     (async () => {
       pullLoop.stop();
+      calendarLoop.stop();
       spinner.warn(`Received ${signal}, draining pending pushes…`);
       try {
         await Promise.race([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plinth-music/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Plinth capstone sync daemon and CLI",
   "type": "module",
   "private": false,