catence 0.2.0-beta.11 → 0.2.0-beta.12

package/dist/contracts/progress.d.ts

@@ -1,5 +1,5 @@
 export declare const STALE_RUN_TIMEOUT_MS: number;
-export declare const SYNC_STAGES: readonly ["starting", "login", "singletons", "daily", "range", "ftp_history", "max_metrics", "hrv_history", "scores", "activities", "collections", "importing", "completed", "interrupted", "failed", "timed_out"];
+export declare const SYNC_STAGES: readonly ["starting", "login", "singletons", "daily", "range", "ftp_history", "max_metrics", "hrv_history", "scores", "activities", "collections", "intervals", "importing", "completed", "interrupted", "failed", "timed_out"];
 export type SyncStage = (typeof SYNC_STAGES)[number];
 export interface SyncProgressState {
     runId: string;

package/dist/contracts/progress.js

@@ -11,6 +11,7 @@ export const SYNC_STAGES = [
     'scores',
     'activities',
     'collections',
+    'intervals',
     'importing',
     'completed',
     'interrupted',

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

package/dist/elt/application/management.js

@@ -15,7 +15,7 @@ import { IntervalsExtractor } from '../ingestion/providers/intervals.js';
 import { completeStravaAuthorization, disconnectStrava, getStravaAuthorizationUrl, syncStravaGear } from '../ingestion/providers/strava/service.js';
 import { setManualActivityLink, unlinkActivitySource } from '../normalization/activities/linking.js';
 import { CatenceDatabase, openReadOnlyRepository, ReadOnlyDatabaseError } from '../storage/database.js';
-import { mergeProgress, readRunningProgress, removeProgressSidecar, writeProgressSidecar } from '../storage/progress-sidecar.js';
+import { mergeProgress, ProgressPump, readRunningProgress, removeProgressSidecar } from '../storage/progress-sidecar.js';
 import { withDataWriteLock } from '../storage/write-lock.js';
 function packageRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
@@ -33,7 +33,7 @@ function baseProgress(runId, provider, stage) {
  * Progress NDJSON lines (kind 'progress') are normalized and persisted as
  * throttled heartbeats; other output is forwarded to the sync logger.
  */
-function runGarminWorker(runId, arguments_, environment, database, paths, log, onInterruptReady) {
+function runGarminWorker(runId, arguments_, environment, pump, log, onInterruptReady) {
     return new Promise((resolve) => {
         const child = spawn('uv', arguments_, { ...environment, stdio: ['ignore', 'pipe', 'pipe'] });
         let killTimer;
@@ -48,24 +48,6 @@ function runGarminWorker(runId, arguments_, environment, database, paths, log, o
             }, 10_000);
             killTimer.unref();
         });
-        let lastProgress = null;
-        let lastHeartbeatAt = 0;
-        const heartbeat = (state) => {
-            const now = Date.now();
-            if (now - lastHeartbeatAt < 2_000)
-                return;
-            lastHeartbeatAt = now;
-            void database.heartbeatRun(runId, state).catch((error) => {
-                log.debug('Progress heartbeat failed', { runId, error: error instanceof Error ? error.message : String(error) });
-            });
-            void writeProgressSidecar(paths, runId, state).catch((error) => {
-                log.debug('Progress sidecar write failed', { runId, error: error instanceof Error ? error.message : String(error) });
-            });
-        };
-        const fallback = setInterval(() => {
-            heartbeat(lastProgress ?? baseProgress(runId, 'garmin', 'starting'));
-        }, 30_000);
-        fallback.unref();
         const buffer = (stream, sink) => {
             let pending = '';
             stream.on('data', (chunk) => {
@@ -95,29 +77,24 @@ function runGarminWorker(runId, arguments_, environment, database, paths, log, o
             }
             if (typeof parsed === 'object' && parsed !== null && parsed.kind === 'progress') {
                 const state = normalizeProgress(parsed);
-                if (state) {
-                    lastProgress = state;
-                    heartbeat(state);
-                }
+                if (state)
+                    pump.publish(state);
                 return;
             }
             log.info(`[garmin] ${line}`);
         });
         buffer(child.stderr, (line) => log.error(`[garmin] ${line}`));
         child.on('error', (error) => {
-            clearInterval(fallback);
             if (killTimer)
                 clearTimeout(killTimer);
             resolve({ code: 1, signal: null });
             log.error('Garmin staging worker could not be started', { runId, error: error.message });
         });
         child.on('close', (code, signal) => {
-            clearInterval(fallback);
             if (killTimer)
                 clearTimeout(killTimer);
-            if (code === 0 && lastProgress) {
-                void writeProgressSidecar(paths, runId, { ...lastProgress, stage: 'importing' }).catch(() => undefined);
-            }
+            if (code === 0)
+                pump.setStageImporting();
             resolve({ code, signal });
         });
     });
@@ -188,11 +165,14 @@ async function syncProvider(database, paths, provider, options, log) {
     });
     let extractionStarted = false;
     const guard = { interrupted: false };
+    const pump = new ProgressPump(runId, provider, { database, paths, log });
+    pump.start();
     try {
         if (provider === 'intervals') {
             const environment = await athleteProviderEnvironment(paths);
             const config = requireIntervalsConfig(environment);
             extractionStarted = true;
+            pump.setStage('intervals');
             await runWithInterruptGuard(runId, database, () => undefined, guard, async () => {
                 await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId, log).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
             });
@@ -222,7 +202,7 @@ async function syncProvider(database, paths, provider, options, log) {
                 const outcome = await runGarminWorker(runId, arguments_, {
                     cwd: packageRoot(),
                     env: { ...(await athleteProviderEnvironment(paths)), UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
-                }, database, paths, log, (kill) => { interruptChild = kill; });
+                }, pump, log, (kill) => { interruptChild = kill; });
                 if (!guard.interrupted && outcome.code !== 0) {
                     throw new Error(`Garmin staging worker exited with code ${outcome.code}${outcome.signal ? ` (${outcome.signal})` : ''}.`);
                 }
@@ -243,12 +223,14 @@ async function syncProvider(database, paths, provider, options, log) {
         }
     }
     finally {
+        pump.stop();
         if (guard.interrupted) {
             await database.markRunInterrupted(runId);
             log.warn('Sync run interrupted', { runId, provider });
         }
         else {
             await database.finishRun(runId);
+            pump.publishFinal(baseProgress(runId, provider, 'completed'));
         }
         await removeProgressSidecar(paths, runId).catch(() => undefined);
         const [run] = await database.rows('SELECT status, error_count FROM sync_runs WHERE run_id = $runId', { runId });

package/dist/elt/storage/progress-sidecar.d.ts

@@ -1,7 +1,11 @@
-import { type SyncProgressSnapshot, type SyncProgressState } from '../../contracts/progress.js';
+import { type SyncProgressSnapshot, type SyncProgressState, type SyncStage } from '../../contracts/progress.js';
 import type { CatencePaths } from '../../contracts/runtime.js';
+import type { SyncLogger } from '../../core/logging.js';
+import type { CatenceDatabase } from './database.js';
 export declare const PROGRESS_SIDECAR_SUFFIX = ".progress.json";
 export declare const PROGRESS_SIDECAR_STALE_MS: number;
+export declare const PROGRESS_KEEPALIVE_MS: number;
+export declare const PROGRESS_PUBLISH_THROTTLE_MS: number;
 export declare function progressSidecarPath(paths: CatencePaths, runId: string): string;
 /**
  * Persist one progress heartbeat as a sidecar file next to the Garmin staging
@@ -24,3 +28,34 @@ export declare function readRunningProgress(paths: CatencePaths, staleAfterMs?:
  * both sources and sorted by heartbeat recency.
  */
 export declare function mergeProgress(dbRunning: SyncProgressState[], dbRecent: SyncProgressState[], sidecars: SyncProgressState[]): SyncProgressSnapshot;
+export interface ProgressPumpOptions {
+    database: CatenceDatabase;
+    paths: CatencePaths;
+    log: SyncLogger;
+}
+/**
+ * Drives progress heartbeats for the whole lifetime of a sync run - including
+ * phases that emit no worker output (the Intervals extractor and the Garmin
+ * JSONL import). `publish` throttles writes to the database and sidecar; a
+ * 30-second keep-alive interval refreshes the last known state so a run never
+ * looks stale while it is still active, even during the lock-holding import.
+ */
+export declare class ProgressPump {
+    private readonly runId;
+    private readonly provider;
+    private readonly options;
+    private lastProgress;
+    private lastHeartbeatAt;
+    private interval;
+    private stageOverride;
+    constructor(runId: string, provider: string, options: ProgressPumpOptions);
+    start(): void;
+    publish(state: SyncProgressState): void;
+    /** Force subsequent keep-alive heartbeats to report the given stage. */
+    setStage(stage: SyncStage): void;
+    /** Transition the run to the JSONL import stage; keep-alives persist it. */
+    setStageImporting(): void;
+    /** Write a terminal heartbeat immediately, bypassing the publish throttle. */
+    publishFinal(state: SyncProgressState): void;
+    stop(): void;
+}

package/dist/elt/storage/progress-sidecar.js

@@ -1,9 +1,11 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { normalizeProgress } from '../../contracts/progress.js';
+import { normalizeProgress, } from '../../contracts/progress.js';
 export const PROGRESS_SIDECAR_SUFFIX = '.progress.json';
 export const PROGRESS_SIDECAR_STALE_MS = 5 * 60 * 1000;
+export const PROGRESS_KEEPALIVE_MS = 30 * 1000;
+export const PROGRESS_PUBLISH_THROTTLE_MS = 2 * 1000;
 const TERMINAL_STAGES = new Set(['completed', 'failed', 'interrupted', 'timed_out']);
 export function progressSidecarPath(paths, runId) {
     return path.join(paths.staging, 'garmin', `${runId}${PROGRESS_SIDECAR_SUFFIX}`);
@@ -16,7 +18,7 @@ export function progressSidecarPath(paths, runId) {
 export async function writeProgressSidecar(paths, runId, state) {
     const target = progressSidecarPath(paths, runId);
     await mkdir(path.dirname(target), { recursive: true });
-    const temporary = `${target}.tmp`;
+    const temporary = `${target}.${Date.now()}.${Math.random().toString(36).slice(2, 10)}.tmp`;
     await writeFile(temporary, JSON.stringify(state));
     await rename(temporary, target);
 }
@@ -84,4 +86,95 @@ export function mergeProgress(dbRunning, dbRecent, sidecars) {
             .slice(0, 10),
     };
 }
+function baselineState(runId, provider, stage) {
+    return {
+        runId,
+        provider,
+        stage,
+        currentStep: null,
+        completedUnits: 0,
+        totalUnits: null,
+        percentComplete: 0,
+        elapsedSeconds: 0,
+        estimatedRemainingSeconds: null,
+        heartbeatAt: new Date().toISOString(),
+    };
+}
+/**
+ * Drives progress heartbeats for the whole lifetime of a sync run - including
+ * phases that emit no worker output (the Intervals extractor and the Garmin
+ * JSONL import). `publish` throttles writes to the database and sidecar; a
+ * 30-second keep-alive interval refreshes the last known state so a run never
+ * looks stale while it is still active, even during the lock-holding import.
+ */
+export class ProgressPump {
+    runId;
+    provider;
+    options;
+    lastProgress = null;
+    lastHeartbeatAt = 0;
+    interval = null;
+    stageOverride = null;
+    constructor(runId, provider, options) {
+        this.runId = runId;
+        this.provider = provider;
+        this.options = options;
+    }
+    start() {
+        if (this.interval)
+            return;
+        this.interval = setInterval(() => {
+            this.publish(this.lastProgress
+                ? { ...this.lastProgress, heartbeatAt: new Date().toISOString() }
+                : baselineState(this.runId, this.provider, this.stageOverride ?? 'starting'));
+        }, PROGRESS_KEEPALIVE_MS);
+        this.interval.unref();
+    }
+    publish(state) {
+        const now = Date.now();
+        if (this.lastHeartbeatAt !== 0 && now - this.lastHeartbeatAt < PROGRESS_PUBLISH_THROTTLE_MS) {
+            this.lastProgress = state;
+            return;
+        }
+        this.lastHeartbeatAt = now;
+        this.lastProgress = state;
+        const { database, paths, log } = this.options;
+        void database.heartbeatRun(this.runId, state).catch((error) => {
+            log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+        });
+        void writeProgressSidecar(paths, this.runId, state).catch((error) => {
+            log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+        });
+    }
+    /** Force subsequent keep-alive heartbeats to report the given stage. */
+    setStage(stage) {
+        this.stageOverride = stage;
+        if (this.lastProgress) {
+            this.lastProgress = { ...this.lastProgress, stage };
+            this.publish(this.lastProgress);
+        }
+    }
+    /** Transition the run to the JSONL import stage; keep-alives persist it. */
+    setStageImporting() {
+        this.setStage('importing');
+    }
+    /** Write a terminal heartbeat immediately, bypassing the publish throttle. */
+    publishFinal(state) {
+        this.lastHeartbeatAt = Date.now();
+        this.lastProgress = state;
+        const { database, paths, log } = this.options;
+        void database.heartbeatRun(this.runId, state).catch((error) => {
+            log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+        });
+        void writeProgressSidecar(paths, this.runId, state).catch((error) => {
+            log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+        });
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+}
 //# sourceMappingURL=progress-sidecar.js.map

package/docs/deployment/local-mcp.md

@@ -209,6 +209,10 @@ for live runs and only touch the `sync_run_progress` table for recent-run
 history once the lock is free — so they keep working while a backfill holds the
 lock, and never crash with a lock error.
 
+Progress also stays live through the entire run, not just worker extraction: a
+30-second keep-alive covers the JSONL import phase (which emits no worker
+output) and the `intervals` phase of a provider-all sync or backfill.
+
 Other read-only tools (`status`, `query_read_only_data`, and friends) still
 need the database and therefore return a clean `data_sync_in_progress` error
 while a sync run is active. That is expected behavior: the store is locked

package/package.json

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