catence 0.2.1-beta.14 → 0.2.1-beta.16

package/README.md

@@ -120,7 +120,7 @@ Optional local Streamable HTTP MCP and HTTP APIs:
 catence serve --host 127.0.0.1 --port 8787
 ```
 
-`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. `POST /api/v1/athletes` creates a catalog athlete (`{"id": "sam", "label": "Sam", "setDefault": false}`); the packaged Console exposes the same call to admins from **Settings → Athletes**. The MCP server has no authentication of its own unless `--auth-token-file` (or `CATENCE_MCP_TOKEN_FILE`) requires a bearer token on every endpoint except the health probes.
+`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. `POST /api/v1/athletes` creates a catalog athlete (`{"id": "sam", "label": "Sam", "setDefault": false}`); the packaged Console exposes the same call to admins from **Settings → Athletes**. The MCP server has no authentication of its own beyond the optional bearer-token gate: `catence-data mcp enable` generates a token at `<home>/mcp-token` and every endpoint except the health probes then requires `Authorization: Bearer <token>`; `mcp status`/`mcp token`/`mcp disable` manage it, and the Console Settings expose the same controls to admins.
 
 ## Configuration
 

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.1-beta.14";
+export declare const CATENCE_RUNTIME_VERSION = "0.2.1-beta.16";
 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.1-beta.14';
+export const CATENCE_RUNTIME_VERSION = '0.2.1-beta.16';
 export const CATENCE_PROTOCOL_VERSION = 1;
 export function catenceRuntimeHealth() {
     return {

package/dist/core/retrieval/index.js

@@ -128,12 +128,30 @@ export async function buildRetrievalIndex(database) {
     await database.run('BEGIN TRANSACTION');
     try {
         await database.run('DELETE FROM retrieval_documents');
-        for (const document of deduplicated.values()) {
-            const id = documentId(document);
-            await database.run(`INSERT INTO retrieval_documents (document_id, entity_type, entity_id, activity_source_id, provider, occurred_on, document_text, metadata_json, content_hash)
-        VALUES ($id, $entityType, $entityId, $activitySourceId, $provider, $occurredOn, $text, $metadata, $hash)`, {
-                id, entityType: document.entityType, entityId: document.entityId, activitySourceId: document.activitySourceId ?? null, provider: document.provider ?? null, occurredOn: document.occurredOn || null, text: document.text, metadata: JSON.stringify(document.metadata), hash: id,
+        // Multi-row INSERT batches: one statement per 500 documents instead of
+        // one round trip per document keeps a full 125k-document rebuild from
+        // being dominated by per-statement overhead.
+        const BATCH_SIZE = 500;
+        const allDocuments = [...deduplicated.values()];
+        for (let offset = 0; offset < allDocuments.length; offset += BATCH_SIZE) {
+            const batch = allDocuments.slice(offset, offset + BATCH_SIZE);
+            const values = {};
+            const tuples = batch.map((document, index) => {
+                const id = documentId(document);
+                const prefix = `d${index}`;
+                values[`${prefix}id`] = id;
+                values[`${prefix}entityType`] = document.entityType;
+                values[`${prefix}entityId`] = document.entityId;
+                values[`${prefix}activitySourceId`] = document.activitySourceId ?? null;
+                values[`${prefix}provider`] = document.provider ?? null;
+                values[`${prefix}occurredOn`] = document.occurredOn || null;
+                values[`${prefix}text`] = document.text;
+                values[`${prefix}metadata`] = JSON.stringify(document.metadata);
+                values[`${prefix}hash`] = id;
+                return `($${prefix}id, $${prefix}entityType, $${prefix}entityId, $${prefix}activitySourceId, $${prefix}provider, $${prefix}occurredOn, $${prefix}text, $${prefix}metadata, $${prefix}hash)`;
             });
+            await database.run(`INSERT INTO retrieval_documents (document_id, entity_type, entity_id, activity_source_id, provider, occurred_on, document_text, metadata_json, content_hash)
+        VALUES ${tuples.join(', ')}`, values);
         }
         await database.run(`INSERT INTO retrieval_index_state (index_name, status, mode, source_watermark, built_at, detail_json)
       VALUES ('context', 'ready', $mode, $watermark, now(), $detail)

package/dist/elt/application/autosync.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { type CatalogPaths } from '../../core/runtime/catalog.js';
+import type { CatencePaths } from '../../contracts/runtime.js';
+import { startDetachedSync, type DetachedSyncHandle } from './detached-sync.js';
+/** The sync cadences the scheduler accepts, in minutes. */
+export declare const AUTO_SYNC_INTERVAL_MINUTES: readonly [15, 30, 60, 120, 360, 720, 1440];
+export type AutoSyncIntervalMinutes = (typeof AUTO_SYNC_INTERVAL_MINUTES)[number];
+/** Auto-sync is on by default at 2h: fresh data several times a day, far inside provider limits. */
+export declare const DEFAULT_AUTO_SYNC_INTERVAL_MINUTES: AutoSyncIntervalMinutes;
+declare const autoSyncFileSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    intervalMinutes: z.ZodNumber & z.ZodType<15 | 60 | 30 | 360 | 120 | 720 | 1440, number, z.core.$ZodTypeInternals<15 | 60 | 30 | 360 | 120 | 720 | 1440, number>>;
+    lastTriggeredAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    lastLogFile: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type AutoSyncConfig = z.infer<typeof autoSyncFileSchema>;
+export type AutoSyncSchedule = {
+    athleteId: string;
+    enabled: boolean;
+    intervalMinutes: AutoSyncIntervalMinutes;
+    intervalOptions: ReadonlyArray<{
+        minutes: AutoSyncIntervalMinutes;
+        label: string;
+    }>;
+    lastTriggeredAt: string | null;
+    lastLogFile: string | null;
+    nextRunAt: string | null;
+};
+export declare function autoSyncFilePath(paths: CatencePaths): string;
+/**
+ * Parse one of the interval labels the UI and CLI accept (`15m`, `2h`, `24h`)
+ * or a bare minute count into a valid cadence. Anything else is rejected at
+ * the boundary so stored state can never hold an unsupported interval.
+ */
+export declare function parseAutoSyncInterval(value: string): AutoSyncIntervalMinutes;
+/**
+ * Read the athlete's schedule. A missing file means "on by default": the
+ * effective schedule is reported without writing anything, so a fresh store
+ * stays pristine until the first explicit change (the scheduler does write
+ * trigger bookkeeping once it actually fires).
+ */
+export declare function readAutoSyncSchedule(paths: CatencePaths, athleteId: string): Promise<AutoSyncSchedule>;
+/**
+ * Apply an explicit schedule change (UI or CLI). Only the requested fields
+ * change; trigger bookkeeping survives an interval switch or a pause.
+ */
+export declare function updateAutoSyncSchedule(paths: CatencePaths, athleteId: string, change: {
+    enabled?: boolean;
+    intervalMinutes?: AutoSyncIntervalMinutes;
+}): Promise<AutoSyncSchedule>;
+export type AutoSyncSchedulerOptions = {
+    catalogPaths: CatalogPaths;
+    /** Internal compatibility hook for tests. */
+    startSync?: (request: Parameters<typeof startDetachedSync>[0]) => Promise<DetachedSyncHandle>;
+    now?: () => Date;
+    /** How often due schedules are checked; default every 30 seconds. */
+    tickMs?: number;
+};
+export type AutoSyncScheduler = {
+    stop(): void;
+};
+/**
+ * The auto-sync scheduler: a periodic timer that triggers a detached sync for
+ * every athlete whose schedule is due. It opens no database connection and
+ * takes no locks — the detached child and the single-writer DuckDB lock stay
+ * the only sync executors, so an already-running sync simply makes the tick a
+ * no-op (DetachedSyncBusyError is skipped quietly and retried on a later
+ * tick, once the active run has finished).
+ */
+export declare function startAutoSyncScheduler(options: AutoSyncSchedulerOptions): AutoSyncScheduler;
+export {};

package/dist/elt/application/autosync.js

@@ -0,0 +1,173 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { athleteStorePaths, loadCatalog } from '../../core/runtime/catalog.js';
+import { createSyncLogger } from '../../core/logging.js';
+import { DetachedSyncBusyError, startDetachedSync } from './detached-sync.js';
+/** The sync cadences the scheduler accepts, in minutes. */
+export const AUTO_SYNC_INTERVAL_MINUTES = [15, 30, 60, 120, 360, 720, 1440];
+/** Auto-sync is on by default at 2h: fresh data several times a day, far inside provider limits. */
+export const DEFAULT_AUTO_SYNC_INTERVAL_MINUTES = 120;
+const INTERVAL_CHOICE_LABELS = new Map([
+    [15, '15m'], [30, '30m'], [60, '1h'], [120, '2h'], [360, '6h'], [720, '12h'], [1440, '24h'],
+]);
+const autoSyncFileSchema = z.object({
+    enabled: z.boolean(),
+    intervalMinutes: z.number().int().refine((value) => AUTO_SYNC_INTERVAL_MINUTES.includes(value), 'intervalMinutes must be one of 15, 30, 60, 120, 360, 720, 1440.'),
+    lastTriggeredAt: z.string().datetime().nullable().default(null),
+    lastLogFile: z.string().nullable().default(null),
+}).strict();
+export function autoSyncFilePath(paths) {
+    return path.join(paths.root, 'autosync.json');
+}
+/**
+ * Parse one of the interval labels the UI and CLI accept (`15m`, `2h`, `24h`)
+ * or a bare minute count into a valid cadence. Anything else is rejected at
+ * the boundary so stored state can never hold an unsupported interval.
+ */
+export function parseAutoSyncInterval(value) {
+    const trimmed = value.trim().toLowerCase();
+    const match = /^(\d+)(m|h)$/.exec(trimmed);
+    const minutes = match ? (match[2] === 'h' ? Number(match[1]) * 60 : Number(match[1])) : Number(trimmed);
+    if (Number.isInteger(minutes) && AUTO_SYNC_INTERVAL_MINUTES.includes(minutes)) {
+        return minutes;
+    }
+    throw new Error(`interval must be one of: ${[...INTERVAL_CHOICE_LABELS.values()].join(', ')}.`);
+}
+function defaultConfig() {
+    return { enabled: true, intervalMinutes: DEFAULT_AUTO_SYNC_INTERVAL_MINUTES, lastTriggeredAt: null, lastLogFile: null };
+}
+function nextRunAt(config) {
+    if (!config.enabled || !config.lastTriggeredAt)
+        return null;
+    return new Date(Date.parse(config.lastTriggeredAt) + config.intervalMinutes * 60_000).toISOString();
+}
+function toSchedule(athleteId, config) {
+    return {
+        athleteId,
+        enabled: config.enabled,
+        intervalMinutes: config.intervalMinutes,
+        intervalOptions: AUTO_SYNC_INTERVAL_MINUTES.map((minutes) => ({ minutes, label: INTERVAL_CHOICE_LABELS.get(minutes) ?? `${minutes}m` })),
+        lastTriggeredAt: config.lastTriggeredAt,
+        lastLogFile: config.lastLogFile,
+        nextRunAt: nextRunAt(config),
+    };
+}
+function isMissingFile(error) {
+    return typeof error === 'object' && error !== null && error.code === 'ENOENT';
+}
+async function readEffectiveConfig(paths) {
+    let raw;
+    try {
+        raw = await readFile(autoSyncFilePath(paths), 'utf8');
+    }
+    catch (error) {
+        if (!isMissingFile(error))
+            throw error;
+        return defaultConfig();
+    }
+    const parsed = autoSyncFileSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success) {
+        throw new Error(`autosync.json is not a valid auto-sync schedule (${parsed.error.issues[0]?.message ?? 'unknown issue'}).`);
+    }
+    return parsed.data;
+}
+/**
+ * Read the athlete's schedule. A missing file means "on by default": the
+ * effective schedule is reported without writing anything, so a fresh store
+ * stays pristine until the first explicit change (the scheduler does write
+ * trigger bookkeeping once it actually fires).
+ */
+export async function readAutoSyncSchedule(paths, athleteId) {
+    return toSchedule(athleteId, await readEffectiveConfig(paths));
+}
+async function writeAutoSyncConfig(paths, config) {
+    const file = autoSyncFilePath(paths);
+    // A freshly added athlete has no store directory yet; the schedule file is
+    // often its first artifact.
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    await rename(temporary, file);
+}
+/**
+ * Apply an explicit schedule change (UI or CLI). Only the requested fields
+ * change; trigger bookkeeping survives an interval switch or a pause.
+ */
+export async function updateAutoSyncSchedule(paths, athleteId, change) {
+    const current = await readEffectiveConfig(paths);
+    const updated = {
+        ...current,
+        ...(change.enabled === undefined ? {} : { enabled: change.enabled }),
+        ...(change.intervalMinutes === undefined ? {} : { intervalMinutes: change.intervalMinutes }),
+    };
+    await writeAutoSyncConfig(paths, updated);
+    return toSchedule(athleteId, updated);
+}
+/** Record that the scheduler fired (or attempted to fire) for this athlete. */
+async function recordTrigger(paths, logFile, at) {
+    const config = await readEffectiveConfig(paths);
+    await writeAutoSyncConfig(paths, { ...config, lastTriggeredAt: at.toISOString(), lastLogFile: logFile });
+}
+/**
+ * The auto-sync scheduler: a periodic timer that triggers a detached sync for
+ * every athlete whose schedule is due. It opens no database connection and
+ * takes no locks — the detached child and the single-writer DuckDB lock stay
+ * the only sync executors, so an already-running sync simply makes the tick a
+ * no-op (DetachedSyncBusyError is skipped quietly and retried on a later
+ * tick, once the active run has finished).
+ */
+export function startAutoSyncScheduler(options) {
+    const startSync = options.startSync ?? startDetachedSync;
+    const now = options.now ?? (() => new Date());
+    const tickMs = options.tickMs ?? 30_000;
+    let ticking = false;
+    const tick = async () => {
+        if (ticking)
+            return; // Never overlap ticks; the in-flight one wins.
+        ticking = true;
+        try {
+            const catalog = await loadCatalog(options.catalogPaths);
+            await Promise.allSettled(catalog.athletes.map(async (athlete) => {
+                const paths = athleteStorePaths(options.catalogPaths, athlete.id);
+                const log = createSyncLogger(paths);
+                try {
+                    const config = await readEffectiveConfig(paths);
+                    if (!config.enabled)
+                        return;
+                    const dueAt = config.lastTriggeredAt ? Date.parse(config.lastTriggeredAt) + config.intervalMinutes * 60_000 : 0;
+                    if (now().getTime() < dueAt)
+                        return;
+                    const handle = await startSync({ paths, athleteId: athlete.id, provider: 'all', cliHome: options.catalogPaths.root });
+                    await recordTrigger(paths, handle.logFile, now());
+                    log.info('Auto-sync triggered', { athleteId: athlete.id, intervalMinutes: config.intervalMinutes, logFile: handle.logFile });
+                }
+                catch (error) {
+                    if (error instanceof DetachedSyncBusyError)
+                        return; // A run is active; retry on a later tick.
+                    // Any other failure is recorded as a trigger attempt so a broken
+                    // store cannot be hammered every tick; the next cadence retries.
+                    await recordTrigger(paths, null, now()).catch(() => undefined);
+                    log.error('Auto-sync trigger failed', { athleteId: athlete.id, error: error instanceof Error ? error.message : String(error) });
+                }
+            }));
+        }
+        catch (error) {
+            process.stderr.write(`[catence] Auto-sync tick failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+        finally {
+            ticking = false;
+        }
+    };
+    const timer = setInterval(() => { void tick(); }, tickMs);
+    timer.unref?.();
+    // The first tick is immediate: a restart should heal stale data within a
+    // minute instead of waiting a full interval.
+    void tick();
+    return {
+        stop() {
+            clearInterval(timer);
+        },
+    };
+}
+//# sourceMappingURL=autosync.js.map

package/dist/elt/application/management.js

@@ -114,9 +114,16 @@ async function backfillGarminSwimLengths(database, paths, parentRunId, log) {
     }
     // The swim list is queried here and handed to the Python worker as a file:
     // the child must never open DuckDB itself because the parent holds the
-    // write lock for the whole run.
+    // write lock for the whole run. Only activities without per-length rows are
+    // handed over: re-parsing every archived FIT on every sync cost ~23s/run
+    // with nothing new to stage.
     const activitiesFile = path.join(paths.staging, 'garmin', `${parentRunId}.swim_activities.json`);
-    await writeFile(activitiesFile, JSON.stringify(await database.garminSwimActivitySources()));
+    const pendingSwims = await database.garminSwimActivitySourcesWithoutLengths();
+    if (pendingSwims.length === 0) {
+        log.info('Garmin swim backfill skipped: every swim activity already has lengths', { parentRunId });
+        return;
+    }
+    await writeFile(activitiesFile, JSON.stringify(pendingSwims));
     const arguments_ = [
         'run',
         'python',

package/dist/elt/ingestion/importer.d.ts

@@ -1,7 +1,17 @@
 import type { CatenceDatabase } from '../storage/database.js';
 import { type StagingRecord } from '../../contracts/staging.js';
 import type { SyncLogger } from '../../core/logging.js';
-export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord, log?: SyncLogger): Promise<void>;
+/**
+ * Per-pass import state. When present, activity-quality refreshes are
+ * deferred to the end of the pass: a staging file lists an activity before
+ * its detail records, so refreshing inline would compute flags from partial
+ * data, and one refresh per activity is enough regardless of how many
+ * detail entity types follow it.
+ */
+export type ImportPassContext = {
+    deferredQualityActivityIds: Set<string>;
+};
+export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord, log?: SyncLogger, pass?: ImportPassContext): Promise<void>;
 export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string, log?: SyncLogger): Promise<number>;
 export declare function importSingleStagingFile(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
 export declare function queueWorkItem(database: CatenceDatabase, runId: string, provider: 'intervals' | 'garmin' | 'strava', endpoint: string, remoteId: string | null, scope: unknown): Promise<string>;

package/dist/elt/ingestion/importer.js

@@ -7,7 +7,12 @@ import { importSourceEntity, refreshActivityQuality } from '../normalization/nor
 import { normalizeStravaEntity } from '../normalization/segments/strava-normalizer.js';
 import { reconcileActivityLink } from '../normalization/activities/linking.js';
 import { json } from '../storage/sql.js';
-export async function importRecord(database, runId, record, log) {
+const GARMIN_ACTIVITY_DETAIL_ENTITY_TYPES = ['activity_detail', 'activity_interval', 'activity_exercise_set', 'activity_swim_lengths'];
+async function activityIdForSource(database, activitySourceId) {
+    const activity = await database.rows('SELECT activity_id FROM activity_sources WHERE activity_source_id = $activitySourceId', { activitySourceId });
+    return activity[0]?.activity_id ?? null;
+}
+export async function importRecord(database, runId, record, log, pass) {
     if (record.kind === 'run_manifest') {
         if (record.runId !== runId)
             throw new Error(`Staging manifest run ${record.runId} does not match importer run ${runId}.`);
@@ -29,14 +34,14 @@ export async function importRecord(database, runId, record, log) {
             await importSourceEntity(database, record);
         if (record.entityType === 'activity') {
             await reconcileActivityLink(database, record.provider + ':' + record.remoteId);
-            const activity = await database.rows('SELECT activity_id FROM activity_sources WHERE activity_source_id = $activitySourceId', { activitySourceId: record.provider + ':' + record.remoteId });
-            if (activity[0]?.activity_id)
-                await refreshActivityQuality(database, activity[0].activity_id);
+            const activityId = await activityIdForSource(database, record.provider + ':' + record.remoteId);
+            if (activityId)
+                await queueActivityQualityRefresh(database, activityId, pass);
         }
-        if (record.provider === 'garmin' && ['activity_detail', 'activity_interval', 'activity_exercise_set', 'activity_swim_lengths'].includes(record.entityType) && record.parentRemoteId) {
-            const activity = await database.rows('SELECT activity_id FROM activity_sources WHERE activity_source_id = $activitySourceId', { activitySourceId: `garmin:${record.parentRemoteId}` });
-            if (activity[0]?.activity_id)
-                await refreshActivityQuality(database, activity[0].activity_id);
+        if (record.provider === 'garmin' && GARMIN_ACTIVITY_DETAIL_ENTITY_TYPES.includes(record.entityType) && record.parentRemoteId) {
+            const activityId = await activityIdForSource(database, `garmin:${record.parentRemoteId}`);
+            if (activityId)
+                await queueActivityQualityRefresh(database, activityId, pass);
         }
         return;
     }
@@ -56,17 +61,57 @@ export async function importRecord(database, runId, record, log) {
     await database.addError(runId, record.provider, record.endpoint, record.remoteId, record.message, record.retryable);
     log?.warn('Staging record reported an extraction error', { runId, provider: record.provider, endpoint: record.endpoint, remoteId: record.remoteId, error: record.message });
 }
+/**
+ * Refresh now (single-record callers) or defer to the end of the pass
+ * (bulk importJsonl callers) — see ImportPassContext.
+ */
+async function queueActivityQualityRefresh(database, activityId, pass) {
+    if (pass) {
+        pass.deferredQualityActivityIds.add(activityId);
+        return;
+    }
+    await refreshActivityQuality(database, activityId);
+}
+/** Records per transaction: large enough to amortize DuckDB commits, small enough to bound a mid-file failure. */
+const IMPORT_CHUNK_SIZE = 200;
 export async function importJsonl(database, runId, filePath, log) {
     let count = 0;
+    const pass = { deferredQualityActivityIds: new Set() };
     const file = createReadStream(filePath, { encoding: 'utf8' });
     const lines = createInterface({ input: file, crlfDelay: Infinity });
-    for await (const line of lines) {
-        if (!line.trim())
-            continue;
-        const record = stagingRecordSchema.parse(JSON.parse(line));
-        await importRecord(database, runId, record, log);
-        count += 1;
+    let inTransaction = false;
+    const startedAt = Date.now();
+    try {
+        for await (const line of lines) {
+            if (!line.trim())
+                continue;
+            if (count % IMPORT_CHUNK_SIZE === 0) {
+                await database.run('BEGIN TRANSACTION');
+                inTransaction = true;
+            }
+            const record = stagingRecordSchema.parse(JSON.parse(line));
+            await importRecord(database, runId, record, log, pass);
+            count += 1;
+            if (count % IMPORT_CHUNK_SIZE === 0) {
+                await database.run('COMMIT');
+                inTransaction = false;
+            }
+        }
+    }
+    catch (error) {
+        if (inTransaction)
+            await database.run('ROLLBACK');
+        throw error;
+    }
+    const qualityStartedAt = Date.now();
+    for (const activityId of pass.deferredQualityActivityIds) {
+        await refreshActivityQuality(database, activityId);
     }
+    log?.info('Staging import finished with stage timings', {
+        runId, records: count, durationMs: Date.now() - startedAt,
+        qualityRefreshes: pass.deferredQualityActivityIds.size,
+        qualityRefreshMs: Date.now() - qualityStartedAt,
+    });
     return count;
 }
 export async function importSingleStagingFile(database, runId, filePath) {

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

@@ -27,6 +27,13 @@ export declare class IntervalsExtractor {
     private captureActivity;
     private capture;
     private importEntities;
+    /**
+     * Intervals.icu enforces 2500 requests per rolling 15 minutes and 5000 per
+     * day; over-limit calls answer 429 with a Retry-After header. Back off
+     * cooperatively and retry a bounded number of times so one auto-sync run
+     * degrades instead of recording a wall of retryable errors.
+     */
+    private request;
     private getJson;
     private getBinary;
 }

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

@@ -243,14 +243,33 @@ export class IntervalsExtractor {
             }
         }
     }
+    /**
+     * Intervals.icu enforces 2500 requests per rolling 15 minutes and 5000 per
+     * day; over-limit calls answer 429 with a Retry-After header. Back off
+     * cooperatively and retry a bounded number of times so one auto-sync run
+     * degrades instead of recording a wall of retryable errors.
+     */
+    async request(route, accept) {
+        for (let attempt = 0;; attempt++) {
+            const headers = { Authorization: basicAuth(this.apiKey) };
+            if (accept)
+                headers.Accept = accept;
+            const response = await fetch(`${apiBaseUrl}${route}`, { headers });
+            if (response.status !== 429 || attempt >= 2)
+                return response;
+            const retryAfterSeconds = Math.min(Math.max(Number(response.headers.get('retry-after')) || 30, 1), 300);
+            this.log.warn('Intervals rate limit hit; backing off', { route, retryAfterSeconds, attempt: attempt + 1 });
+            await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1_000));
+        }
+    }
     async getJson(route) {
-        const response = await fetch(`${apiBaseUrl}${route}`, { headers: { Authorization: basicAuth(this.apiKey), Accept: 'application/json' } });
+        const response = await this.request(route, 'application/json');
         if (!response.ok)
             throw new Error(`Intervals ${route} failed with HTTP ${response.status}`);
         return response.json();
     }
     async getBinary(route) {
-        const response = await fetch(`${apiBaseUrl}${route}`, { headers: { Authorization: basicAuth(this.apiKey) } });
+        const response = await this.request(route, null);
         if (!response.ok)
             throw new Error(`Intervals ${route} failed with HTTP ${response.status}`);
         return new Uint8Array(await response.arrayBuffer());

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

@@ -60,7 +60,12 @@ export declare class CatenceDatabase implements WriteDataStore {
     knownActivitySummaryHashes(provider: Provider): Promise<Record<string, string>>;
     hasGarminLactateThresholdHistory(): Promise<boolean>;
     earliestActivityStartDate(provider: Provider): Promise<string | null>;
-    garminSwimActivitySources(): Promise<Array<{
+    /**
+     * Swim activities that still lack per-length rows: the FIT backfill only
+     * has work to do for these, so syncs skip re-parsing already-derived
+     * archives entirely.
+     */
+    garminSwimActivitySourcesWithoutLengths(): Promise<Array<{
         remote_activity_id: string;
         started_on: string | null;
     }>>;

package/dist/elt/storage/database.js

@@ -319,13 +319,19 @@ export class CatenceDatabase {
          JOIN activity_sources source USING (activity_id) WHERE source.provider = $provider`, { provider });
         return toIsoDate(rows[0]?.earliest ?? null);
     }
-    async garminSwimActivitySources() {
+    /**
+     * Swim activities that still lack per-length rows: the FIT backfill only
+     * has work to do for these, so syncs skip re-parsing already-derived
+     * archives entirely.
+     */
+    async garminSwimActivitySourcesWithoutLengths() {
         const sports = ['lap_swimming', 'swimming', 'open_water_swimming', 'openwaterswimming'];
         return this.rows(`SELECT source.remote_activity_id, cast(activity.started_at_utc AS VARCHAR) AS started_on
          FROM activity_sources AS source
          JOIN activities AS activity USING (activity_id)
         WHERE source.provider = 'garmin'
           AND lower(coalesce(activity.sport, '')) IN (${sports.map((sport) => `'${sport}'`).join(', ')})
+          AND NOT EXISTS (SELECT 1 FROM swim_lengths WHERE swim_lengths.activity_source_id = source.activity_source_id)
         ORDER BY activity.started_at_utc`);
     }
     async latestSourceDate(provider, cursorName) {

package/dist/interfaces/cli/commands.js

@@ -2,7 +2,8 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, deleteAthleteSecret, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, reimportWeight, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
+import { defaultBearerTokenPath, disableBearerToken, ensureBearerToken, mcpExposureStatus, readBearerToken, } from '../http/cli-options.js';
+import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, deleteAthleteSecret, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, parseAutoSyncInterval, planSelfUpdate, readAutoSyncSchedule, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, reimportWeight, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, updateAutoSyncSchedule, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
     .description('Athlete-scoped Catence data setup, extraction, and normalization.')
@@ -37,6 +38,41 @@ async function stdinSecret() {
         throw new Error('--value-stdin received an empty secret.');
     return value;
 }
+const mcpCommand = program.command('mcp').description('Manage Streamable HTTP MCP exposure: the bearer-token gate, its token, and endpoint URLs.');
+const mcpLocalEndpoint = () => `http://127.0.0.1:${process.env.CATENCE_HTTP_PORT ?? '8787'}`;
+mcpCommand.command('status')
+    .description('Report whether the bearer-token gate is enabled, the token, and the endpoint URLs.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('enable')
+    .description('Enable the bearer-token gate: generate the token file (mode 0600) if it does not exist.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    ensureBearerToken(tokenFile);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('disable')
+    .description('Disable the bearer-token gate by removing the token file. Remote access is refused again.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    disableBearerToken(tokenFile);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('token')
+    .description('Print only the bearer token for pasting into an MCP client credential flow.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    const token = readBearerToken(tokenFile);
+    if (token === null)
+        throw new Error(`MCP exposure is not enabled; run 'catence-data mcp enable' first.`);
+    process.stdout.write(`${token}\n`);
+});
 program.command('setup')
     .description('Create a home catalog and its first athlete store. Existing 0.1 stores must be re-synced.')
     .option('--athlete <id>', 'first athlete ID')
@@ -130,6 +166,27 @@ program.command('retry')
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await retryDataSync(paths, options.run), null, 2)}\n`);
 });
+const autoSyncCommand = program.command('auto-sync').description('Manage the automatic sync schedule for one athlete. The scheduler runs inside the Catence server (default: enabled, every 2 hours).');
+autoSyncCommand.command('status')
+    .description('Report the athlete’s automatic sync schedule: enabled flag, interval, and next run.')
+    .action(async () => {
+    const { athlete, paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await readAutoSyncSchedule(paths, athlete.id), null, 2)}\n`);
+});
+autoSyncCommand.command('enable')
+    .description('Turn automatic syncing on, optionally changing the interval (15m, 30m, 1h, 2h, 6h, 12h, 24h).')
+    .option('--interval <interval>', 'sync interval label or minutes', '2h')
+    .action(async (options) => {
+    const { athlete, paths } = await currentAthlete();
+    const intervalMinutes = parseAutoSyncInterval(options.interval);
+    process.stdout.write(`${JSON.stringify(await updateAutoSyncSchedule(paths, athlete.id, { enabled: true, intervalMinutes }), null, 2)}\n`);
+});
+autoSyncCommand.command('disable')
+    .description('Turn automatic syncing off. Manual sync keeps working.')
+    .action(async () => {
+    const { athlete, paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await updateAutoSyncSchedule(paths, athlete.id, { enabled: false }), null, 2)}\n`);
+});
 program.command('auth').description('Connect a source account using one athlete’s local credentials.')
     .command('strava')
     .option('--code <authorization-code>', 'OAuth authorization code returned by Strava')

package/dist/interfaces/http/cli-options.d.ts

@@ -6,7 +6,34 @@ export type ServeCliOptions = {
     authTokenFile?: string;
     help: boolean;
 };
-export declare const SERVE_USAGE = "Usage: catence serve [options]\n\nRun Catence as a local Streamable HTTP MCP server.\n\nOptions:\n  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  --host <host>              Listener host. Defaults to 127.0.0.1.\n  --port <port>              Listener port. Defaults to 8787.\n  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.\n  --auth-token-file <path>   Require 'Authorization: Bearer <token>' on every request except\n                             the health endpoints. Defaults to CATENCE_MCP_TOKEN_FILE.\n  -h, --help                 Show this help text.";
-/** Read and validate the bearer token from a file: trimmed, non-empty, or fail loudly. */
+export declare const SERVE_USAGE = "Usage: catence serve [options]\n\nRun Catence as a local Streamable HTTP MCP server.\n\nOptions:\n  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  --host <host>              Listener host. Defaults to 127.0.0.1.\n  --port <port>              Listener port. Defaults to 8787.\n  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.\n  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;\n                             generate/inspect it with 'catence-data mcp enable|token'.\n                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.\n  -h, --help                 Show this help text.";
+/** The canonical token location inside a catalog home. */
+export declare function defaultBearerTokenPath(catalogRoot: string): string;
+/** Read and validate a stored bearer token: trimmed, non-empty, or fail loudly. */
 export declare function loadBearerToken(filePath: string): string;
+/**
+ * The bearer token for the server: the stored one, or a freshly generated
+ * token written to the file (mode 0600) when it does not exist yet. Users
+ * never hand-craft tokens; they enable auth and read the result with
+ * `catence-data mcp-token`.
+ */
+export declare function ensureBearerToken(filePath: string): string;
+export declare function disableBearerToken(filePath: string): void;
+/** The bearer token when exposure is enabled, or null when no token file exists. */
+export declare function readBearerToken(filePath: string): string | null;
+/**
+ * The currently active bearer token for the HTTP gate, cached by the token
+ * file's mtime so enabling or disabling is picked up without a restart. A
+ * missing file disables the gate; an existing but unreadable or empty file
+ * fails closed (the gate rejects everything except health probes).
+ */
+export declare function activeBearerToken(filePath: string): string | null | 'invalid';
+export type McpExposureStatus = {
+    enabled: boolean;
+    tokenFile: string;
+    endpoint: string;
+    healthEndpoint: string;
+    token?: string;
+};
+export declare function mcpExposureStatus(filePath: string, endpointBase: string): McpExposureStatus;
 export declare function parseServeCliOptions(arguments_: readonly string[]): ServeCliOptions;

package/dist/interfaces/http/cli-options.js

@@ -1,4 +1,5 @@
-import { readFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 export const SERVE_USAGE = `Usage: catence serve [options]
 
 Run Catence as a local Streamable HTTP MCP server.
@@ -8,10 +9,15 @@ Options:
   --host <host>              Listener host. Defaults to 127.0.0.1.
   --port <port>              Listener port. Defaults to 8787.
   --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.
-  --auth-token-file <path>   Require 'Authorization: Bearer <token>' on every request except
-                             the health endpoints. Defaults to CATENCE_MCP_TOKEN_FILE.
+  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;
+                             generate/inspect it with 'catence-data mcp enable|token'.
+                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.
   -h, --help                 Show this help text.`;
-/** Read and validate the bearer token from a file: trimmed, non-empty, or fail loudly. */
+/** The canonical token location inside a catalog home. */
+export function defaultBearerTokenPath(catalogRoot) {
+    return `${catalogRoot.replace(/[/\\]+$/, '')}/mcp-token`;
+}
+/** Read and validate a stored bearer token: trimmed, non-empty, or fail loudly. */
 export function loadBearerToken(filePath) {
     let token;
     try {
@@ -24,6 +30,68 @@ export function loadBearerToken(filePath) {
         throw new Error(`The auth token file ${filePath} is empty.`);
     return token;
 }
+/**
+ * The bearer token for the server: the stored one, or a freshly generated
+ * token written to the file (mode 0600) when it does not exist yet. Users
+ * never hand-craft tokens; they enable auth and read the result with
+ * `catence-data mcp-token`.
+ */
+export function ensureBearerToken(filePath) {
+    if (existsSync(filePath))
+        return loadBearerToken(filePath);
+    const token = randomBytes(32).toString('hex');
+    writeFileSync(filePath, token, { mode: 0o600 });
+    return token;
+}
+export function disableBearerToken(filePath) {
+    if (existsSync(filePath))
+        rmSync(filePath);
+}
+/** The bearer token when exposure is enabled, or null when no token file exists. */
+export function readBearerToken(filePath) {
+    return existsSync(filePath) ? loadBearerToken(filePath) : null;
+}
+const tokenCache = new Map();
+/**
+ * The currently active bearer token for the HTTP gate, cached by the token
+ * file's mtime so enabling or disabling is picked up without a restart. A
+ * missing file disables the gate; an existing but unreadable or empty file
+ * fails closed (the gate rejects everything except health probes).
+ */
+export function activeBearerToken(filePath) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(filePath).mtimeMs;
+    }
+    catch {
+        tokenCache.set(filePath, { mtimeMs: 0, token: null });
+        return null;
+    }
+    const cached = tokenCache.get(filePath);
+    if (cached && cached.mtimeMs === mtimeMs) {
+        return cached.token === null ? 'invalid' : cached.token;
+    }
+    try {
+        const token = loadBearerToken(filePath);
+        tokenCache.set(filePath, { mtimeMs, token });
+        return token;
+    }
+    catch {
+        tokenCache.set(filePath, { mtimeMs, token: null });
+        return 'invalid';
+    }
+}
+export function mcpExposureStatus(filePath, endpointBase) {
+    const token = readBearerToken(filePath);
+    const base = endpointBase.replace(/\/+$/, '');
+    return {
+        enabled: token !== null,
+        tokenFile: filePath,
+        endpoint: `${base}/mcp`,
+        healthEndpoint: `${base}/health`,
+        ...(token !== null ? { token } : {}),
+    };
+}
 function requiredValue(arguments_, index, option) {
     const value = arguments_[index + 1];
     if (!value || value.startsWith('-'))

package/dist/interfaces/http/server.d.ts

@@ -7,12 +7,20 @@ export type CatenceHttpServerOptions = {
     paths?: CatencePaths;
     allowedOrigins?: readonly string[];
     /**
-     * When set, every request except the health endpoints and CORS preflights
-     * must present `Authorization: Bearer <token>`. The MCP server has no
-     * authentication of its own; this gates it (and the JSON APIs) for
-     * non-loopback exposure such as a Cloudflare Tunnel to an MCP client.
+     * Static bearer token for the gate (tests and embedded single-store callers).
+     * Mutually exclusive with bearerTokenFile.
      */
     bearerToken?: string;
+    /**
+     * Token file whose presence switches the gate on: every request except the
+     * health endpoints and CORS preflights must present
+     * `Authorization: Bearer <token>`. The file is re-read on mtime change, so
+     * `catence-data mcp enable|disable` (and the /api/v1/mcp-exposure route)
+     * take effect without a restart. The MCP server has no other
+     * authentication; this gates it (and the JSON APIs) for non-loopback
+     * exposure such as a Cloudflare Tunnel to an MCP client.
+     */
+    bearerTokenFile?: string;
     /** Internal compatibility hook for tests: override the detached sync spawner. */
     startSync?: typeof startDetachedSync;
     /** Internal compatibility hook for tests: passed into the default startDetachedSync. */

package/dist/interfaces/http/server.js

@@ -2,16 +2,20 @@ import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import path from 'node:path';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { addAthlete, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, catenceRuntimeHealth, DashboardSnapshotService, deleteAthleteSecret, describeAthleteSecrets, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, listAthleteFileRevisions, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, readAthleteFile, readAthleteFileRevision, resolveAthlete, resolveCatalogPaths, setAthleteSecret, startDetachedSync, syncProgress, updateAthleteFile, } from '../../runtime/index.js';
+import { addAthlete, AthleteFileConflictError, AthleteFileTooLargeError, AthleteFileValidationError, catenceRuntimeHealth, DashboardSnapshotService, deleteAthleteSecret, describeAthleteSecrets, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, listAthleteFileRevisions, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, parseAutoSyncInterval, readAutoSyncSchedule, readAthleteFile, readAthleteFileRevision, resolveAthlete, resolveCatalogPaths, setAthleteSecret, startDetachedSync, syncProgress, updateAthleteFile, updateAutoSyncSchedule, } from '../../runtime/index.js';
+import { activeBearerToken, ensureBearerToken, disableBearerToken, mcpExposureStatus } from './cli-options.js';
 import { createCatenceMcpServer } from '../mcp/server.js';
 import { generationStatus } from './generation-status.js';
 const MAX_REQUEST_BYTES = 1_000_000;
 /** Endpoints that stay open when bearer authentication is enabled: they carry
  * no personal data and must answer unauthenticated readiness probes. */
 const UNAUTHENTICATED_PATHS = new Set(['/health', '/api/v1/health']);
-function isAuthorized(request, bearerToken) {
-    if (!bearerToken)
+function isAuthorized(request, options) {
+    const bearerToken = options.bearerToken !== undefined ? options.bearerToken : options.bearerTokenFile !== undefined ? activeBearerToken(options.bearerTokenFile) : undefined;
+    if (bearerToken === undefined || bearerToken === null)
         return true;
+    if (bearerToken === 'invalid')
+        return false;
     const received = Buffer.from(request.headers.authorization ?? '');
     const expected = Buffer.from(`Bearer ${bearerToken}`);
     // timingSafeEqual throws on length mismatch, so compare sizes first.
@@ -99,6 +103,34 @@ async function dashboardPaths(catalogPaths, staticPaths, url) {
         return staticPaths;
     throw new Error('No Catence data store is configured.');
 }
+function parseSyncScheduleBody(body) {
+    if (body === undefined)
+        return {};
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new Error('Request body must be a JSON object.');
+    const raw = body;
+    for (const key of Object.keys(raw)) {
+        if (!['athleteId', 'enabled', 'intervalMinutes'].includes(key)) {
+            throw new Error(`Unknown auto-sync field: ${key}.`);
+        }
+    }
+    if (raw.athleteId !== undefined && typeof raw.athleteId !== 'string')
+        throw new Error('athleteId must be a string.');
+    if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean')
+        throw new Error('enabled must be a boolean.');
+    if (raw.intervalMinutes !== undefined) {
+        if (typeof raw.intervalMinutes === 'string') {
+            raw.intervalMinutes = parseAutoSyncInterval(raw.intervalMinutes);
+        }
+        else if (typeof raw.intervalMinutes !== 'number') {
+            throw new Error('intervalMinutes must be a number or a label like 15m, 2h, 24h.');
+        }
+    }
+    if (raw.enabled === undefined && raw.intervalMinutes === undefined) {
+        throw new Error('Provide enabled, intervalMinutes, or both.');
+    }
+    return raw;
+}
 function parseSyncBody(body) {
     if (body === undefined)
         return {};
@@ -325,7 +357,7 @@ export function createCatenceHttpServer(options = {}) {
                 response.writeHead(204).end();
                 return;
             }
-            if (!UNAUTHENTICATED_PATHS.has(pathname) && !isAuthorized(request, options.bearerToken)) {
+            if (!UNAUTHENTICATED_PATHS.has(pathname) && !isAuthorized(request, options)) {
                 // No WWW-Authenticate on purpose: MCP connector auto-detection treats a
                 // plain 401 as a bearer gate rather than an OAuth server.
                 json(response, 401, { error: { code: 'unauthorized', message: 'A valid Authorization: Bearer token is required.' } });
@@ -544,6 +576,34 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/sync/schedule' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url);
+                    const athleteId = catalogPaths ? (url.searchParams.get('athleteId') ?? '') : 'local';
+                    json(response, 200, await readAutoSyncSchedule(paths, athleteId));
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'schedule_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/sync/schedule' && request.method === 'PUT') {
+                try {
+                    const body = parseSyncScheduleBody(await readJsonBody(request));
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await resolveSyncPaths(catalogPaths, staticPaths, { athleteId: body.athleteId });
+                    const athleteId = catalogPaths ? (body.athleteId ?? '') : 'local';
+                    json(response, 200, await updateAutoSyncSchedule(paths, athleteId, {
+                        enabled: body.enabled,
+                        ...(body.intervalMinutes === undefined ? {} : { intervalMinutes: parseAutoSyncInterval(String(body.intervalMinutes)) }),
+                    }));
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'schedule_update_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
             if (pathname === '/api/v1/models/discover' && request.method === 'POST') {
                 // Refresh the OpenCode Go profiles without starting a data sync. The
                 // Console's Models page calls this behind its authenticated proxy.
@@ -599,6 +659,35 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/mcp-exposure' && request.method === 'GET') {
+                if (!options.bearerTokenFile) {
+                    json(response, 400, { error: { code: 'exposure_not_configured', message: 'This server was started without a bearer-token file; restart it with --auth-token-file to manage MCP exposure.' } });
+                    return;
+                }
+                json(response, 200, mcpExposureStatus(options.bearerTokenFile, `http://${request.headers.host ?? '127.0.0.1:8787'}`));
+                return;
+            }
+            if (pathname === '/api/v1/mcp-exposure' && request.method === 'POST') {
+                if (!options.bearerTokenFile) {
+                    json(response, 400, { error: { code: 'exposure_not_configured', message: 'This server was started without a bearer-token file; restart it with --auth-token-file to manage MCP exposure.' } });
+                    return;
+                }
+                try {
+                    const body = await readJsonBody(request);
+                    if (typeof body !== 'object' || body === null || Array.isArray(body) || !('enabled' in body) || typeof body.enabled !== 'boolean') {
+                        throw new Error('Request body must be a JSON object with a boolean "enabled" field.');
+                    }
+                    if (body.enabled)
+                        ensureBearerToken(options.bearerTokenFile);
+                    else
+                        disableBearerToken(options.bearerTokenFile);
+                    json(response, 200, mcpExposureStatus(options.bearerTokenFile, `http://${request.headers.host ?? '127.0.0.1:8787'}`));
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'exposure_update_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
             if (pathname === '/mcp') {
                 await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths());
                 return;

package/dist/interfaces/mcp/main.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { existsSync } from 'node:fs';
-import { addAthlete, athleteStorePaths, CatenceDatabase, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths } from '../../runtime/index.js';
-import { loadBearerToken, parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
+import { addAthlete, athleteStorePaths, CatenceDatabase, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths, startAutoSyncScheduler } from '../../runtime/index.js';
+import { defaultBearerTokenPath, parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
 import { createCatenceHttpServer } from '../http/server.js';
 import { MCP_USAGE, parseMcpCliOptions } from './cli-options.js';
 import { createCatenceMcpServer } from './server.js';
@@ -46,11 +46,13 @@ async function run() {
             return;
         }
         await migrateCatalogStores(options.home);
-        const bearerToken = options.authTokenFile ? loadBearerToken(options.authTokenFile) : undefined;
+        const catalogPaths = resolveCatalogPaths(options.home);
         const httpServer = createCatenceHttpServer({
-            catalogPaths: resolveCatalogPaths(options.home),
+            catalogPaths,
             allowedOrigins: options.allowedOrigins,
-            bearerToken,
+            // The token file's presence switches authentication on; enable it with
+            // `catence-data mcp enable` (or the Console Settings / exposure API).
+            bearerTokenFile: options.authTokenFile ?? defaultBearerTokenPath(catalogPaths.root),
         });
         await new Promise((resolve, reject) => {
             httpServer.once('error', reject);
@@ -60,9 +62,15 @@ async function run() {
             });
         });
         console.error(`Catence Streamable HTTP server is listening at http://${options.host}:${options.port}/mcp`);
-        if (bearerToken)
-            console.error('Bearer-token authentication is enabled; health endpoints stay open for readiness probes.');
+        console.error(`Bearer-token authentication is armed at ${options.authTokenFile ?? defaultBearerTokenPath(catalogPaths.root)}; enable it with 'catence-data mcp enable'. Health endpoints stay open for readiness probes.`);
+        // Auto-sync runs while the server is up: each athlete's autosync.json
+        // (default: enabled, every 2 hours) triggers a detached sync. The
+        // detached child and the single-writer DuckDB lock stay the only
+        // executors, so concurrent ticks are no-ops by design.
+        const scheduler = startAutoSyncScheduler({ catalogPaths });
+        console.error('Auto-sync scheduler started (default: enabled, every 2 hours per athlete; configure with auto-sync enable --interval or Console Settings).');
         const close = () => {
+            scheduler.stop();
             httpServer.close(() => process.exit(0));
         };
         process.once('SIGINT', close);

package/dist/interfaces/mcp/server.js

@@ -312,7 +312,17 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
     }, tool('start_detached_sync', async (input) => {
         const paths = activePaths();
         const athleteId = activeAthlete()?.id ?? 'local';
-        const handle = await startSync({ paths, athleteId, provider: input.provider, from: input.from, refresh: input.refresh });
+        const handle = await startSync({
+            paths,
+            athleteId,
+            provider: input.provider,
+            from: input.from,
+            refresh: input.refresh,
+            // The child resolves the athlete within the catalog, not within the
+            // athlete store this tool resolved for locks and logs: passing the
+            // store itself trips the legacy-store guard in catalog deployments.
+            ...(catalogPaths ? { cliHome: catalogPaths.root } : {}),
+        });
         return {
             data: { ...handle, progressTool: 'catence_sync_progress' },
             provenance: { operation: 'detached_sync_spawn' },

package/dist/runtime/index.d.ts

@@ -35,6 +35,8 @@ export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaA
 export type { ProviderChoice } from '../elt/application/management.js';
 export { DETACHED_SYNC_PROVIDERS, DetachedSyncBusyError, startDetachedSync, } from '../elt/application/detached-sync.js';
 export type { DetachedSyncHandle, DetachedSyncProvider, DetachedSyncRequest, DetachedSyncSpawner } from '../elt/application/detached-sync.js';
+export { AUTO_SYNC_INTERVAL_MINUTES, DEFAULT_AUTO_SYNC_INTERVAL_MINUTES, parseAutoSyncInterval, readAutoSyncSchedule, startAutoSyncScheduler, updateAutoSyncSchedule, } from '../elt/application/autosync.js';
+export type { AutoSyncConfig, AutoSyncIntervalMinutes, AutoSyncSchedule, AutoSyncScheduler, AutoSyncSchedulerOptions } from '../elt/application/autosync.js';
 export { buildOpenCodeGoConsoleProfiles, classifyOpenCodeGoModel, fetchOpenCodeGoModelIds, mergeOpenCodeGoConsoleProfiles, OPENCODE_GO_API_BASE_ENV, OPENCODE_GO_API_KEY_ENV, OPENCODE_GO_DEFAULT_BASE_URL, OPENCODE_GO_MESSAGES_API_BASE_ENV, } from '../core/runtime/opencode-go.js';
 export type { OpenCodeGoConsoleProfiles, OpenCodeGoMergeResult, OpenCodeGoRoute } from '../core/runtime/opencode-go.js';
 export type { InterruptedRuns, SyncProgressSnapshot, SyncProgressState } from '../contracts/progress.js';

package/dist/runtime/index.js

@@ -19,6 +19,7 @@ export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
 export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, importStagedFile, linkActivity, rebuildRetrievalIndex, reimportNutrition, reimportWeight, resolveExtractionErrors, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 export { DETACHED_SYNC_PROVIDERS, DetachedSyncBusyError, startDetachedSync, } from '../elt/application/detached-sync.js';
+export { AUTO_SYNC_INTERVAL_MINUTES, DEFAULT_AUTO_SYNC_INTERVAL_MINUTES, parseAutoSyncInterval, readAutoSyncSchedule, startAutoSyncScheduler, updateAutoSyncSchedule, } from '../elt/application/autosync.js';
 export { buildOpenCodeGoConsoleProfiles, classifyOpenCodeGoModel, fetchOpenCodeGoModelIds, mergeOpenCodeGoConsoleProfiles, OPENCODE_GO_API_BASE_ENV, OPENCODE_GO_API_KEY_ENV, OPENCODE_GO_DEFAULT_BASE_URL, OPENCODE_GO_MESSAGES_API_BASE_ENV, } from '../core/runtime/opencode-go.js';
 export { CatenceDatabase, openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';

package/docs/configuration.md

@@ -247,7 +247,7 @@ profiles and preserve existing ones, limits, and `defaultProfile` unless
 | --- | --- |
 | `CATENCE_HOME` | Catalog home (default `~/.catence`); equivalent to `--home` |
 | `CATENCE_HTTP_HOST` / `CATENCE_HTTP_PORT` | Defaults for `catence serve --host/--port` (host `127.0.0.1`, port `8787`) |
-| `CATENCE_MCP_TOKEN_FILE` | Default for `catence serve --auth-token-file`; when set, every endpoint except `/health` and `/api/v1/health` requires `Authorization: Bearer <token>` |
+| `CATENCE_MCP_TOKEN_FILE` | Overrides the bearer-token file path for `catence serve` (default `<catalog-home>/mcp-token`); the file's presence switches the gate on, managed with `catence-data mcp enable/disable` or the Console Settings |
 
 Provider credentials are stored per athlete, either with `catence-data secret
 set` (see [`local-mcp.md`](deployment/local-mcp.md#3-store-provider-credentials-stdin-only-never-shell-history))

package/docs/deployment/docker.md

@@ -509,30 +509,43 @@ claude mcp add --transport http catence -- http://<tailscale-ip>:8787/mcp
 ### Bearer-token authentication for remote MCP clients
 
 To serve the MCP endpoint to a remote MCP client (for example a Mistral Work
-custom connector) over a Cloudflare Tunnel, enable bearer-token
-authentication instead of leaving the runtime unauthenticated. Set
-`CATENCE_MCP_TOKEN_FILE` in `catence-deploy/.env` to a host file holding one
-token (`openssl rand -hex 32`); the deploy script bind-mounts that file
-read-only into the container at the same path:
+custom connector) over a Cloudflare Tunnel, switch on the native
+bearer-token gate. The deploy scaffold arms it at `/data/mcp-token` (inside
+the data volume, so it survives rebuilds); the file's presence is the switch
+and Catence generates the token itself:
 
 ```sh
-# once, when the stack is already deployed:
-printf %s "$(openssl rand -hex 32)" > /srv/catence-mcp-token   # mode 0600, outside the data volume
-echo "CATENCE_MCP_TOKEN_FILE=/srv/catence-mcp-token" >> catence-deploy/.env
-./scripts/deploy-console.sh beta    # re-renders compose with the token mount
+# enable from the host (or use the Console Settings once logged in):
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp enable
+
+# print the token for the client's credential flow:
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp token
+
+# disable again:
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env \
+  exec console catence-data --home /data mcp disable
 ```
 
-With the token configured, every runtime endpoint except `/health` and
+With the gate enabled, every runtime endpoint except `/health` and
 `/api/v1/health` answers `401` without an exact `Authorization: Bearer
-<token>` header — including `/mcp` and the JSON APIs. The Console attaches
-the header automatically to its own runtime calls, and refuses to start when
-the configured file is unreadable or empty.
+<token>` header — including `/mcp` and the JSON APIs. Toggling takes effect
+without a restart; the Console attaches the header automatically to its own
+runtime calls.
 
 Keep `CATENCE_MCP_BIND=127.0.0.1` (the default): the tunnel client on the
 host forwards to the host-loopback mapping, so the port still never binds a
 LAN interface. Point the tunnel ingress for the MCP hostname at
 `http://127.0.0.1:8787` and complete the client's credential flow with the
-same token. Rotate by rewriting the file and restarting the stack.
+token from `mcp token`. Rotate with `mcp disable && mcp enable` and
+re-authenticate the client. The only additional setup the tunnel needs is
+the ingress rule for the MCP hostname.
+
+A custom host-side token file is still possible: set
+`CATENCE_MCP_TOKEN_FILE=<host path>` in `.env`. The file is then bind-mounted
+read-only at the same path, so it must already exist on the host — enabling
+from the Console cannot create it.
 
 ## Exposing the Console safely
 

package/docs/deployment/local-mcp.md

@@ -306,26 +306,40 @@ override the host and port when the flags are omitted.
 
 The server has no authentication of its own; when it must be reachable beyond
 loopback (for example through a Cloudflare Tunnel to an MCP client such as
-Mistral Work), require a bearer token with `--auth-token-file <path>`
-(environment equivalent: `CATENCE_MCP_TOKEN_FILE`):
+Mistral Work), switch on the bearer-token gate. The gate is armed at a token
+file — `<catalog-home>/mcp-token` by default, or the path given by
+`--auth-token-file` (environment equivalent: `CATENCE_MCP_TOKEN_FILE`) — and
+the **file's presence is the switch**: create it to enable, remove it to
+disable, no restart needed.
+
+Catence generates the token itself; never hand-craft one:
 
 ```sh
-catence serve --host 127.0.0.1 --port 8787 --auth-token-file /path/to/token
+catence-data mcp status    # enabled, token file, endpoint URLs
+catence-data mcp enable    # generate the token file (mode 0600) if missing
+catence-data mcp token      # print the token for the client credential flow
+catence-data mcp disable   # remove the file; remote access is refused again
 ```
 
-- The file holds one token (whitespace-trimmed); generate one with
-  `openssl rand -hex 32`. An unreadable or empty file aborts startup.
 - Every endpoint except `/health` and `/api/v1/health` (kept open for readiness
-  probes) then answers `401` without an exact
-  `Authorization: Bearer <token>` header. The `401` deliberately carries no
+  probes) answers `401` without an exact `Authorization: Bearer <token>`
+  header while the gate is on. The `401` deliberately carries no
   `WWW-Authenticate`, so MCP clients with auth auto-detection (Mistral Work)
   classify the server as bearer-auth rather than OAuth.
 - CORS preflights (`OPTIONS`) pass through without a token.
-- Rotation: rewrite the file and restart the server. Keep the token out of
+- An existing but unreadable or empty token file fails closed: the gate
+  rejects everything except the health probes until the file is fixed or
+  removed.
+- `GET /api/v1/mcp-exposure` reports the same status the Console Settings page
+  shows (including the token); `POST /api/v1/mcp-exposure` with
+  `{"enabled": true|false}` toggles the gate. The Console exposes both to
+  admins only.
+- Rotation: `catence-data mcp disable && catence-data mcp enable` (or rewrite
+  the file), then re-authenticate the MCP client. Keep the token out of
   `.env`, `config.json`, shell history, and repositories.
-- The Console attaches the same header automatically to its runtime calls when
-  `CATENCE_MCP_TOKEN_FILE` is set, and refuses to start if the file is
-  unreadable.
+- The Console attaches the same header automatically to its runtime calls and
+  reads the token file lazily, so enabling the gate from the Console or CLI
+  needs no Console restart either.
 
 - `GET /api/v1/athletes` returns IDs and labels only.
 - `POST /api/v1/athletes` creates a catalog athlete from

package/package.json

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

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

@@ -75,12 +75,32 @@ def main() -> None:
     email = os.environ.get("GARMIN_EMAIL")
     if not email:
         raise SystemExit("GARMIN_EMAIL is required.")
-    password = os.environ.get("GARMIN_PASSWORD") or getpass.getpass("Garmin password: ")
-    writer = StagingWriter(args.data_dir, args.output)
-    writer.manifest(args.run_id, args.from_date.isoformat())
     token_store = args.data_dir / "auth" / "garmin_tokens.json"
     token_store.parent.mkdir(parents=True, exist_ok=True)
-    client = Garmin(email, password, prompt_mfa=lambda: input("Garmin MFA code: "))
+    if not sys.stdin.isatty():
+        # Unattended auto-sync must never hang on a hidden prompt: fail fast
+        # so the run records a visible error instead.
+        password = os.environ.get("GARMIN_PASSWORD")
+        if not password and not token_store.exists():
+            raise SystemExit(
+                "Garmin login is required (no stored token, no GARMIN_PASSWORD, "
+                "and stdin is not interactive). Run an interactive sync once to "
+                "store the session token, or set GARMIN_PASSWORD."
+            )
+    else:
+        password = os.environ.get("GARMIN_PASSWORD") or getpass.getpass("Garmin password: ")
+
+    def prompt_mfa() -> str:
+        if not sys.stdin.isatty():
+            raise SystemExit(
+                "Garmin MFA is required but stdin is not interactive; the "
+                "session token expired. Run an interactive sync once to renew it."
+            )
+        return input("Garmin MFA code: ")
+
+    writer = StagingWriter(args.data_dir, args.output)
+    writer.manifest(args.run_id, args.from_date.isoformat())
+    client = Garmin(email, password, prompt_mfa=prompt_mfa)
     client.login(str(token_store))
     reporter = ProgressReporter(args.run_id)
     reporter.set_stage("login")