catence 0.2.0-beta.19 → 0.2.0-beta.20

package/dist/contracts/release.d.ts

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export declare const CATENCE_RUNTIME_VERSION = "0.2.0-beta.19";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.0-beta.20";
 export declare const CATENCE_PROTOCOL_VERSION = 1;
 export type CatenceRuntimeCapabilities = {
     mcp: true;

package/dist/contracts/release.js

@@ -3,7 +3,7 @@
  * Keep these values synchronized with release/manifest.json; release checks
  * deliberately reject drift before a package can be published.
  */
-export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.19';
+export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.20';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/core/runtime/opencode-go.d.ts

@@ -37,16 +37,19 @@ export type OpenCodeGoMergeResult = {
         messages: number;
     };
     guessedRoutes: string[];
+    /** Model ids removed from the managed profiles because they left the live catalog. */
+    prunedModelIds?: string[];
 };
 /**
  * Fetch the live OpenCode Go catalog and merge the two Console profiles into
  * `configPath`, preserving every other section plus existing console fields
  * (`limits`, other profiles) and the existing `defaultProfile` unless
  * `setDefault` is passed. Model routing (`model`) is refreshed from the live
- * catalog, while per-model customizations (custom label, `reasoningEffort`,
- * `variants`) and models that disappeared upstream are kept. The written file
- * is re-validated with the same strict schema the runtime applies on load,
- * then replaced atomically.
+ * catalog, per-model customizations (custom label, `reasoningEffort`,
+ * `variants`) survive for models still in the catalog, and models that
+ * disappeared upstream are pruned so the Console never offers stale routes.
+ * The written file is re-validated with the same strict schema the runtime
+ * applies on load, then replaced atomically.
  */
 export declare function mergeOpenCodeGoConsoleProfiles(options: {
     configPath: string;

package/dist/core/runtime/opencode-go.js

@@ -163,10 +163,11 @@ function preservedModelFields(previous) {
  * `configPath`, preserving every other section plus existing console fields
  * (`limits`, other profiles) and the existing `defaultProfile` unless
  * `setDefault` is passed. Model routing (`model`) is refreshed from the live
- * catalog, while per-model customizations (custom label, `reasoningEffort`,
- * `variants`) and models that disappeared upstream are kept. The written file
- * is re-validated with the same strict schema the runtime applies on load,
- * then replaced atomically.
+ * catalog, per-model customizations (custom label, `reasoningEffort`,
+ * `variants`) survive for models still in the catalog, and models that
+ * disappeared upstream are pruned so the Console never offers stale routes.
+ * The written file is re-validated with the same strict schema the runtime
+ * applies on load, then replaced atomically.
  */
 export async function mergeOpenCodeGoConsoleProfiles(options) {
     const baseUrl = options.baseUrl ?? OPENCODE_GO_DEFAULT_BASE_URL;
@@ -184,8 +185,11 @@ export async function mergeOpenCodeGoConsoleProfiles(options) {
         : built.defaultProfile;
     // Merge per model, not per profile: discovery owns routing and the id list,
     // but a human's label, reasoningEffort, and variants must survive every
-    // re-discovery. Models that vanished upstream stay configured.
+    // re-discovery. Models that vanished upstream are pruned so the managed
+    // profiles mirror the live catalog instead of going stale; a failed or
+    // empty catalog fetch never reaches this loop (fetch throws first).
     const mergedProfiles = {};
+    const prunedModelIds = [];
     for (const [profileId, builtProfile] of Object.entries(built.profiles)) {
         const previousProfile = existingProfiles[profileId];
         const rawModels = typeof previousProfile === 'object' && previousProfile !== null
@@ -194,7 +198,7 @@ export async function mergeOpenCodeGoConsoleProfiles(options) {
         const previousModels = typeof rawModels === 'object' && rawModels !== null && !Array.isArray(rawModels)
             ? rawModels
             : {};
-        const models = { ...previousModels };
+        const models = {};
         for (const [modelId, entry] of Object.entries(builtProfile.models)) {
             models[modelId] = {
                 ...preservedModelFields(previousModels[modelId]),
@@ -202,6 +206,10 @@ export async function mergeOpenCodeGoConsoleProfiles(options) {
                 model: entry.model,
             };
         }
+        for (const modelId of Object.keys(previousModels)) {
+            if (!(modelId in models))
+                prunedModelIds.push(`${profileId}:${modelId}`);
+        }
         const previousDefaultModel = typeof previousProfile === 'object' && previousProfile !== null
             ? previousProfile.defaultModel
             : undefined;
@@ -232,6 +240,7 @@ export async function mergeOpenCodeGoConsoleProfiles(options) {
         defaultProfile,
         counts: built.counts,
         guessedRoutes: built.guessedRoutes,
+        prunedModelIds,
     };
 }
 //# sourceMappingURL=opencode-go.js.map

package/dist/elt/application/detached-sync.d.ts

@@ -8,6 +8,16 @@ export type DetachedSyncRequest = {
     provider?: DetachedSyncProvider;
     from?: string;
     refresh?: boolean;
+    /**
+     * The `--home` value the detached `catence-data` child must receive.
+     *
+     * Catalog deployments pass the catalog root here: `paths` points at the
+     * resolved athlete store (for locks/logs), but the child resolves
+     * `--athlete` within a catalog, so pointing `--home` at the store itself
+     * makes it fail with the legacy-store guard. Standalone stores omit this
+     * and default to `paths.root`.
+     */
+    cliHome?: string;
 };
 export type DetachedSyncHandle = {
     started: true;

package/dist/elt/application/detached-sync.js

@@ -1,7 +1,9 @@
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { open, mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { STALE_RUN_TIMEOUT_MS } from '../../contracts/progress.js';
 import { syncProgress } from './management.js';
 export const DETACHED_SYNC_PROVIDERS = ['intervals', 'garmin', 'strava', 'all'];
 /** Raised when another sync run is already active for this store. */
@@ -14,12 +16,25 @@ export class DetachedSyncBusyError extends Error {
     }
 }
 /**
- * Resolve the packaged `catence-data` CLI entry next to this module. In a
- * built install both live under dist/; source checkouts run through tsx and
- * tests inject their own spawner.
+ * Resolve how to launch the `catence-data` CLI next to this module.
+ *
+ * Built installs: both modules live under dist/, so the child is plain
+ * `node …/dist/interfaces/cli/main.js`. Source checkouts run through tsx,
+ * where the same relative path points at a nonexistent `.js` file — there the
+ * TypeScript entry is launched through the checkout's local tsx binary
+ * instead. Tests inject their own spawner and never reach this resolution.
  */
-function cliScriptPath() {
-    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../interfaces/cli/main.js');
+function cliInvocation() {
+    const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+    const builtEntry = path.resolve(moduleDirectory, '../../interfaces/cli/main.js');
+    if (existsSync(builtEntry))
+        return { command: process.execPath, entry: builtEntry };
+    const sourceEntry = path.resolve(moduleDirectory, '../../interfaces/cli/main.ts');
+    const tsxBinary = path.resolve(moduleDirectory, '../../../node_modules/.bin/tsx');
+    if (!existsSync(sourceEntry) || !existsSync(tsxBinary)) {
+        throw new Error(`Could not locate the catence-data CLI entry (tried ${builtEntry} and ${sourceEntry}). Install the package or run from a checkout with node_modules present.`);
+    }
+    return { command: tsxBinary, entry: sourceEntry };
 }
 function assertValidRequest(request) {
     if (!request.athleteId || !/^[a-z][a-z0-9-]{0,62}$/.test(request.athleteId)) {
@@ -46,14 +61,20 @@ export async function startDetachedSync(request, dependencies = {}) {
     assertValidRequest(request);
     const provider = request.provider ?? 'all';
     const snapshot = await syncProgress(request.paths);
-    const activeRun = snapshot.running[0];
+    // Belt-and-braces: syncProgress already age-filters stale runs, so this
+    // predicate only re-asserts the sidecar contract at the decision point —
+    // a heartbeat older than the stale timeout must never block a new run.
+    const activeRun = snapshot.running.find((state) => {
+        const ageMs = Date.now() - Date.parse(state.heartbeatAt);
+        return Number.isFinite(ageMs) && ageMs <= STALE_RUN_TIMEOUT_MS;
+    });
     if (activeRun)
         throw new DetachedSyncBusyError(activeRun.runId);
     const stamp = (dependencies.now ?? (() => new Date()))().toISOString().replace(/[:.]/g, '-');
     const logFile = path.join(request.paths.root, 'logs', `sync-${request.athleteId}-${stamp}.log`);
     await mkdir(path.dirname(logFile), { recursive: true });
     await writeFile(logFile, `[${new Date().toISOString()}] catence-data --athlete ${request.athleteId} sync --provider ${provider}${request.from ? ` --from ${request.from}` : ''}${request.refresh ? ' --refresh' : ''}\n`, 'utf8');
-    const arguments_ = [cliScriptPath(), '--home', request.paths.root, '--athlete', request.athleteId, 'sync', '--provider', provider];
+    const arguments_ = [cliInvocation().entry, '--home', request.cliHome ?? request.paths.root, '--athlete', request.athleteId, 'sync', '--provider', provider];
     if (request.from)
         arguments_.push('--from', request.from);
     if (request.refresh)
@@ -63,7 +84,7 @@ export async function startDetachedSync(request, dependencies = {}) {
     const logHandle = await open(logFile, 'a');
     try {
         const spawnProcess = dependencies.spawnProcess ?? spawn;
-        const child = spawnProcess(process.execPath, arguments_, {
+        const child = spawnProcess(cliInvocation().command, arguments_, {
             detached: true,
             stdio: ['ignore', logHandle.fd, logHandle.fd],
             env: process.env,

package/dist/elt/application/management.js

@@ -2,6 +2,9 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { EVENT_WINDOW_PAST_DAYS } from '../ingestion/providers/registry.js';
 import { createServer } from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -21,6 +24,46 @@ import { withDataWriteLock } from '../storage/write-lock.js';
 function packageRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
 }
+// Mirrors python/catence/providers/garmin/worker.py fetch windows: the events
+// listing looks back a year and scheduled workouts start three months ago, so
+// only rows inside those windows are authoritative for deletion sweeps.
+const GARMIN_EVENTS_LOOKBACK_DAYS = 365;
+const GARMIN_SCHEDULED_MONTHS_BACK = 3;
+/**
+ * Delete calendar entities that the latest Garmin listing no longer contains.
+ * The staging manifest is the authority on which ids were just fetched; any
+ * in-window row of the same type missing from it was deleted (or un-enrolled)
+ * upstream and would otherwise linger as a ghost.
+ */
+async function reconcileGarminCalendarEntities(database, stagedManifestPath) {
+    const events = [];
+    const scheduled = [];
+    const file = createReadStream(stagedManifestPath, { encoding: 'utf8' });
+    const lines = createInterface({ input: file, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue; // The importer owns malformed-line reporting.
+        }
+        const candidate = record;
+        if (candidate?.kind !== 'source_entity' || candidate.provider !== 'garmin')
+            continue;
+        if (candidate.entityType === 'event' && typeof candidate.remoteId === 'string')
+            events.push(candidate.remoteId);
+        if (candidate.entityType === 'scheduled_workout' && typeof candidate.remoteId === 'string')
+            scheduled.push(candidate.remoteId);
+    }
+    const now = new Date();
+    const eventCutoff = new Date(now.getTime() - GARMIN_EVENTS_LOOKBACK_DAYS * 86_400_000).toISOString().slice(0, 10);
+    const scheduledCutoff = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - GARMIN_SCHEDULED_MONTHS_BACK, 1)).toISOString().slice(0, 10);
+    await database.deleteMissingCalendarEntities('garmin', ['event'], events, eventCutoff);
+    await database.deleteMissingCalendarEntities('garmin', ['scheduled_workout'], scheduled, scheduledCutoff);
+}
 function baseProgress(runId, provider, stage) {
     return {
         runId, provider, stage, currentStep: null,
@@ -288,6 +331,15 @@ async function syncProvider(database, paths, provider, options, log) {
                 if (earliest)
                     arguments_.push('--lt-history-from', earliest);
             }
+            // Calendar-events coverage backfill: a store whose activities predate
+            // the short lookback gets exactly one deep pull (to its earliest
+            // activity); once an older event lands, normal syncs stay narrow.
+            const eventsShortFrom = new Date(Date.now() - EVENT_WINDOW_PAST_DAYS * 86_400_000).toISOString().slice(0, 10);
+            const needsEventBackfill = !(await database.hasCalendarEventOlderThan('garmin', eventsShortFrom));
+            const earliestActivity = needsEventBackfill ? await database.earliestActivityStartDate('garmin') : null;
+            if (needsEventBackfill && earliestActivity && earliestActivity < eventsShortFrom) {
+                arguments_.push('--events-from', earliestActivity);
+            }
             let interruptChild = null;
             await runWithInterruptGuard(runId, database, () => interruptChild?.(), guard, async () => {
                 const outcome = await runGarminWorker(runId, arguments_, {
@@ -302,6 +354,7 @@ async function syncProvider(database, paths, provider, options, log) {
                 if (!existsSync(output))
                     throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
                 await importJsonl(database, runId, output, log);
+                await reconcileGarminCalendarEntities(database, output);
                 if (provider === 'garmin') {
                     try {
                         await backfillGarminSwimLengths(database, paths, runId, log);

package/dist/elt/ingestion/providers/intervals.d.ts

@@ -13,6 +13,15 @@ export declare class IntervalsExtractor {
         fromDate: string;
         toDate: string;
     } | null, includeAccount?: boolean): Promise<void>;
+    /**
+     * Regular syncs reach back EVENT_WINDOW_PAST_DAYS — just enough to
+     * associate recently finished events with their activities. A store whose
+     * own activity history predates that span gets an automatic one-time
+     * coverage backfill instead: the window stretches to the earliest
+     * activity until an event older than the short window lands (self-
+     * clearing), after which deeper history is the backfill command's job.
+     */
+    private resolveEventsSyncWindow;
     private captureCollectionChildren;
     private getCollection;
     private captureActivity;

package/dist/elt/ingestion/providers/intervals.js

@@ -2,7 +2,7 @@ import { IntervalsClient } from 'intervals-icu';
 import { randomUUID } from 'node:crypto';
 import { stableJsonHash, storeArtifact, storeJsonArtifact } from '../../storage/artifacts.js';
 import { importRecord, queueWorkItem, completeWorkItem, failWorkItem } from '../importer.js';
-import { intervalsActivityReadEndpoints, intervalsSecondaryReadRegistry, assertReadOnlyRegistry } from './registry.js';
+import { intervalsActivityReadEndpoints, intervalsSecondaryReadRegistry, intervalsEventSyncWindow, assertReadOnlyRegistry } from './registry.js';
 import { intervalsStreamsToSamples, writeParquetSamples } from '../../streams.js';
 const apiBaseUrl = 'https://intervals.icu/api/v1';
 function asObject(value) {
@@ -67,6 +67,21 @@ export class IntervalsExtractor {
         for (const endpoint of intervalsSecondaryReadRegistry) {
             if (endpoint.name === 'athlete')
                 continue;
+            // Calendar events straddle today (past for activity association,
+            // future for planning); they must not inherit the cursor-bounded
+            // activity window, which always ends at today.
+            if (endpoint.name === 'events') {
+                const window = await this.resolveEventsSyncWindow();
+                const payload = await this.capture(runId, 'events', null, window, async () => this.getCollection('events', resolvedAthleteId, window.fromDate, window.toDate));
+                if (payload === undefined)
+                    continue;
+                await this.importEntities('event', 'events', payload, null, runId);
+                // The listing is authoritative: events deleted upstream must not
+                // linger as ghosts in the store once this sync succeeded.
+                const seenIds = asItems(payload).map((item) => idOf(item, '')).filter(Boolean);
+                await this.database.deleteMissingCalendarEntities('intervals', ['event'], seenIds, window.fromDate);
+                continue;
+            }
             if (!activityWindow)
                 continue;
             const { fromDate, toDate } = activityWindow;
@@ -86,6 +101,23 @@ export class IntervalsExtractor {
             }
         }
     }
+    /**
+     * Regular syncs reach back EVENT_WINDOW_PAST_DAYS — just enough to
+     * associate recently finished events with their activities. A store whose
+     * own activity history predates that span gets an automatic one-time
+     * coverage backfill instead: the window stretches to the earliest
+     * activity until an event older than the short window lands (self-
+     * clearing), after which deeper history is the backfill command's job.
+     */
+    async resolveEventsSyncWindow() {
+        const short = intervalsEventSyncWindow();
+        if (await this.database.hasCalendarEventOlderThan('intervals', short.fromDate))
+            return short;
+        const earliest = await this.database.earliestActivityStartDate('intervals');
+        if (!earliest || earliest >= short.fromDate)
+            return short;
+        return { fromDate: earliest, toDate: short.toDate };
+    }
     async captureCollectionChildren(runId, collection, payload, athleteId) {
         const children = {
             events: [{ suffix: (id) => `/athlete/${athleteId}/events/${id}`, entityType: 'event' }],

package/dist/elt/ingestion/providers/registry.d.ts

@@ -11,6 +11,19 @@ export declare const intervalsReadRegistry: readonly EndpointSpec[];
  * Garmin's activity detail, files, streams, or account data.
  */
 export declare const intervalsSecondaryReadRegistry: EndpointSpec[];
+/** How far back and ahead of today the planned-events fetch reaches. */
+/** Regular syncs look back a month for activity association; deeper history arrives via the automatic coverage backfill. */
+export declare const EVENT_WINDOW_PAST_DAYS = 30;
+export declare const EVENT_WINDOW_FUTURE_DAYS = 365;
+/**
+ * Deliberately cursor-free: activities chase a past-only incremental window,
+ * while calendar events must straddle today so upcoming races and recently
+ * completed ones (associatable with their finished activities) both arrive.
+ */
+export declare function intervalsEventSyncWindow(now?: Date): {
+    fromDate: string;
+    toDate: string;
+};
 export declare const intervalsActivityReadEndpoints: readonly ["activity", "streams", "intervals", "map", "weather", "weather_summary", "best_efforts", "power_curve", "pace_curve", "hr_curve", "power_vs_hr", "hr_load_model", "segments", "messages", "original_file", "fit_file", "gpx_file"];
 /** Read-only methods exposed by python-garminconnect, grouped for manifest tests and worker dispatch. */
 export declare const garminReadRegistry: readonly EndpointSpec[];

package/dist/elt/ingestion/providers/registry.js

@@ -21,7 +21,23 @@ export const intervalsReadRegistry = registry('intervals', [
  * supplies the separately named training calculations without duplicating
  * Garmin's activity detail, files, streams, or account data.
  */
-export const intervalsSecondaryReadRegistry = intervalsReadRegistry.filter((endpoint) => endpoint.name === 'athlete' || endpoint.name === 'activities');
+export const intervalsSecondaryReadRegistry = intervalsReadRegistry.filter((endpoint) => endpoint.name === 'athlete' || endpoint.name === 'activities' || endpoint.name === 'events');
+/** How far back and ahead of today the planned-events fetch reaches. */
+/** Regular syncs look back a month for activity association; deeper history arrives via the automatic coverage backfill. */
+export const EVENT_WINDOW_PAST_DAYS = 30;
+export const EVENT_WINDOW_FUTURE_DAYS = 365;
+/**
+ * Deliberately cursor-free: activities chase a past-only incremental window,
+ * while calendar events must straddle today so upcoming races and recently
+ * completed ones (associatable with their finished activities) both arrive.
+ */
+export function intervalsEventSyncWindow(now = new Date()) {
+    const dayMs = 86_400_000;
+    return {
+        fromDate: new Date(now.getTime() - EVENT_WINDOW_PAST_DAYS * dayMs).toISOString().slice(0, 10),
+        toDate: new Date(now.getTime() + EVENT_WINDOW_FUTURE_DAYS * dayMs).toISOString().slice(0, 10),
+    };
+}
 export const intervalsActivityReadEndpoints = [
     'activity', 'streams', 'intervals', 'map', 'weather', 'weather_summary', 'best_efforts', 'power_curve', 'pace_curve', 'hr_curve',
     'power_vs_hr', 'hr_load_model', 'segments', 'messages', 'original_file', 'fit_file', 'gpx_file',
@@ -43,6 +59,7 @@ export const garminReadRegistry = registry('garmin', [
     ['activity_power_zones', 'activity', 'activity_zone'], ['activity_exercise_sets', 'activity', 'activity_exercise_set'], ['activity_gear', 'activity', 'activity_gear'],
     ['activity_original', 'activity', 'activity_file'], ['activity_tcx', 'activity', 'activity_file'], ['activity_gpx', 'activity', 'activity_file'], ['activity_kml', 'activity', 'activity_file'],
     ['activity_csv', 'activity', 'activity_file'], ['workouts', 'collection', 'workout'], ['scheduled_workouts', 'date_range', 'scheduled_workout'],
+    ['events', 'collection', 'event'],
     ['training_plans', 'collection', 'training_plan'], ['goals', 'collection', 'goal'], ['personal_records', 'singleton', 'personal_record'],
     ['earned_badges', 'collection', 'badge'], ['available_badges', 'collection', 'badge'], ['challenges', 'collection', 'challenge'],
     ['gear', 'collection', 'gear'], ['golf_summary', 'collection', 'golf_scorecard'], ['golf_user_stats', 'singleton', 'golf_user_stat'],

package/dist/elt/storage/database.d.ts

@@ -20,7 +20,9 @@ export declare class CatenceDatabase implements WriteDataStore {
     heartbeatRun(runId: string, progress: SyncProgressState): Promise<void>;
     markRunInterrupted(runId: string, stage?: string): Promise<void>;
     interruptStaleSyncRuns(timeoutMs?: number): Promise<InterruptedRuns>;
-    syncProgress(): Promise<SyncProgressSnapshot>;
+    syncProgress(timeoutMs?: number): Promise<SyncProgressSnapshot>;
+    hasCalendarEventOlderThan(provider: Provider, beforeIsoDate: string, entityType?: string): Promise<boolean>;
+    deleteMissingCalendarEntities(provider: Provider, entityTypes: readonly string[], keepRemoteIds: readonly string[], minOccurredOn: string): Promise<void>;
     addError(runId: string, provider: Provider, endpoint: string, remoteId: string | null, message: string, retryable: boolean): Promise<void>;
     resolveErrors(opts?: {
         runIds?: string[];

package/dist/elt/storage/database.js

@@ -142,7 +142,14 @@ export class CatenceDatabase {
         }
         return { runIds: stale.map((row) => row.run_id) };
     }
-    async syncProgress() {
+    async syncProgress(timeoutMs = STALE_RUN_TIMEOUT_MS) {
+        // A run killed with its container (docker restart, OOM) keeps
+        // status='running' until something cleans it up, and that cleanup only
+        // runs inside a starting sync child — which the busy guard refuses to
+        // spawn while the row reads as active. Age-filtering here mirrors the
+        // sidecar contract: a heartbeat older than the stale timeout can never
+        // block a new run or disable the dashboard's Sync button forever.
+        const cutoff = new Date(Date.now() - timeoutMs).toISOString();
         const running = await this.rows(`SELECT runs.run_id, runs.provider,
          coalesce(progress.stage, 'starting') AS stage,
          progress.current_step AS current_step,
@@ -155,7 +162,8 @@ export class CatenceDatabase {
        FROM sync_runs AS runs
        LEFT JOIN sync_run_progress AS progress USING (run_id)
        WHERE runs.status = 'running'
-       ORDER BY runs.started_at DESC`);
+         AND coalesce(progress.heartbeat_at, runs.started_at) > $cutoff
+       ORDER BY runs.started_at DESC`, { cutoff });
         const recent = await this.rows(`SELECT progress.run_id, progress.provider, progress.stage, progress.current_step,
          progress.completed_units, progress.total_units, progress.percent, progress.elapsed_seconds,
          progress.estimated_remaining_seconds, cast(progress.heartbeat_at AS VARCHAR) AS heartbeat_at
@@ -164,6 +172,37 @@ export class CatenceDatabase {
        LIMIT 10`);
         return { running: running.map(toSyncProgressState), recent: recent.map(toSyncProgressState) };
     }
+    async hasCalendarEventOlderThan(provider, beforeIsoDate, entityType = 'event') {
+        // Coverage signal for the automatic calendar-events backfill: true once
+        // the store already holds an event older than the regular short window,
+        // meaning the one-time deep pull has landed and normal syncs can stay
+        // narrow. Athletes with genuinely no old events re-run the deep window;
+        // it costs one small paginated listing per sync.
+        const rows = await this.rows(`SELECT 1 FROM source_entities WHERE provider = $provider AND entity_type = $entityType AND occurred_on < $before LIMIT 1`, { provider, entityType, before: beforeIsoDate });
+        return rows.length > 0;
+    }
+    async deleteMissingCalendarEntities(provider, entityTypes, keepRemoteIds, minOccurredOn) {
+        // Calendar entities (joined races, scheduled workouts) are mutable and
+        // deletable upstream. Re-fetches upsert survivors via remote_id; this
+        // removes in-window rows absent from the latest authoritative listing so
+        // upstream deletions propagate instead of leaving ghosts forever. Rows
+        // without a date are preserved (they predate strict dating).
+        if (!entityTypes.length)
+            return;
+        const values = { provider, minOccurredOn };
+        const typePlaceholders = entityTypes.map((name, index) => {
+            values[`type${index}`] = name;
+            return `$type${index}`;
+        });
+        let keepClause = '';
+        if (keepRemoteIds.length) {
+            keepClause = ` AND remote_id NOT IN (${keepRemoteIds.map((_, index) => `$keep${index}`).join(', ')})`;
+            keepRemoteIds.forEach((id, index) => { values[`keep${index}`] = id; });
+        }
+        for (const table of ['source_entities', 'domain_entities']) {
+            await this.run(`DELETE FROM ${table} WHERE provider = $provider AND entity_type IN (${typePlaceholders}) AND occurred_on >= $minOccurredOn${keepClause}`, values);
+        }
+    }
     async addError(runId, provider, endpoint, remoteId, message, retryable) {
         await this.run(`INSERT INTO normalization_errors (error_id, run_id, provider, endpoint, remote_id, message, retryable)
        VALUES ($errorId, $runId, $provider, $endpoint, $remoteId, $message, $retryable)`, { errorId: randomUUID(), runId, provider, endpoint, remoteId, message, retryable });

package/dist/interfaces/http/server.js

@@ -1,7 +1,7 @@
 import { createServer } from 'node:http';
 import path from 'node:path';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { catenceRuntimeHealth, DashboardSnapshotService, dataStatus, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, startDetachedSync, syncProgress, } from '../../runtime/index.js';
+import { catenceRuntimeHealth, DashboardSnapshotService, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, resolveAthlete, resolveCatalogPaths, startDetachedSync, syncProgress, } from '../../runtime/index.js';
 import { createCatenceMcpServer } from '../mcp/server.js';
 const MAX_REQUEST_BYTES = 1_000_000;
 function json(response, statusCode, value) {
@@ -131,25 +131,37 @@ async function lastSyncSummary(paths) {
         return null;
     };
     try {
-        const status = await dataStatus(paths);
-        const runs = Array.isArray(status.syncRuns) ? status.syncRuns : [];
-        const completed = runs.filter((run) => String(run.status ?? '').startsWith('completed') && completedAtIso(run.completed_at));
-        const providers = {};
-        let lastCompletedAt = null;
-        for (const run of completed) {
-            const completedAt = completedAtIso(run.completed_at);
-            const provider = String(run.provider ?? 'unknown');
-            if (!providers[provider] || providers[provider] < completedAt)
-                providers[provider] = completedAt;
-            if (!lastCompletedAt || lastCompletedAt < completedAt)
-                lastCompletedAt = completedAt;
+        // Read-only repository on purpose: it exposes per-run history (`syncRuns`)
+        // and degrades through the typed lock-conflict error while a detached
+        // sync holds DuckDB's single-writer lock. The write-capable dataStatus()
+        // would both block here and has no run history at all.
+        const repository = await openReadOnlyRepository(paths);
+        try {
+            const status = await repository.status();
+            const runs = Array.isArray(status.syncRuns) ? status.syncRuns : [];
+            const completed = runs.filter((run) => String(run.status ?? '').startsWith('completed') && completedAtIso(run.completed_at));
+            const providers = {};
+            let lastCompletedAt = null;
+            for (const run of completed) {
+                const completedAt = completedAtIso(run.completed_at);
+                const provider = String(run.provider ?? 'unknown');
+                if (!providers[provider] || providers[provider] < completedAt)
+                    providers[provider] = completedAt;
+                if (!lastCompletedAt || lastCompletedAt < completedAt)
+                    lastCompletedAt = completedAt;
+            }
+            return { lastCompletedAt, providers, recentRuns: runs.slice(0, 5) };
+        }
+        finally {
+            await repository.close();
         }
-        return { lastCompletedAt, providers, recentRuns: runs.slice(0, 5) };
     }
-    catch (error) {
-        if (error instanceof ReadOnlyDatabaseError)
-            return null;
-        throw error;
+    catch {
+        // Best-effort by contract: while a detached sync holds the single-writer
+        // DuckDB lock, even opening a snapshot fails cross-process. Progress (from
+        // sidecar heartbeats) must still reach the dashboard, so any failure here
+        // degrades to "no last-sync summary" instead of failing /sync/status.
+        return null;
     }
 }
 async function handleMcpRequest(request, response, paths) {
@@ -271,7 +283,16 @@ export function createCatenceHttpServer(options = {}) {
                             discoveryWarning = `OpenCode Go model discovery failed; profiles were left unchanged (${error instanceof Error ? error.message : String(error)}).`;
                         }
                     }
-                    const handle = await startSync({ paths, athleteId: body.athleteId ?? 'local', provider: body.provider, from: body.from, refresh: body.refresh }, { spawnProcess: options.syncSpawnProcess });
+                    const handle = await startSync({
+                        paths,
+                        athleteId: body.athleteId ?? 'local',
+                        provider: body.provider,
+                        from: body.from,
+                        refresh: body.refresh,
+                        // The child resolves the athlete within the catalog, not within
+                        // the athlete store this route resolved for locks and logs.
+                        cliHome: catalogPaths ? catalogPaths.root : undefined,
+                    }, { spawnProcess: options.syncSpawnProcess });
                     json(response, 202, { ...handle, ...(discoveryWarning ? { warning: discoveryWarning } : {}), progressEndpoint: '/api/v1/sync/status' });
                 }
                 catch (error) {

package/docs/development.md

@@ -142,7 +142,7 @@ npm run catence-data -- --home "$CATENCE_HOME" sync --athlete alex --provider ga
 npm run catence-data -- --home "$CATENCE_HOME" build-retrieval-index --athlete alex
 
 # Hot-reload loop for MCP iteration (restarts on src/ change)
-npx tsx watch src/interfaces/mcp/main.ts -- --home "$CATENCE_HOME"
+npx tsx watch src/interfaces/mcp/main.ts --home "$CATENCE_HOME"
 
 # Tests (DuckDB integration tests use a 15s per-test timeout)
 npm test
@@ -157,15 +157,18 @@ npm run check
 The Console normally auto-starts a matching packaged runtime (`npx catence@<pinned>`). For development, point it at your live `tsx` runtime instead via `--mcp-url`:
 
 ```sh
-# Terminal 1 — live MCP/ELT runtime on loopback
-npx tsx watch src/interfaces/mcp/main.ts -- serve --home "$CATENCE_HOME" --host 127.0.0.1 --port 8787
+# Terminal 1 — live MCP/ELT runtime on loopback (no `--` separator; tsx
+# forwards arguments verbatim, so a bare `--` would reach the CLI unparsed)
+npx tsx watch src/interfaces/mcp/main.ts serve --home "$CATENCE_HOME" --host 127.0.0.1 --port 8787
 
-# Terminal 2 — Console using that runtime (no auto-started `npx` runtime)
+# Terminal 2 — Console using that runtime (no auto-started `npx` runtime).
+# The `console` npm script already ends in the `serve` subcommand, so extra
+# arguments after `--` are appended AFTER `serve` — never repeat it here.
 export CATENCE_CONSOLE_USERNAME='coach'
 export CATENCE_CONSOLE_PASSWORD_HASH="$(uv run --project console catence-console auth hash-password)"
 export CHAINLIT_AUTH_SECRET="$(openssl rand -hex 32)"
 export OPENAI_API_KEY='…'          # or ANTHROPIC_API_KEY / OPENCODE_API_KEY …
-npm run console -- serve --home "$CATENCE_HOME" --mcp-url http://127.0.0.1:8787/mcp --ui-port 8000
+npm run console -- --home "$CATENCE_HOME" --mcp-url http://127.0.0.1:8787/mcp --ui-port 8000
 # open http://127.0.0.1:8000
 ```
 
@@ -264,7 +267,7 @@ services:
                --home /data --ui-host 0.0.0.0 --ui-port 8000
                --mcp-host 0.0.0.0 --mcp-port 8787"
       # for no-restart TS hot-reload, replace the command with:
-      # npx tsx watch src/interfaces/mcp/main.ts -- serve --home /data --host 0.0.0.0 --port 8787
+      # npx tsx watch src/interfaces/mcp/main.ts serve --home /data --host 0.0.0.0 --port 8787
       # and run Console separately with --mcp-url
 
 volumes:
@@ -293,7 +296,7 @@ docker compose -f docker-compose.dev.yml --env-file .env.dev exec console \
   catence-data --home /data status --athlete alex
 ```
 
-An alternative that avoids running `npm` inside the mount loop is to keep the runtime on the host entirely: run `npx tsx watch src/interfaces/mcp/main.ts -- serve --home /srv/catence-dev ...` on the host and start the Console container with `--mcp-url http://host.docker.internal:8787/mcp` (or the host's Tailscale IP) and `--env-file .env.dev` — the same `--mcp-url` trick from the local Console section.
+An alternative that avoids running `npm` inside the mount loop is to keep the runtime on the host entirely: run `npx tsx watch src/interfaces/mcp/main.ts serve --home /srv/catence-dev ...` on the host and start the Console container with `--mcp-url http://host.docker.internal:8787/mcp` (or the host's Tailscale IP) and `--env-file .env.dev` — the same `--mcp-url` trick from the local Console section.
 
 ## Where secrets and model definitions live (dev and Docker)
 
@@ -323,3 +326,8 @@ Recommended dev defaults:
 - **Doctor reports runtime unreachable** — the Console was started without `--mcp-url` and its auto-started runtime is on a different port. Start the runtime explicitly and pass `--mcp-url http://127.0.0.1:8787/mcp` to the Console, or use `uv run --project console catence-console doctor --home "$CATENCE_HOME" --mcp-url http://127.0.0.1:8787/mcp`.
 - **Docker `run` container has a separate loopback** — `docker compose run` cannot see a `docker compose exec` MCP server. Use `exec` for `doctor`/`sync` against the running container, or use `run` only for one-off `setup`/`secret set` with `--value-stdin`.
 - **Refusing to initialize** — the data home contains unrelated files. The error lists them; only `config.json`, `console/`, and Chainlit's `.files/`, `.chainlit/`, `public/` are allowed alongside a catalog.
+- **Is a sync actually running? (no deploy scaffold needed)** — three checks, all safe while a sync holds the write lock:
+  1. Runtime status API: `curl -s "http://127.0.0.1:8787/api/v1/sync/status?athleteId=<id>" | jq '.progress.running'` (through the Console instead: `/api/v1/sync/status` behind your login).
+  2. Detached-child log files: `ls -t "$CATENCE_HOME/logs" | head`. A successful `POST /api/v1/sync` creates `logs/sync-<athlete>-<stamp>.log` before spawning, so an absent or empty `logs/` directory proves no detached sync ever started.
+  3. The MCP progress tools (`catence_sync_progress`) read the same heartbeats.
+- **Models page clutter** — unused shipped profiles can be hidden per device from the Models page (`Hide` on the profile card); hidden profiles disappear from the chat Model dropdown but stay configured, and are restored with `Unhide`. Hiding lives in the Console database, never in `config.json`.

package/docs/llm-providers.md

@@ -198,8 +198,10 @@ The script warns on stderr and skips any model that does not fit one of these
 families. Rerun it to refresh the model lists; existing profiles, limits, and
 `defaultProfile` are preserved unless `--set-default` is passed. Re-running
 never discards your own tweaks: per-model custom labels, `reasoningEffort`
-pins, and `variants` maps survive every refresh, and models that have dropped
-out of the live catalog stay configured.
+pins, and `variants` maps survive every refresh. Models that have dropped out
+of the live catalog are pruned from the managed profiles, so the Console never
+offers a route the gateway no longer serves; if a pruned model was the
+profile's default, discovery selects a current one instead.
 
 You do not have to run the script manually: the Console dashboard's **Sync
 data** button (and `POST /api/v1/sync` with `"refreshModels": true`) refreshes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0-beta.19",
+  "version": "0.2.0-beta.20",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {

package/pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
 
 [tool.uv.sources]
 # fork commit
-garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "732bf14602bce2ca22cb569ba6583c3229bf904d" }
+garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "cd4e3d9ef81a93681950138e08f57af226fd5735" }
 
 [tool.uv]
 package = false

package/python/catence/providers/garmin/cli.py

@@ -32,8 +32,13 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--lt-history-from",
         dest="lt_history_from",
+        type=date.fromisoformat,        help="Backfill lactate-threshold history from this date instead of the daily window.",
+    )
+    parser.add_argument(
+        "--events-from",
+        dest="events_from",
         type=date.fromisoformat,
-        help="Backfill lactate-threshold history from this date instead of the daily window.",
+        help="Fetch calendar events from this date instead of the default short lookback.",
     )
     return parser.parse_args()
 
@@ -79,6 +84,7 @@ def main() -> None:
             activity_to_date=args.activity_to_date,
             include_non_historical=not args.historical_only,
             lactate_threshold_history_from=args.lt_history_from,
+            events_from=args.events_from.isoformat() if args.events_from else None,
         )
     except WorkerInterrupted:
         reporter.finish("interrupted")

package/python/catence/providers/garmin/registry.py

@@ -32,6 +32,7 @@ GARMIN_READ_METHODS = {
         "get_activity_gear", "download_activity",
     ),
     "workouts": ("get_workouts", "get_scheduled_workouts"),
+    "events": ("get_events",),
     "goals": ("get_goals",),
     "gear": ("get_gear",),
     "golf": ("get_golf_summary",),

package/python/catence/providers/garmin/worker.py

@@ -109,6 +109,25 @@ def remote_id(payload: dict[str, Any], fallback: str) -> str:
     return fallback
 
 
+# Scheduled workouts are tiny calendar payloads (one GET per month), so a year
+# of lookahead costs little next to a normal Garmin sync. Months back keep
+# recently completed schedules associatable with their finished activities.
+SCHEDULED_WORKOUTS_MONTHS_BACK = 3
+SCHEDULED_WORKOUTS_MONTHS_AHEAD = 12
+
+# Regular syncs reach back only far enough to associate recently finished
+# events with their activities; deeper history arrives via the automatic
+# coverage backfill (the parent passes --events-from when the store's own
+# window predates this span).
+EVENTS_PAST_DAYS = 30
+
+
+def shift_month(base: date, offset: int) -> date:
+    """Return the first day of the month `offset` months from `base`'s month."""
+    total = base.year * 12 + (base.month - 1) + offset
+    return date(total // 12, total % 12 + 1, 1)
+
+
 def payload_date(payload: Mapping[str, Any]) -> str | None:
     """Return the first ISO calendar day exposed by a Garmin payload."""
     for key in ("calendarDate", "date", "until", "from", "timestamp", "timestampLocal", "startTimestampGMT"):
@@ -158,6 +177,7 @@ class GarminStagingWorker:
         activity_to_date: date | None = None,
         include_non_historical: bool = True,
         lactate_threshold_history_from: date | None = None,
+        events_from: str | None = None,
     ) -> None:
         assert_read_only_registry()
         end = to_date or date.today()
@@ -192,7 +212,7 @@ class GarminStagingWorker:
             self._activities(activity_from_date, activity_end)
         if include_non_historical:
             self._check_interrupted()
-            self._collections()
+            self._collections(events_from=events_from)
 
     def _capture(self, endpoint: str, action: Callable[[], Any], remote_id_value: str | None = None, scope: dict[str, Any] | None = None) -> tuple[Any | None, str | None]:
         try:
@@ -705,15 +725,33 @@ class GarminStagingWorker:
                         occurred_on=start_date[:10],
                     )
 
-    def _collections(self) -> None:
+    def _fetch_garmin_events(self, start_date: str) -> None:
+        """Fetch calendar events from start_date, following pagination."""
+        page = 1
+        while True:
+            payload, raw_hash = self._capture(
+                "garmin_events",
+                lambda page=page: self.api.get_events(start_date, limit=100, page=page),
+                scope={"startDate": start_date, "page": page},
+            )
+            items = payload if isinstance(payload, list) else []
+            if items:
+                self._entity("garmin_events", "event", items, raw_hash)
+            if len(items) < 100:
+                return
+            page += 1
+
+    def _collections(self, events_from: str | None = None) -> None:
         today = date.today()
         calls = {
-            "workouts": ("get_workouts", (), "workout"), "scheduled_workouts": ("get_scheduled_workouts", (today.year, today.month), "scheduled_workout"),
+            "workouts": ("get_workouts", (), "workout"),
             "goals": ("get_goals", (), "goal"), "golf_summary": ("get_golf_summary", (), "golf_scorecard"),
         }
+        months = [shift_month(today, offset) for offset in range(-SCHEDULED_WORKOUTS_MONTHS_BACK, SCHEDULED_WORKOUTS_MONTHS_AHEAD + 1)]
+        events_start = events_from or (today - timedelta(days=EVENTS_PAST_DAYS)).isoformat()
         if self.progress is not None:
             self.progress.set_stage("collections")
-            self.progress.advance(total=len(calls))
+            self.progress.advance(total=len(calls) + len(months) + 1)
         for index, (endpoint, (method, arguments, entity_type)) in enumerate(calls.items(), start=1):
             self._check_interrupted()
             if self.progress is not None:
@@ -723,3 +761,51 @@ class GarminStagingWorker:
                 self._entity(endpoint, entity_type, payload, raw_hash)
             if self.progress is not None:
                 self.progress.advance(completed=index)
+        # Scheduled workouts span past-to-future months so upcoming sessions
+        # surface ahead of time and recently completed ones stay associatable
+        # with their finished activities. The calendar service answers each
+        # month with a grid wrapper whose items live under `calendarItems`;
+        # empty months must stage nothing, and real items stage one row each
+        # with their own calendar date.
+        for month_index, month in enumerate(months, start=1):
+            self._check_interrupted()
+            payload, raw_hash = self._capture(
+                "scheduled_workouts",
+                lambda month=month: self.api.get_scheduled_workouts(month.year, month.month),
+                scope={"month": month.isoformat()},
+            )
+            items = payload.get("calendarItems") if isinstance(payload, Mapping) else payload
+            # itemType 'activity' entries are echoes of already-recorded
+            # activities (the activities endpoint owns those); only true
+            # scheduled workout templates belong in this entity family.
+            if items:
+                items = [item for item in items if isinstance(item, Mapping) and item.get("itemType") == "workout"]
+            if items:
+                self._entity("scheduled_workouts", "scheduled_workout", items, raw_hash)
+            if self.progress is not None:
+                self.progress.advance(completed=len(calls) + month_index)
+        # Joined events (races etc.) look back only far enough to associate
+        # finished activities; the parent widens start_date into a one-time
+        # coverage backfill when the store predates this span.
+        self._check_interrupted()
+        if self.progress is not None:
+            self.progress.advance(step="garmin_events")
+        self._fetch_garmin_events(events_start)
+        if self.progress is not None:
+            self.progress.advance(completed=len(calls) + len(months) + 1)
+
+    def _fetch_garmin_events(self, start_date: str) -> None:
+        """Fetch calendar events from start_date, following pagination."""
+        page = 1
+        while True:
+            payload, raw_hash = self._capture(
+                "garmin_events",
+                lambda page=page: self.api.get_events(start_date, limit=100, page=page),
+                scope={"startDate": start_date, "page": page},
+            )
+            items = payload if isinstance(payload, list) else []
+            if items:
+                self._entity("garmin_events", "event", items, raw_hash)
+            if len(items) < 100:
+                return
+            page += 1

package/uv.lock

@@ -47,7 +47,7 @@ dev = [
 requires-dist = [
     { name = "duckdb", specifier = ">=1.4.0" },
     { name = "fitdecode", specifier = ">=0.10.0" },
-    { name = "garminconnect", git = "https://github.com/rifusaki/python-garminconnect.git?rev=732bf14602bce2ca22cb569ba6583c3229bf904d" },
+    { name = "garminconnect", git = "https://github.com/rifusaki/python-garminconnect.git?rev=cd4e3d9ef81a93681950138e08f57af226fd5735" },
     { name = "polars", specifier = ">=1.0.0" },
     { name = "pyarrow", specifier = ">=18.0.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -318,8 +318,8 @@ wheels = [
 
 [[package]]
 name = "garminconnect"
-version = "0.3.8"
-source = { git = "https://github.com/rifusaki/python-garminconnect.git?rev=732bf14602bce2ca22cb569ba6583c3229bf904d#732bf14602bce2ca22cb569ba6583c3229bf904d" }
+version = "0.3.12"
+source = { git = "https://github.com/rifusaki/python-garminconnect.git?rev=cd4e3d9ef81a93681950138e08f57af226fd5735#cd4e3d9ef81a93681950138e08f57af226fd5735" }
 dependencies = [
     { name = "curl-cffi" },
     { name = "requests" },