catence 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/interfaces/cli/commands.js

@@ -2,7 +2,7 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { addAthlete, athleteStorePaths, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, initializeCatalog, linkActivity, loadCatalog, rebuildRetrievalIndex, resolveAthlete, resolveCatalogPaths, retryDataSync, setAthleteSecret, syncData, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
     .description('Athlete-scoped Catence data setup, extraction, and normalization.')
@@ -158,9 +158,124 @@ program.command('status').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await dataStatus(paths), null, 2)}\n`);
 });
+function renderProgress(snapshot) {
+    const lines = snapshot.running.map((run) => {
+        const pct = run.percentComplete.toFixed(1).padStart(5);
+        const units = run.totalUnits !== null ? `${run.completedUnits}/${run.totalUnits}` : String(run.completedUnits);
+        const eta = run.estimatedRemainingSeconds !== null ? `${Math.round(run.estimatedRemainingSeconds)}s` : '?';
+        const step = run.currentStep ?? '';
+        return `${pct}%  ${run.stage.padEnd(12)} ${units.padEnd(11)} ${eta.padEnd(6)} ${step}`;
+    });
+    return lines.length === 0 ? 'no active sync runs' : lines.join('\n');
+}
+program.command('progress')
+    .description('Show live progress for active sync runs.')
+    .option('--watch', 'refresh every few seconds until no sync runs are active')
+    .action(async (options) => {
+    const { paths } = await currentAthlete();
+    if (!options.watch) {
+        process.stdout.write(`${JSON.stringify(await syncProgress(paths), null, 2)}\n`);
+        return;
+    }
+    while (true) {
+        const snapshot = await syncProgress(paths);
+        if (output.isTTY) {
+            output.write(`\x1b[2J\x1b[H${renderProgress(snapshot)}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+        }
+        if (snapshot.running.length === 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+});
+program.command('update')
+    .description('Check for and apply the newest Catence release on the tracked channel (runtime and Console).')
+    .option('--check', 'report available releases without changing anything')
+    .option('--channel <stable|beta>', 'release channel to track; defaults to the installed runtime channel')
+    .option('--runtime', 'only check or update the Catence runtime package')
+    .option('--console', 'only check or update the Catence Console package')
+    .action(async (options) => {
+    if (options.channel !== undefined && options.channel !== 'stable' && options.channel !== 'beta') {
+        throw new Error('--channel must be stable or beta.');
+    }
+    const channel = options.channel ?? channelForVersion(CATENCE_RUNTIME_VERSION);
+    const runtimeOnly = options.runtime ?? false;
+    const consoleOnly = options.console ?? false;
+    const updateRuntime = runtimeOnly || !consoleOnly;
+    const updateConsole = consoleOnly || !runtimeOnly;
+    const [npmDistTags, pypiReleases, consoleInstalled] = await Promise.all([
+        fetchNpmDistTags('catence'),
+        fetchPypiReleases('catence-console'),
+        readInstalledConsoleVersion(),
+    ]);
+    const plan = planSelfUpdate({ runtimeVersion: CATENCE_RUNTIME_VERSION, channel, npmDistTags, pypiReleases, consoleInstalled });
+    const report = { channel, runtime: plan.runtime, console: plan.console };
+    if (options.check) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        process.exit(plan.ok ? 0 : 1);
+    }
+    const applied = [];
+    if (plan.runtime.updateAvailable && updateRuntime) {
+        const runtimeTarget = plan.runtime.target;
+        if (runtimeTarget === undefined)
+            throw new Error('No runtime update target is available.');
+        const npmPrefix = await npmGlobalPrefix();
+        if (isGlobalNpmInstall(import.meta.url, npmPrefix)) {
+            const exitCode = await runSelfUpdateCommand('npm', ['install', '--global', `catence@${runtimeTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`npm failed to install catence@${runtimeTarget} (exit ${exitCode}).`);
+            applied.push(`runtime: catence@${runtimeTarget}`);
+        }
+        else {
+            process.stderr.write(`Runtime is not a global npm install; run: npm install --global catence@${runtimeTarget}\n`);
+        }
+    }
+    if (plan.console.updateAvailable && updateConsole) {
+        const consoleTarget = plan.console.target;
+        if (consoleTarget === undefined)
+            throw new Error('No Console update target is available.');
+        if (await hasCommand('uv')) {
+            const exitCode = await runSelfUpdateCommand('uv', ['tool', 'install', '--upgrade', `catence-console==${consoleTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`uv failed to install catence-console==${consoleTarget} (exit ${exitCode}).`);
+            applied.push(`console: catence-console==${consoleTarget}`);
+        }
+        else {
+            process.stderr.write(`uv is not installed; run: pip install --upgrade 'catence-console==${consoleTarget}'\n`);
+        }
+    }
+    process.stdout.write(`${JSON.stringify({ ...report, applied }, null, 2)}\n`);
+});
 program.command('build-retrieval-index').description('Build derived local retrieval context for one athlete.').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await rebuildRetrievalIndex(paths), null, 2)}\n`);
 });
+program.command('reimport-nutrition').description('Re-run normalization over captured nutrition entities without contacting providers.').action(async () => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await reimportNutrition(paths), null, 2)}\n`);
+});
+program
+    .command('import')
+    .description('Import a staged JSONL file (for example a swim-length backfill) into one athlete’s data store.')
+    .requiredOption('--provider <provider>', 'garmin, intervals, or strava')
+    .argument('<file>', 'path to the staged JSONL file')
+    .action(async (file, options) => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await importStagedFile(paths, options.provider, file), null, 2)}\n`);
+});
+program
+    .command('resolve-errors')
+    .description('Mark unresolved extraction errors as resolved (for example stale bootstrap failures from an environment that has since recovered).')
+    .option('--run <run-id>', 'resolve errors from a specific run only (repeatable)')
+    .option('--provider <provider>', 'resolve errors for garmin, intervals, or strava only')
+    .option('--before <timestamp>', 'resolve errors created before this ISO timestamp')
+    .option('--all', 'resolve every unresolved error')
+    .action(async (options) => {
+    const { paths } = await currentAthlete();
+    const runIds = Array.isArray(options.run) ? options.run : options.run ? [options.run] : undefined;
+    process.stdout.write(`${JSON.stringify(await resolveExtractionErrors(paths, { runIds, provider: options.provider, before: options.before, all: options.all }), null, 2)}\n`);
+});
 await program.parseAsync();
 //# sourceMappingURL=commands.js.map

package/dist/interfaces/http/generation-status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Read + classify the generation progress sidecar written by the Catence
+ * Console agent turn (see `catence_console/generation_sidecar.py`). Mirrors the
+ * detached-sync sidecar logic: a run is "running" until it reaches a terminal
+ * stage, and "stale" (i.e. likely stuck) when its heartbeat is older than the
+ * threshold. This powers the chat UI's "still thinking vs stalled" signal.
+ */
+export interface GenerationStatus {
+    threadId: string;
+    stage?: string;
+    running: boolean;
+    stale: boolean;
+    heartbeatAt?: string;
+    startedAt?: string;
+    updatedAt?: string;
+    toolCallCount: number;
+    lastTool?: string | null;
+}
+export declare function generationStatus(homeRoot: string, threadId: string): Promise<GenerationStatus>;

package/dist/interfaces/http/generation-status.js

@@ -0,0 +1,55 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+const TERMINAL_STAGES = new Set([
+    'completed',
+    'failed',
+    'interrupted',
+    'timed_out'
+]);
+const STALE_MS = 5 * 60 * 1000; // 5 minutes
+function emptyStatus(threadId) {
+    return {
+        threadId,
+        running: false,
+        stale: false,
+        toolCallCount: 0
+    };
+}
+export async function generationStatus(homeRoot, threadId) {
+    const safe = threadId.replace(/[^a-zA-Z0-9_-]/g, '');
+    if (!safe)
+        return emptyStatus(threadId);
+    const file = path.join(homeRoot, 'generation', `${safe}.generation.json`);
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        return emptyStatus(threadId);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return emptyStatus(threadId);
+    }
+    const base = {
+        threadId,
+        stage: typeof data.stage === 'string' ? data.stage : undefined,
+        heartbeatAt: typeof data.heartbeatAt === 'string' ? data.heartbeatAt : undefined,
+        startedAt: typeof data.startedAt === 'string' ? data.startedAt : undefined,
+        updatedAt: typeof data.updatedAt === 'string' ? data.updatedAt : undefined,
+        toolCallCount: typeof data.toolCallCount === 'number' ? data.toolCallCount : 0,
+        lastTool: data.lastTool === null || typeof data.lastTool === 'string'
+            ? data.lastTool
+            : undefined
+    };
+    if (base.stage && TERMINAL_STAGES.has(base.stage)) {
+        return { ...base, running: false, stale: false };
+    }
+    const hb = base.heartbeatAt ? Date.parse(base.heartbeatAt) : NaN;
+    const stale = !Number.isFinite(hb) || Date.now() - hb > STALE_MS;
+    return { ...base, running: true, stale };
+}
+//# sourceMappingURL=generation-status.js.map

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

@@ -1,11 +1,17 @@
 import { type Server } from 'node:http';
-import { type CatalogPaths, type CatencePaths } from '../../runtime/index.js';
+import { type DetachedSyncSpawner, mergeOpenCodeGoConsoleProfiles, startDetachedSync, type CatalogPaths, type CatencePaths } from '../../runtime/index.js';
 export type CatenceHttpServerOptions = {
     /** A shared catalog for public servers. All data APIs then require athleteId. */
     catalogPaths?: CatalogPaths;
     /** Internal compatibility hook for tests and embedded single-store callers. */
     paths?: CatencePaths;
     allowedOrigins?: readonly string[];
+    /** Internal compatibility hook for tests: override the detached sync spawner. */
+    startSync?: typeof startDetachedSync;
+    /** Internal compatibility hook for tests: passed into the default startDetachedSync. */
+    syncSpawnProcess?: DetachedSyncSpawner;
+    /** Internal compatibility hook for tests: override OpenCode Go model discovery. */
+    mergeModels?: typeof mergeOpenCodeGoConsoleProfiles;
 };
 /**
  * Create Catence's local Streamable HTTP server.

package/dist/interfaces/http/server.js

@@ -1,7 +1,9 @@
 import { createServer } from 'node:http';
+import path from 'node:path';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { catenceRuntimeHealth, DashboardSnapshotService, jsonSafe, loadCatalog, openReadOnlyRepository, resolveAthlete, resolveCatalogPaths } 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';
+import { generationStatus } from './generation-status.js';
 const MAX_REQUEST_BYTES = 1_000_000;
 function json(response, statusCode, value) {
     const body = JSON.stringify(jsonSafe(value));
@@ -85,6 +87,84 @@ async function dashboardPaths(catalogPaths, staticPaths, url) {
         return staticPaths;
     throw new Error('No Catence data store is configured.');
 }
+function parseSyncBody(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', 'provider', 'from', 'refresh', 'refreshModels'].includes(key)) {
+            throw new Error(`Unknown sync field: ${key}.`);
+        }
+    }
+    if (raw.athleteId !== undefined && typeof raw.athleteId !== 'string')
+        throw new Error('athleteId must be a string.');
+    if (raw.provider !== undefined && (typeof raw.provider !== 'string' || !DETACHED_SYNC_PROVIDERS.includes(raw.provider))) {
+        throw new Error('provider must be intervals, garmin, strava, or all.');
+    }
+    if (raw.from !== undefined && (typeof raw.from !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(raw.from))) {
+        throw new Error('from must use YYYY-MM-DD.');
+    }
+    for (const flag of ['refresh', 'refreshModels']) {
+        if (raw[flag] !== undefined && typeof raw[flag] !== 'boolean')
+            throw new Error(`${flag} must be a boolean.`);
+    }
+    return raw;
+}
+async function resolveSyncPaths(catalogPaths, staticPaths, body) {
+    if (catalogPaths) {
+        if (!body.athleteId)
+            throw new Error('athleteId is required. Call /api/v1/athletes to inspect the configured catalog.');
+        return (await resolveAthlete(catalogPaths, body.athleteId)).paths;
+    }
+    if (staticPaths)
+        return staticPaths;
+    throw new Error('No Catence data store is configured.');
+}
+/** Best-effort last-success timestamps; null while a run holds the write lock. */
+async function lastSyncSummary(paths) {
+    const completedAtIso = (value) => {
+        if (value instanceof Date)
+            return Number.isNaN(value.getTime()) ? null : value.toISOString();
+        if (typeof value === 'string' && value.trim())
+            return value;
+        return null;
+    };
+    try {
+        // 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();
+        }
+    }
+    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) {
     if (request.method !== 'POST') {
         methodNotAllowed(response);
@@ -143,6 +223,8 @@ export function createCatenceHttpServer(options = {}) {
     const catalogPaths = options.catalogPaths ?? (options.paths ? null : resolveCatalogPaths());
     const staticPaths = options.paths ?? null;
     const allowedOrigins = options.allowedOrigins ?? [];
+    const startSync = options.startSync ?? startDetachedSync;
+    const mergeModels = options.mergeModels ?? mergeOpenCodeGoConsoleProfiles;
     return createServer((request, response) => {
         void (async () => {
             if (!addCorsHeaders(request, response, allowedOrigins)) {
@@ -158,6 +240,10 @@ export function createCatenceHttpServer(options = {}) {
                 json(response, 200, catenceRuntimeHealth());
                 return;
             }
+            if (pathname === '/api/v1/health' && request.method === 'GET') {
+                json(response, 200, catenceRuntimeHealth());
+                return;
+            }
             if (pathname === '/api/v1/athletes' && request.method === 'GET') {
                 if (!catalogPaths) {
                     json(response, 200, { defaultAthleteId: 'local', athletes: [{ id: 'local', label: 'Local athlete' }] });
@@ -182,6 +268,103 @@ export function createCatenceHttpServer(options = {}) {
                 }
                 return;
             }
+            if (pathname === '/api/v1/sync' && request.method === 'POST') {
+                let body;
+                try {
+                    body = parseSyncBody(await readJsonBody(request));
+                    const paths = await resolveSyncPaths(catalogPaths, staticPaths, body);
+                    // Optional model self-discovery runs before the data sync so new
+                    // OpenCode Go models appear without a manual script run. Failure is
+                    // non-fatal: it must never block or fail a data sync. The Console
+                    // reads <CATENCE_HOME>/config.json, so catalog deployments merge
+                    // into the catalog root's config instead of the athlete store.
+                    const discoveryConfigPath = catalogPaths ? path.join(catalogPaths.root, 'config.json') : paths.config;
+                    let discoveryWarning = null;
+                    if (body.refreshModels) {
+                        try {
+                            await mergeModels({ configPath: discoveryConfigPath, setDefault: false });
+                        }
+                        catch (error) {
+                            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,
+                        // 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) {
+                    json(response, error instanceof DetachedSyncBusyError ? 409 : 400, {
+                        error: {
+                            code: error instanceof DetachedSyncBusyError ? 'sync_in_progress' : 'sync_start_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.
+                try {
+                    const body = await readJsonBody(request).catch(() => ({}));
+                    const raw = (body ?? {});
+                    if (raw.setDefault !== undefined && typeof raw.setDefault !== 'boolean')
+                        throw new Error('setDefault must be a boolean.');
+                    const configPath = catalogPaths ? path.join(catalogPaths.root, 'config.json') : staticPaths?.config;
+                    if (!configPath)
+                        throw new Error('No Catence data store is configured.');
+                    json(response, 200, jsonSafe(await mergeModels({ configPath, setDefault: raw.setDefault === true })));
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'model_discovery_failed', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/sync/status' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    const paths = await dashboardPaths(catalogPaths, staticPaths, url);
+                    const athleteId = catalogPaths ? (await resolveAthlete(catalogPaths, url.searchParams.get('athleteId') ?? '')).athlete.id : 'local';
+                    json(response, 200, { athleteId, progress: await syncProgress(paths), lastSync: await lastSyncSummary(paths) });
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'sync_status_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname.startsWith('/api/v1/threads/') &&
+                pathname.endsWith('/generation') &&
+                request.method === 'GET') {
+                try {
+                    const segments = pathname.split('/').filter(Boolean);
+                    const threadId = segments[segments.length - 2];
+                    if (!threadId)
+                        throw new Error('Missing threadId in request path.');
+                    const base = (catalogPaths ?? staticPaths ?? resolveCatalogPaths());
+                    const root = base?.root;
+                    if (!root || typeof root !== 'string') {
+                        throw new Error('No Catence data store is configured.');
+                    }
+                    json(response, 200, await generationStatus(root, threadId));
+                }
+                catch (error) {
+                    json(response, 400, {
+                        error: {
+                            code: 'generation_status_unavailable',
+                            message: error instanceof Error ? error.message : String(error)
+                        }
+                    });
+                }
+                return;
+            }
             if (pathname === '/mcp') {
                 await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths());
                 return;

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

@@ -1,8 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type CatalogPaths, hydrateStravaActivity, type CatencePaths } from '../../runtime/index.js';
+import { type CatalogPaths, hydrateStravaActivity, startDetachedSync, type CatencePaths } from '../../runtime/index.js';
 type StravaActivityHydrator = typeof hydrateStravaActivity;
 type McpDependencies = {
     hydrateStravaActivity?: StravaActivityHydrator;
+    startDetachedSync?: typeof startDetachedSync;
 };
 export declare function createCatenceMcpServer(paths?: CatencePaths | CatalogPaths, dependencies?: McpDependencies): McpServer;
 export {};

package/dist/interfaces/mcp/server.js

@@ -1,7 +1,7 @@
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
-import { ActivityDiscoveryService, AnalyticsService, loadCatalog, configuredMcpRateLimit, DataWriteBusyError, DATASET_CATALOG, demoStoreMetadata, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, searchContext, SlidingWindowLimiter, StravaEnrichmentError, StravaRateLimitError, SwimmingService, WELLNESS_METRICS, WellnessService, } from '../../runtime/index.js';
+import { ActivityDiscoveryService, AnalyticsService, loadCatalog, configuredMcpRateLimit, DataWriteBusyError, DATASET_CATALOG, demoStoreMetadata, DetachedSyncBusyError, FitnessService, getDataset, hydrateStravaActivity, hydrateStravaSegmentHistory, jsonSafe, loadCatenceConfig, openReadOnlyRepository, queryReadOnlyData, QueryValidationError, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, searchContext, SlidingWindowLimiter, startDetachedSync, StravaEnrichmentError, StravaRateLimitError, SwimmingService, WELLNESS_METRICS, WellnessService, } from '../../runtime/index.js';
 const filterSchema = z.object({
     column: z.string().min(1),
     op: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'between', 'contains']),
@@ -32,17 +32,19 @@ function textResult(value) {
     return { content: [{ type: 'text', text: JSON.stringify(jsonSafe(value), null, 2) }] };
 }
 function errorResult(error) {
-    const classified = error instanceof DataWriteBusyError
-        ? { code: 'data_sync_in_progress', message: error.message, retryable: true }
-        : error instanceof StravaRateLimitError
-            ? { code: 'rate_limited', message: error.message, retryable: true, retryAfterSeconds: error.retryAfterSeconds ?? null }
-            : error instanceof StravaEnrichmentError
-                ? { code: 'strava_connection_error', message: error.message }
-                : error instanceof ReadOnlyDatabaseError
-                    ? { code: error.code, message: error.message }
-                    : error instanceof QueryValidationError
-                        ? { code: 'invalid_request', message: error.message }
-                        : { code: 'data_unavailable', message: error instanceof Error ? error.message : String(error) };
+    const classified = error instanceof DetachedSyncBusyError
+        ? { code: 'sync_in_progress', message: error.message, retryable: true, runId: error.runId }
+        : error instanceof DataWriteBusyError
+            ? { code: 'data_sync_in_progress', message: error.message, retryable: true }
+            : error instanceof StravaRateLimitError
+                ? { code: 'rate_limited', message: error.message, retryable: true, retryAfterSeconds: error.retryAfterSeconds ?? null }
+                : error instanceof StravaEnrichmentError
+                    ? { code: 'strava_connection_error', message: error.message }
+                    : error instanceof ReadOnlyDatabaseError
+                        ? { code: error.code, message: error.message }
+                        : error instanceof QueryValidationError
+                            ? { code: 'invalid_request', message: error.message }
+                            : { code: 'data_unavailable', message: error instanceof Error ? error.message : String(error) };
     return { ...textResult({ data: null, provenance: {}, query: {}, caveats: [classified.message], error: classified }), isError: true };
 }
 function hydrationFailure(error) {
@@ -123,6 +125,7 @@ async function activitySegments(repository, activityId, hydratedStravaActivityId
 export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependencies = {}) {
     const server = new McpServer({ name: 'catence', version: '0.1.0' }, { instructions: MCP_INSTRUCTIONS });
     const hydrateActivity = dependencies.hydrateStravaActivity ?? hydrateStravaActivity;
+    const startSync = dependencies.startDetachedSync ?? startDetachedSync;
     const catalogPaths = isCatalogPaths(paths) ? paths : null;
     const staticPaths = isCatalogPaths(paths) ? null : paths;
     const scope = new AsyncLocalStorage();
@@ -176,7 +179,12 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
                     ...(demoStore ? { demoStore: { generated: true, seed: demoStore.seed, days: demoStore.days, startDate: demoStore.startDate, endDate: demoStore.endDate }, caveats: [...caveats, 'This response uses Catence generated demo data, not personal measurements.'] } : {}),
                 });
             };
-            return selected ? scope.run(selected, run) : run();
+            // `return await` matters here: a bare `return run()` would let a
+            // rejected promise escape the try block, bypassing the classified
+            // errorResult payload entirely.
+            if (selected)
+                return await scope.run(selected, run);
+            return await run();
         }
         catch (error) {
             return errorResult(error);
@@ -231,6 +239,35 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         data: { ...(await repository.status()), ...(await repository.coverage()) },
         provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
     }))));
+    server.registerTool('catence_sync_progress', {
+        title: 'Catence sync progress',
+        description: 'Read live progress heartbeats for active sync runs, plus the most recent completed or interrupted runs. Read-only.',
+    }, tool('catence_sync_progress', async () => useRepository(activePaths(), async (repository) => ({
+        data: await repository.progress(),
+        provenance: { database: 'read-only DuckDB snapshot' }, query: {}, caveats: [],
+    }))));
+    server.registerTool('start_detached_sync', {
+        title: 'Start a detached data sync',
+        description: 'Write-only sync trigger, named like the other explicit lock-guarded write tools. Spawns one detached catence-data sync process for this athlete and returns immediately with the run handle and log file; it refuses while another sync run is active. Track the run with catence_sync_progress; this tool never waits for completion.',
+        inputSchema: {
+            provider: z.enum(['intervals', 'garmin', 'strava', 'all']).optional(),
+            from: z.string().date().optional(),
+            refresh: z.boolean().optional(),
+        },
+    }, 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 });
+        return {
+            data: { ...handle, progressTool: 'catence_sync_progress' },
+            provenance: { operation: 'detached_sync_spawn' },
+            query: { ...input },
+            caveats: [
+                'The sync runs in its own process and keeps running if this session ends; its log file records the full worker output.',
+                'Only one sync run may be active per athlete store.',
+            ],
+        };
+    }));
     server.registerTool('review_daily_recovery_load', {
         title: 'Review daily recovery and training load',
         description: 'Return source-cited daily health, training, and nutrition facts for a recovery/load review. It does not prescribe a training plan.',

package/dist/runtime/index.d.ts

@@ -7,6 +7,8 @@
  * without changing the public product adapters.
  */
 export type { CatencePaths } from '../contracts/runtime.js';
+export { channelForVersion, compareReleaseVersions, fetchNpmDistTags, fetchPypiReleases, hasCommand, isGlobalNpmInstall, latestRelease, npmGlobalPrefix, parseReleaseVersion, planSelfUpdate, readInstalledConsoleVersion, runSelfUpdateCommand, } from '../core/runtime/self-update.js';
+export type { SelfUpdatePlan, UpdateChannel } from '../core/runtime/self-update.js';
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
@@ -26,8 +28,13 @@ export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
+export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, importStagedFile, linkActivity, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
 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 { 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';
 export { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/dist/runtime/index.js

@@ -1,3 +1,4 @@
+export { channelForVersion, compareReleaseVersions, fetchNpmDistTags, fetchPypiReleases, hasCommand, isGlobalNpmInstall, latestRelease, npmGlobalPrefix, parseReleaseVersion, planSelfUpdate, readInstalledConsoleVersion, runSelfUpdateCommand, } from '../core/runtime/self-update.js';
 export { CATENCE_PROTOCOL_VERSION, CATENCE_RUNTIME_VERSION, catenceRuntimeHealth } from '../contracts/release.js';
 export { configuredMcpRateLimit, loadCatenceConfig, resolvePaths } from '../core/runtime/configuration.js';
 export { addAthlete, athleteStorePaths, defaultAthlete, defaultCatalogHome, initializeCatalog, loadCatalog, resolveAthlete, resolveCatalogPaths, } from '../core/runtime/catalog.js';
@@ -14,7 +15,9 @@ export { WELLNESS_METRICS, WellnessService } from '../core/query/wellness.js';
 export { jsonSafe, ReadOnlyRepository } from '../core/query/repository.js';
 export { queryReadOnlyData } from '../core/query/sql-guard.js';
 export { createDemoStore, demoStoreMetadata } from '../elt/application/demo.js';
-export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, retryDataSync, syncData, unlinkActivity, } from '../elt/application/management.js';
+export { connectStrava, connectStravaWithCallback, dataStatus, disconnectStravaAccount, initializeDataStore, importStagedFile, linkActivity, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, retryDataSync, syncData, syncProgress, unlinkActivity, } from '../elt/application/management.js';
+export { DETACHED_SYNC_PROVIDERS, DetachedSyncBusyError, startDetachedSync, } from '../elt/application/detached-sync.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 { openReadOnlyRepository, ReadOnlyDatabaseError } from '../elt/storage/database.js';
 export { DataWriteBusyError } from '../elt/storage/write-lock.js';
 export { hydrateStravaActivity, hydrateStravaSegmentHistory, StravaEnrichmentError, StravaRateLimitError, } from '../elt/ingestion/providers/strava/service.js';

package/docs/architecture.md

@@ -87,7 +87,17 @@ The query layer has four shared pieces:
 
 ### 4. Serving and retrieval
 
-The server exposes `catence_status`, `describe_data`, `describe_dataset`, `read_series`, `aggregate_data`, `analyze_series`, `fit_series_model`, `query_read_only_data`, `find_activities`, `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, `power_coverage_report`, `latest_cycling_activities`, `cycling_progress_report`, `review_daily_recovery_load`, `review_weekly_training`, `review_activity_deep_dive`, `search_context`, `hydrate_strava_activity`, `hydrate_recent_strava_activities`, and `hydrate_strava_segment_history`, plus resources for status, catalog, a single activity, and a date-range summary.
+The server exposes these tools, grouped by purpose:
+
+- Catalog and status: `list_athletes`, `catence_status`, `catence_sync_progress`.
+- Review workflows: `review_daily_recovery_load`, `review_weekly_training`, `review_activity_deep_dive`, plus the matching `daily_recovery_load_review`, `weekly_training_review`, and `activity_deep_dive` prompts.
+- General data and analytics: `describe_data`, `describe_dataset`, `read_series`, `aggregate_data`, `analyze_series`, `fit_series_model`, `query_read_only_data`, `search_context`.
+- Wellness: `wellness_correlate`, `wellness_baselines`, `wellness_anomalies`, `wellness_coverage`.
+- Fitness and progress: `get_ftp_history`, `get_vo2max_history`, `power_curve_trend`, `power_coverage_report`, `latest_cycling_activities`, `cycling_progress_report`, `get_swim_laps`, `swim_progress_report`.
+- Activity detail and segments: `find_activities`, `get_activity_segments`.
+- Strava hydration (the only writers): `hydrate_strava_activity`, `hydrate_recent_strava_activities`, `hydrate_strava_segment_history`.
+
+Resources are mode-dependent. In catalog mode the server registers only `athletes` (`catence://athletes`), the machine-readable roster of configured athlete IDs and labels; in a single-store (non-catalog) deployment it registers resources for status, catalog, a single activity template (`catence://activity/{activityId}`), and a date-range summary template (`catence://summary/{startDate}/{endDate}`).
 
 `catence serve` is a loopback-only-by-default Streamable HTTP adapter. It creates a stateless MCP server and transport for each `/mcp` request, so the HTTP and stdio surfaces use the same tool implementation. `GET /health` is a versioned client handshake with runtime version, protocol version, and capabilities; distributed Console builds reject an incompatible protocol before starting a chat. The same listener serves a small read-only `/api/v1/dashboard` snapshot for the local Console: canonical daily-health rows, weekly canonical activity aggregates, recent canonical activities, status, coverage, and explicit missing-data caveats.