catence 0.2.0-beta.16 → 0.2.0-beta.18

package/README.md

@@ -7,9 +7,9 @@ Catence is a local-first fitness MCP server for Garmin, Intervals.icu, and targe
 ## What is included
 
 - Garmin, Intervals.icu, and Strava ingestion with source-aware normalization.
-- Read-only MCP tools, plus explicitly named, lock-guarded Strava hydration tools.
+- Read-only MCP tools, plus explicitly named, lock-guarded write tools for Strava hydration and detached syncs.
 - One shared Catence agent can serve several isolated athlete stores. Every personal-data MCP call names an `athleteId`; Catence never silently combines athletes.
-- A password-protected Chainlit Console with an authenticated dashboard.
+- A password-protected Chainlit Console with an authenticated dashboard, a data-sync button with live progress, and in-app model management.
 - A generated demo catalog for safe evaluation in Glama, desktop MCP clients, or local development.
 
 Catence helps explore recovery, training load, trends, activity detail, swimming/cycling/running progress, segments, gear, and data quality. It reports the evidence and coverage it can see; it does not diagnose or prescribe training.

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

package/dist/core/runtime/configuration.d.ts

@@ -12,7 +12,7 @@ declare const rateLimitSchema: z.ZodObject<{
     requests: z.ZodNumber;
     windowSeconds: z.ZodNumber;
 }, z.core.$strict>;
-declare const catenceConfigSchema: z.ZodObject<{
+export declare const catenceConfigSchema: z.ZodObject<{
     mcp: z.ZodOptional<z.ZodObject<{
         rateLimits: z.ZodOptional<z.ZodObject<{
             server: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -50,6 +50,8 @@ declare const catenceConfigSchema: z.ZodObject<{
             models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
                 label: z.ZodOptional<z.ZodString>;
                 model: z.ZodString;
+                reasoningEffort: z.ZodOptional<z.ZodString>;
+                variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             }, z.core.$strict>>>;
             defaultModel: z.ZodOptional<z.ZodString>;
             defaultReasoningEffort: z.ZodOptional<z.ZodEnum<{

package/dist/core/runtime/configuration.js

@@ -32,9 +32,13 @@ export function requireIntervalsConfig(environment = process.env) {
 const rateLimitSchema = z.object({ requests: z.number().int().positive(), windowSeconds: z.number().int().positive() }).strict();
 const nullableRateLimitSchema = rateLimitSchema.nullable();
 const environmentVariableSchema = z.string().regex(/^[A-Z][A-Z0-9_]*$/, 'must be an uppercase environment-variable name');
+// Keep this aligned with the Console's Python validator, which accepts a
+// per-model reasoningEffort and free-form reasoning-effort variants.
 const consoleModelSchema = z.object({
     label: z.string().min(1).optional(),
     model: z.string().min(1),
+    reasoningEffort: z.string().min(1).optional(),
+    variants: z.record(z.string(), z.string()).optional(),
 }).strict();
 const consoleProfileSchema = z.object({
     label: z.string().min(1).optional(),
@@ -60,7 +64,7 @@ const consoleLimitsSchema = z.object({
     toolRounds: z.number().int().min(1).max(32).optional(),
     toolResultCharacters: z.number().int().min(1_000).max(250_000).optional(),
 }).strict();
-const catenceConfigSchema = z.object({
+export const catenceConfigSchema = z.object({
     mcp: z.object({
         rateLimits: z.object({
             server: nullableRateLimitSchema.optional(),

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

@@ -0,0 +1,52 @@
+export declare const OPENCODE_GO_DEFAULT_BASE_URL = "https://opencode.ai/zen/go/v1";
+export declare const OPENCODE_GO_API_KEY_ENV = "OPENCODE_GO_API_KEY";
+export declare const OPENCODE_GO_API_BASE_ENV = "OPENCODE_GO_API_BASE";
+export declare const OPENCODE_GO_MESSAGES_API_BASE_ENV = "OPENCODE_GO_MESSAGES_API_BASE";
+export type OpenCodeGoRoute = 'chat' | 'responses' | 'messages';
+/** Live model ids plus trusted routing metadata ("live discovery + trusted metadata"). */
+export declare function classifyOpenCodeGoModel(id: string): {
+    route: OpenCodeGoRoute;
+    guessed: boolean;
+};
+export type OpenCodeGoConsoleProfiles = {
+    profiles: Record<string, Record<string, unknown>>;
+    defaultProfile: string;
+    counts: {
+        chat: number;
+        responses: number;
+        messages: number;
+    };
+    guessedRoutes: string[];
+};
+/**
+ * Build the two ready-made Console profiles from live model ids.
+ *
+ * The public `GET /models` endpoint returns only ids, not which API each model
+ * needs, so routing comes from the trusted table intersected with the live
+ * list; prefix-guessed routes are reported so callers can warn.
+ */
+export declare function buildOpenCodeGoConsoleProfiles(modelIds: readonly string[], baseUrl?: string): OpenCodeGoConsoleProfiles;
+export declare function fetchOpenCodeGoModelIds(baseUrl?: string): Promise<string[]>;
+export type OpenCodeGoMergeResult = {
+    configPath: string;
+    mergedProfileIds: string[];
+    defaultProfile: string;
+    counts: {
+        chat: number;
+        responses: number;
+        messages: number;
+    };
+    guessedRoutes: string[];
+};
+/**
+ * Fetch the live OpenCode Go catalog and merge the two Console profiles into
+ * `configPath`, preserving every other section plus existing console fields
+ * (`limits`, other profiles) and the existing `defaultProfile` unless
+ * `setDefault` is passed. The written file is re-validated with the same
+ * strict schema the runtime applies on load, then replaced atomically.
+ */
+export declare function mergeOpenCodeGoConsoleProfiles(options: {
+    configPath: string;
+    baseUrl?: string;
+    setDefault?: boolean;
+}): Promise<OpenCodeGoMergeResult>;

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

@@ -0,0 +1,189 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { catenceConfigSchema } from './configuration.js';
+export const OPENCODE_GO_DEFAULT_BASE_URL = 'https://opencode.ai/zen/go/v1';
+export const OPENCODE_GO_API_KEY_ENV = 'OPENCODE_GO_API_KEY';
+export const OPENCODE_GO_API_BASE_ENV = 'OPENCODE_GO_API_BASE';
+export const OPENCODE_GO_MESSAGES_API_BASE_ENV = 'OPENCODE_GO_MESSAGES_API_BASE';
+// LiteLLM appends a fixed suffix to the profile base URL per provider, so the
+// three APIs need different prefixes and two base URLs:
+//   openai/<id>             -> {base}/chat/completions
+//   openai/responses/<id>   -> {base}/responses
+//   anthropic/<id>          -> {base minus /v1}/v1/messages
+const RESPONSES_MODELS = new Set(['grok-4.5', 'gpt-5.6-luna']);
+const MESSAGES_MODELS = new Set([
+    'minimax-m2.5',
+    'minimax-m2.7',
+    'minimax-m3',
+    'qwen3.5-plus',
+    'qwen3.6-plus',
+    'qwen3.7-plus',
+    'qwen3.7-max',
+    'qwen3.8-max',
+]);
+const BRAND_NAMES = new Map([
+    ['deepseek', 'DeepSeek'],
+    ['glm', 'GLM'],
+    ['gpt', 'GPT'],
+    ['grok', 'Grok'],
+    ['hy3', 'Hy3'],
+    ['kimi', 'Kimi'],
+    ['mimo', 'MiMo'],
+    ['minimax', 'MiniMax'],
+    ['qwen', 'Qwen'],
+]);
+const CHAT_PROFILE_ID = 'opencode-go';
+const MESSAGES_PROFILE_ID = 'opencode-go-messages';
+/** Live model ids plus trusted routing metadata ("live discovery + trusted metadata"). */
+export function classifyOpenCodeGoModel(id) {
+    if (RESPONSES_MODELS.has(id))
+        return { route: 'responses', guessed: false };
+    if (MESSAGES_MODELS.has(id))
+        return { route: 'messages', guessed: false };
+    if (/^(grok-|gpt-)/.test(id))
+        return { route: 'responses', guessed: true };
+    if (/^(minimax-|qwen)/.test(id))
+        return { route: 'messages', guessed: true };
+    return { route: 'chat', guessed: false };
+}
+function modelReference(id, route) {
+    if (route === 'responses')
+        return `openai/responses/${id}`;
+    if (route === 'messages')
+        return `anthropic/${id}`;
+    return `openai/${id}`;
+}
+function labelFor(id) {
+    return id
+        .split('-')
+        .map((segment) => BRAND_NAMES.get(segment) ?? segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join(' ');
+}
+/**
+ * Build the two ready-made Console profiles from live model ids.
+ *
+ * The public `GET /models` endpoint returns only ids, not which API each model
+ * needs, so routing comes from the trusted table intersected with the live
+ * list; prefix-guessed routes are reported so callers can warn.
+ */
+export function buildOpenCodeGoConsoleProfiles(modelIds, baseUrl = OPENCODE_GO_DEFAULT_BASE_URL) {
+    const groups = { chat: [], responses: [], messages: [] };
+    const guessedRoutes = [];
+    for (const id of modelIds) {
+        if (!id)
+            continue;
+        const { route, guessed } = classifyOpenCodeGoModel(id);
+        groups[route].push(id);
+        if (guessed)
+            guessedRoutes.push(`${id} -> ${route}`);
+    }
+    for (const route of Object.keys(groups))
+        groups[route].sort();
+    const chatModels = {};
+    for (const id of [...groups.chat, ...groups.responses]) {
+        chatModels[id] = { label: labelFor(id), model: modelReference(id, groups.chat.includes(id) ? 'chat' : 'responses') };
+    }
+    const messagesModels = {};
+    for (const id of groups.messages) {
+        messagesModels[id] = { label: labelFor(id), model: modelReference(id, 'messages') };
+    }
+    const chatDefault = groups.chat[0] ?? groups.responses[0];
+    const profiles = {
+        [CHAT_PROFILE_ID]: {
+            label: 'OpenCode Go',
+            ...(chatDefault ? { defaultModel: chatDefault } : {}),
+            models: chatModels,
+            apiKeyEnv: OPENCODE_GO_API_KEY_ENV,
+            apiBaseEnv: OPENCODE_GO_API_BASE_ENV,
+        },
+    };
+    if (groups.messages.length) {
+        profiles[MESSAGES_PROFILE_ID] = {
+            label: 'OpenCode Go (Anthropic)',
+            defaultModel: groups.messages[0],
+            models: messagesModels,
+            apiKeyEnv: OPENCODE_GO_API_KEY_ENV,
+            apiBaseEnv: OPENCODE_GO_MESSAGES_API_BASE_ENV,
+        };
+    }
+    return {
+        profiles,
+        defaultProfile: CHAT_PROFILE_ID,
+        counts: { chat: groups.chat.length, responses: groups.responses.length, messages: groups.messages.length },
+        guessedRoutes,
+    };
+}
+export async function fetchOpenCodeGoModelIds(baseUrl = OPENCODE_GO_DEFAULT_BASE_URL) {
+    const modelsUrl = `${baseUrl.replace(/\/$/, '')}/models`;
+    let response;
+    try {
+        response = await fetch(modelsUrl, { headers: { accept: 'application/json' } });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${modelsUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new Error(`GET ${modelsUrl} returned HTTP ${response.status}.`);
+    const payload = (await response.json());
+    const ids = (payload.data ?? []).map((entry) => entry.id).filter((id) => typeof id === 'string' && Boolean(id));
+    if (!ids.length)
+        throw new Error(`GET ${modelsUrl} returned no models.`);
+    return ids;
+}
+async function readConfigRoot(configPath) {
+    try {
+        const root = JSON.parse(await readFile(configPath, 'utf8'));
+        if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+            throw new Error(`${configPath} must contain a JSON object.`);
+        }
+        return root;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+/**
+ * Fetch the live OpenCode Go catalog and merge the two Console profiles into
+ * `configPath`, preserving every other section plus existing console fields
+ * (`limits`, other profiles) and the existing `defaultProfile` unless
+ * `setDefault` is passed. The written file is re-validated with the same
+ * strict schema the runtime applies on load, then replaced atomically.
+ */
+export async function mergeOpenCodeGoConsoleProfiles(options) {
+    const baseUrl = options.baseUrl ?? OPENCODE_GO_DEFAULT_BASE_URL;
+    const modelIds = await fetchOpenCodeGoModelIds(baseUrl);
+    const built = buildOpenCodeGoConsoleProfiles(modelIds, baseUrl);
+    const root = await readConfigRoot(options.configPath);
+    const existingConsole = typeof root.console === 'object' && root.console !== null && !Array.isArray(root.console)
+        ? root.console
+        : {};
+    const existingProfiles = typeof existingConsole.profiles === 'object' && existingConsole.profiles !== null && !Array.isArray(existingConsole.profiles)
+        ? existingConsole.profiles
+        : {};
+    const defaultProfile = typeof existingConsole.defaultProfile === 'string' && existingConsole.defaultProfile && !options.setDefault
+        ? existingConsole.defaultProfile
+        : built.defaultProfile;
+    const updatedConsole = {
+        ...existingConsole,
+        defaultProfile,
+        profiles: { ...existingProfiles, ...built.profiles },
+    };
+    // Validate before writing anything: the runtime rejects invalid configs at
+    // load time, so a bad merge must never reach disk.
+    const candidate = { ...root, console: updatedConsole };
+    catenceConfigSchema.parse(candidate);
+    await mkdir(path.dirname(options.configPath), { recursive: true });
+    const temporaryPath = `${options.configPath}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify(candidate, null, 2)}\n`, 'utf8');
+    await rename(temporaryPath, options.configPath);
+    return {
+        configPath: options.configPath,
+        mergedProfileIds: Object.keys(built.profiles),
+        defaultProfile,
+        counts: built.counts,
+        guessedRoutes: built.guessedRoutes,
+    };
+}
+//# sourceMappingURL=opencode-go.js.map

package/dist/core/runtime/secrets.js

@@ -42,27 +42,65 @@ export async function setAthleteSecret(paths, provider, field, value) {
     await rename(temporary, destination);
     await chmod(destination, 0o600);
 }
+function isTruthyEnvValue(value) {
+    if (!value)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+function isGenericEnvFallbackAllowed(base) {
+    const direct = base.CATENCE_ALLOW_ENV_SECRETS ?? base.CATENCE_SECRETS_FROM_ENV ?? process.env.CATENCE_ALLOW_ENV_SECRETS ?? process.env.CATENCE_SECRETS_FROM_ENV;
+    return isTruthyEnvValue(direct);
+}
+function athleteEnvPrefix(paths) {
+    const athleteId = path.basename(path.dirname(paths.secrets));
+    const normalized = athleteId.replace(/[^a-zA-Z0-9]/g, '_').toUpperCase();
+    return `CATENCE_ATHLETE_${normalized}_`;
+}
+function resolveWithEnvFallback(fileValue, envName, perAthletePrefix, base, allowGeneric) {
+    if (fileValue)
+        return fileValue;
+    const perAthleteName = `${perAthletePrefix}${envName}`;
+    const perAthleteValue = base[perAthleteName] ?? process.env[perAthleteName];
+    if (perAthleteValue)
+        return perAthleteValue;
+    if (!allowGeneric)
+        return undefined;
+    const genericValue = base[envName] ?? process.env[envName];
+    if (genericValue)
+        return genericValue;
+    return undefined;
+}
 /** Build only the provider environment needed by a selected athlete worker. */
 export async function athleteProviderEnvironment(paths, base = process.env) {
     const secrets = await readAthleteSecrets(paths);
     const environment = { ...base };
+    const allowGenericEnv = isGenericEnvFallbackAllowed(base);
+    const perAthletePrefix = athleteEnvPrefix(paths);
     // Never let credentials inherited by the shared process leak into an
-    // athlete store that has not explicitly configured that provider.
+    // athlete store that has not explicitly configured that provider, unless
+    // the operator has opted in via CATENCE_ALLOW_ENV_SECRETS or is using a
+    // per-athlete scoped variable (CATENCE_ATHLETE_<ID>_GARMIN_EMAIL etc.).
     for (const name of ['GARMIN_EMAIL', 'GARMIN_PASSWORD', 'INTERVALS_API_KEY', 'INTERVALS_ATHLETE_ID', 'STRAVA_CLIENT_ID', 'STRAVA_CLIENT_SECRET']) {
         delete environment[name];
     }
-    if (secrets.garmin?.email)
-        environment.GARMIN_EMAIL = secrets.garmin.email;
-    if (secrets.garmin?.password)
-        environment.GARMIN_PASSWORD = secrets.garmin.password;
-    if (secrets.intervals?.apiKey)
-        environment.INTERVALS_API_KEY = secrets.intervals.apiKey;
-    if (secrets.intervals?.athleteId)
-        environment.INTERVALS_ATHLETE_ID = secrets.intervals.athleteId;
-    if (secrets.strava?.clientId)
-        environment.STRAVA_CLIENT_ID = secrets.strava.clientId;
-    if (secrets.strava?.clientSecret)
-        environment.STRAVA_CLIENT_SECRET = secrets.strava.clientSecret;
+    const garminEmail = resolveWithEnvFallback(secrets.garmin?.email, 'GARMIN_EMAIL', perAthletePrefix, base, allowGenericEnv);
+    const garminPassword = resolveWithEnvFallback(secrets.garmin?.password, 'GARMIN_PASSWORD', perAthletePrefix, base, allowGenericEnv);
+    const intervalsApiKey = resolveWithEnvFallback(secrets.intervals?.apiKey, 'INTERVALS_API_KEY', perAthletePrefix, base, allowGenericEnv);
+    const intervalsAthleteId = resolveWithEnvFallback(secrets.intervals?.athleteId, 'INTERVALS_ATHLETE_ID', perAthletePrefix, base, allowGenericEnv);
+    const stravaClientId = resolveWithEnvFallback(secrets.strava?.clientId, 'STRAVA_CLIENT_ID', perAthletePrefix, base, allowGenericEnv);
+    const stravaClientSecret = resolveWithEnvFallback(secrets.strava?.clientSecret, 'STRAVA_CLIENT_SECRET', perAthletePrefix, base, allowGenericEnv);
+    if (garminEmail)
+        environment.GARMIN_EMAIL = garminEmail;
+    if (garminPassword)
+        environment.GARMIN_PASSWORD = garminPassword;
+    if (intervalsApiKey)
+        environment.INTERVALS_API_KEY = intervalsApiKey;
+    if (intervalsAthleteId)
+        environment.INTERVALS_ATHLETE_ID = intervalsAthleteId;
+    if (stravaClientId)
+        environment.STRAVA_CLIENT_ID = stravaClientId;
+    if (stravaClientSecret)
+        environment.STRAVA_CLIENT_SECRET = stravaClientSecret;
     return environment;
 }
 //# sourceMappingURL=secrets.js.map

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

@@ -0,0 +1,40 @@
+import { type SpawnOptions } from 'node:child_process';
+import type { CatencePaths } from '../../contracts/runtime.js';
+export declare const DETACHED_SYNC_PROVIDERS: readonly ["intervals", "garmin", "strava", "all"];
+export type DetachedSyncProvider = (typeof DETACHED_SYNC_PROVIDERS)[number];
+export type DetachedSyncRequest = {
+    paths: CatencePaths;
+    athleteId: string;
+    provider?: DetachedSyncProvider;
+    from?: string;
+    refresh?: boolean;
+};
+export type DetachedSyncHandle = {
+    started: true;
+    athleteId: string;
+    provider: DetachedSyncProvider;
+    logFile: string;
+};
+/** Raised when another sync run is already active for this store. */
+export declare class DetachedSyncBusyError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/** Minimal structural spawner so tests can inject a fake child process. */
+export type DetachedSyncSpawner = (command: string, arguments_: readonly string[], options: SpawnOptions) => {
+    unref(): void;
+};
+/**
+ * Spawn one detached `catence-data sync` process for an athlete store and
+ * return immediately.
+ *
+ * The child outlives this process (SSH deaths, Console restarts), logs to a
+ * file under the catalog home, and is guarded by the same live-progress
+ * heartbeat check the progress tools use. The guard and the spawn are not
+ * atomic; the single-writer DuckDB lock remains the authoritative guard, so a
+ * racing second child fails cleanly in its own log file.
+ */
+export declare function startDetachedSync(request: DetachedSyncRequest, dependencies?: {
+    now?: () => Date;
+    spawnProcess?: DetachedSyncSpawner;
+}): Promise<DetachedSyncHandle>;

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

@@ -0,0 +1,78 @@
+import { spawn } from 'node:child_process';
+import { open, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { syncProgress } from './management.js';
+export const DETACHED_SYNC_PROVIDERS = ['intervals', 'garmin', 'strava', 'all'];
+/** Raised when another sync run is already active for this store. */
+export class DetachedSyncBusyError extends Error {
+    runId;
+    constructor(runId) {
+        super(`A Catence sync run is already active (${runId}). Watch it with the progress tools instead of starting another.`);
+        this.name = 'DetachedSyncBusyError';
+        this.runId = runId;
+    }
+}
+/**
+ * Resolve the packaged `catence-data` CLI entry next to this module. In a
+ * built install both live under dist/; source checkouts run through tsx and
+ * tests inject their own spawner.
+ */
+function cliScriptPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../interfaces/cli/main.js');
+}
+function assertValidRequest(request) {
+    if (!request.athleteId || !/^[a-z][a-z0-9-]{0,62}$/.test(request.athleteId)) {
+        throw new Error('athleteId is required and must be a lowercase athlete identifier.');
+    }
+    if (request.provider !== undefined && !DETACHED_SYNC_PROVIDERS.includes(request.provider)) {
+        throw new Error('provider must be intervals, garmin, strava, or all.');
+    }
+    if (request.from !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(request.from)) {
+        throw new Error('from must use YYYY-MM-DD.');
+    }
+}
+/**
+ * Spawn one detached `catence-data sync` process for an athlete store and
+ * return immediately.
+ *
+ * The child outlives this process (SSH deaths, Console restarts), logs to a
+ * file under the catalog home, and is guarded by the same live-progress
+ * heartbeat check the progress tools use. The guard and the spawn are not
+ * atomic; the single-writer DuckDB lock remains the authoritative guard, so a
+ * racing second child fails cleanly in its own log file.
+ */
+export async function startDetachedSync(request, dependencies = {}) {
+    assertValidRequest(request);
+    const provider = request.provider ?? 'all';
+    const snapshot = await syncProgress(request.paths);
+    const activeRun = snapshot.running[0];
+    if (activeRun)
+        throw new DetachedSyncBusyError(activeRun.runId);
+    const stamp = (dependencies.now ?? (() => new Date()))().toISOString().replace(/[:.]/g, '-');
+    const logFile = path.join(request.paths.root, 'logs', `sync-${request.athleteId}-${stamp}.log`);
+    await mkdir(path.dirname(logFile), { recursive: true });
+    await writeFile(logFile, `[${new Date().toISOString()}] catence-data --athlete ${request.athleteId} sync --provider ${provider}${request.from ? ` --from ${request.from}` : ''}${request.refresh ? ' --refresh' : ''}\n`, 'utf8');
+    const arguments_ = [cliScriptPath(), '--home', request.paths.root, '--athlete', request.athleteId, 'sync', '--provider', provider];
+    if (request.from)
+        arguments_.push('--from', request.from);
+    if (request.refresh)
+        arguments_.push('--refresh');
+    // The file handle stays open only for the spawn; the detached child holds
+    // its own duplicate of the descriptor afterwards.
+    const logHandle = await open(logFile, 'a');
+    try {
+        const spawnProcess = dependencies.spawnProcess ?? spawn;
+        const child = spawnProcess(process.execPath, arguments_, {
+            detached: true,
+            stdio: ['ignore', logHandle.fd, logHandle.fd],
+            env: process.env,
+        });
+        child.unref();
+    }
+    finally {
+        await logHandle.close();
+    }
+    return { started: true, athleteId: request.athleteId, provider, logFile };
+}
+//# sourceMappingURL=detached-sync.js.map

package/dist/elt/application/management.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -28,6 +28,86 @@ function baseProgress(runId, provider, stage) {
         estimatedRemainingSeconds: null, heartbeatAt: new Date().toISOString(),
     };
 }
+/**
+ * Run the standalone swim-length backfill without progress streaming.
+ * The backfill reads every archived Garmin FIT (already on disk) and emits
+ * source_entity rows for any swim that actually contains length messages;
+ * importing them is idempotent, so re-parsing already-imported swims is
+ * harmless.
+ */
+function runSwimBackfillProcess(arguments_, environment, log) {
+    return new Promise((resolve) => {
+        const child = spawn('uv', arguments_, { ...environment, stdio: ['ignore', 'pipe', 'pipe'] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(chunk.toString('utf8')));
+        child.stderr.on('data', (chunk) => stderr.push(chunk.toString('utf8')));
+        child.on('error', (error) => {
+            log.error('Garmin swim-backfill process could not be started', { error: error.message });
+            resolve({ code: 1, signal: null });
+        });
+        child.on('close', (code, signal) => {
+            const out = stdout.join('').trim();
+            const err = stderr.join('').trim();
+            if (out)
+                log.info(`[garmin swim_backfill] ${out}`);
+            if (err)
+                log.error(`[garmin swim_backfill] ${err}`);
+            resolve({ code, signal });
+        });
+    });
+}
+async function backfillGarminSwimLengths(database, paths, parentRunId, log) {
+    const output = path.join(paths.staging, 'garmin', `${parentRunId}.swim_lengths.jsonl`);
+    await mkdir(path.dirname(output), { recursive: true });
+    // Fresh file for deterministic counting; a stale file would make
+    // line counting ambiguous.
+    try {
+        const { rm } = await import('node:fs/promises');
+        await rm(output, { force: true });
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+    // 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.
+    const activitiesFile = path.join(paths.staging, 'garmin', `${parentRunId}.swim_activities.json`);
+    await writeFile(activitiesFile, JSON.stringify(await database.garminSwimActivitySources()));
+    const arguments_ = [
+        'run',
+        'python',
+        '-m',
+        'python.catence.providers.garmin.swim_backfill',
+        '--data-dir',
+        paths.root,
+        '--output',
+        output,
+        '--activities',
+        activitiesFile,
+    ];
+    const environment = {
+        cwd: packageRoot(),
+        env: { ...(await athleteProviderEnvironment(paths)), UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+    };
+    const outcome = await runSwimBackfillProcess(arguments_, environment, log);
+    if (outcome.code !== 0) {
+        throw new Error(`Garmin swim_backfill exited with code ${outcome.code}${outcome.signal ? ` (${outcome.signal})` : ''}.`);
+    }
+    if (!existsSync(output)) {
+        log.info('Garmin swim backfill produced no output file', { parentRunId });
+        return;
+    }
+    const content = await readFile(output, 'utf8');
+    const lines = content.split('\n').filter((line) => line.trim().length > 0);
+    if (lines.length === 0) {
+        log.info('Garmin swim backfill produced no staged lengths', { parentRunId });
+        return;
+    }
+    const backfillRunId = randomUUID();
+    const imported = await importJsonl(database, backfillRunId, output, log);
+    log.info('Imported swim lengths from automatic backfill', { parentRunId, backfillRunId, staged: lines.length, imported });
+}
 /**
  * Run the Garmin staging worker with streamed stdout/stderr so progress and
  * errors surface in real time instead of buffering until the child exits.
@@ -198,6 +278,16 @@ async function syncProvider(database, paths, provider, options, log) {
                 arguments_.push('--skip-activities');
             if (options.backfill && !options.refreshActivities)
                 arguments_.push('--historical-only');
+            // Data-completeness catch-up: stores synced before lactate-threshold
+            // history capture only hold the latest singleton point. When no
+            // per-day LT observations exist yet, widen the worker's LT window to
+            // the athlete's first activity so the history backfills once; the
+            // condition self-clears after the first successful import.
+            if (!(await database.hasGarminLactateThresholdHistory())) {
+                const earliest = await database.earliestActivityStartDate('garmin');
+                if (earliest)
+                    arguments_.push('--lt-history-from', earliest);
+            }
             let interruptChild = null;
             await runWithInterruptGuard(runId, database, () => interruptChild?.(), guard, async () => {
                 const outcome = await runGarminWorker(runId, arguments_, {
@@ -212,6 +302,17 @@ async function syncProvider(database, paths, provider, options, log) {
                 if (!existsSync(output))
                     throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
                 await importJsonl(database, runId, output, log);
+                if (provider === 'garmin') {
+                    try {
+                        await backfillGarminSwimLengths(database, paths, runId, log);
+                    }
+                    catch (error) {
+                        log.warn('Garmin swim-length backfill after sync failed', {
+                            runId,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
             }
         }
     }

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

@@ -56,6 +56,12 @@ export declare class CatenceDatabase implements WriteDataStore {
     activityNeedsDetailSync(provider: Provider, remoteActivityId: string, summaryHash: string): Promise<boolean>;
     recordActivitySyncState(provider: Provider, remoteActivityId: string, summaryHash: string, runId: string, detailsFetched: boolean): Promise<void>;
     knownActivitySummaryHashes(provider: Provider): Promise<Record<string, string>>;
+    hasGarminLactateThresholdHistory(): Promise<boolean>;
+    earliestActivityStartDate(provider: Provider): Promise<string | null>;
+    garminSwimActivitySources(): Promise<Array<{
+        remote_activity_id: string;
+        started_on: string | null;
+    }>>;
     private latestSourceDate;
     private upsertCursor;
 }