catence 0.2.0-beta.17 → 0.2.0-beta.19

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

package/dist/core/query/repository.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { SYNC_STAGES } from '../../contracts/progress.js';
-import { mergeProgress, readProgressSidecars } from '../../elt/storage/progress-sidecar.js';
+import { mergeProgress, readRunningProgress } from '../../elt/storage/progress-sidecar.js';
 import { sqlString } from './sql.js';
 import { DATASET_CATALOG, getDataset } from './catalog.js';
 export class ReadOnlyRepository {
@@ -165,9 +165,11 @@ export class ReadOnlyRepository {
       LIMIT 10
     `);
         // Merge with sidecar heartbeat files so an active Garmin run stays visible
-        // even while the same process holds the single-writer database lock.
-        const sidecars = await readProgressSidecars(this.paths);
-        return mergeProgress(running.map(toSyncProgressState), recent.map(toSyncProgressState), sidecars);
+        // even while the same process holds the single-writer database lock. The
+        // filtered reader guarantees a terminal or stale heartbeat can never read
+        // as an active run again, so a finished sync cannot block new ones.
+        const runningSidecars = await readRunningProgress(this.paths);
+        return mergeProgress(running.map(toSyncProgressState), recent.map(toSyncProgressState), runningSidecars);
     }
     async coverage() {
         const rows = await this.rows(`

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,55 @@
+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. Model routing (`model`) is refreshed from the live
+ * catalog, while per-model customizations (custom label, `reasoningEffort`,
+ * `variants`) and models that disappeared upstream are kept. The written file
+ * is re-validated with the same strict schema the runtime applies on load,
+ * then replaced atomically.
+ */
+export declare function mergeOpenCodeGoConsoleProfiles(options: {
+    configPath: string;
+    baseUrl?: string;
+    setDefault?: boolean;
+}): Promise<OpenCodeGoMergeResult>;

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

@@ -0,0 +1,237 @@
+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;
+    }
+}
+/** Per-model fields a human may have customized after the initial discovery. */
+function preservedModelFields(previous) {
+    if (typeof previous !== 'object' || previous === null || Array.isArray(previous))
+        return {};
+    const raw = previous;
+    const preserved = {};
+    if (typeof raw.label === 'string' && raw.label.trim())
+        preserved.label = raw.label;
+    if (typeof raw.reasoningEffort === 'string')
+        preserved.reasoningEffort = raw.reasoningEffort;
+    if (raw.variants !== undefined)
+        preserved.variants = raw.variants;
+    return preserved;
+}
+/**
+ * Fetch the live OpenCode Go catalog and merge the two Console profiles into
+ * `configPath`, preserving every other section plus existing console fields
+ * (`limits`, other profiles) and the existing `defaultProfile` unless
+ * `setDefault` is passed. Model routing (`model`) is refreshed from the live
+ * catalog, while per-model customizations (custom label, `reasoningEffort`,
+ * `variants`) and models that disappeared upstream are kept. The written file
+ * is re-validated with the same strict schema the runtime applies on load,
+ * then replaced atomically.
+ */
+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;
+    // Merge per model, not per profile: discovery owns routing and the id list,
+    // but a human's label, reasoningEffort, and variants must survive every
+    // re-discovery. Models that vanished upstream stay configured.
+    const mergedProfiles = {};
+    for (const [profileId, builtProfile] of Object.entries(built.profiles)) {
+        const previousProfile = existingProfiles[profileId];
+        const rawModels = typeof previousProfile === 'object' && previousProfile !== null
+            ? previousProfile.models
+            : undefined;
+        const previousModels = typeof rawModels === 'object' && rawModels !== null && !Array.isArray(rawModels)
+            ? rawModels
+            : {};
+        const models = { ...previousModels };
+        for (const [modelId, entry] of Object.entries(builtProfile.models)) {
+            models[modelId] = {
+                ...preservedModelFields(previousModels[modelId]),
+                label: entry.label,
+                model: entry.model,
+            };
+        }
+        const previousDefaultModel = typeof previousProfile === 'object' && previousProfile !== null
+            ? previousProfile.defaultModel
+            : undefined;
+        mergedProfiles[profileId] = {
+            ...builtProfile,
+            ...(typeof previousDefaultModel === 'string' && previousDefaultModel in models
+                ? { defaultModel: previousDefaultModel }
+                : {}),
+            models,
+        };
+    }
+    const updatedConsole = {
+        ...existingConsole,
+        defaultProfile,
+        profiles: { ...existingProfiles, ...mergedProfiles },
+    };
+    // 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/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

@@ -332,7 +332,7 @@ async function syncProvider(database, paths, provider, options, log) {
         }
         else {
             await database.finishRun(runId);
-            pump.publishFinal(baseProgress(runId, provider, 'completed'));
+            await 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

@@ -56,6 +56,6 @@ export declare class ProgressPump {
     /** 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;
+    publishFinal(state: SyncProgressState): Promise<void>;
     stop(): void;
 }

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

@@ -50,15 +50,33 @@ export async function readProgressSidecars(paths) {
 /** Active runs from sidecars: non-terminal stage and a fresh heartbeat. */
 export async function readRunningProgress(paths, staleAfterMs = PROGRESS_SIDECAR_STALE_MS) {
     const now = Date.now();
+    const directory = path.join(paths.staging, 'garmin');
+    if (!existsSync(directory))
+        return [];
+    const files = (await readdir(directory)).filter((file) => file.endsWith(PROGRESS_SIDECAR_SUFFIX));
     const running = [];
-    for (const state of await readProgressSidecars(paths)) {
-        if (TERMINAL_STAGES.has(state.stage))
+    const prunable = [];
+    for (const file of files) {
+        let state = null;
+        try {
+            state = normalizeProgress(JSON.parse(await readFile(path.join(directory, file), 'utf8')));
+        }
+        catch {
+            // Torn or partial sidecar write; it is not authoritative.
+        }
+        if (!state)
             continue;
         const ageMs = now - Date.parse(state.heartbeatAt);
-        if (!Number.isFinite(ageMs) || ageMs > staleAfterMs)
+        if (TERMINAL_STAGES.has(state.stage) || !Number.isFinite(ageMs) || ageMs > staleAfterMs) {
+            // A terminal heartbeat that survived its own cleanup (a crash between
+            // the final publish and the sidecar removal) must never read as an
+            // active run again, so sweep it instead of leaving it behind forever.
+            prunable.push(file);
             continue;
+        }
         running.push(state);
     }
+    await Promise.all(prunable.map((file) => rm(path.join(directory, file), { force: true }).catch(() => undefined)));
     return running;
 }
 /**
@@ -159,14 +177,16 @@ export class ProgressPump {
         this.setStage('importing');
     }
     /** Write a terminal heartbeat immediately, bypassing the publish throttle. */
-    publishFinal(state) {
+    async publishFinal(state) {
         this.lastHeartbeatAt = Date.now();
         this.lastProgress = state;
         const { database, paths, log } = this.options;
-        void database.heartbeatRun(this.runId, state).catch((error) => {
+        // Both terminal writes complete before the caller removes the sidecar, so
+        // a finished run can never resurrect its own progress file after cleanup.
+        await 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) => {
+        await writeProgressSidecar(paths, this.runId, state).catch((error) => {
             log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
         });
     }

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,6 +1,7 @@
 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, dataStatus, DetachedSyncBusyError, DETACHED_SYNC_PROVIDERS, jsonSafe, loadCatalog, mergeOpenCodeGoConsoleProfiles, openReadOnlyRepository, ReadOnlyDatabaseError, resolveAthlete, resolveCatalogPaths, startDetachedSync, syncProgress, } from '../../runtime/index.js';
 import { createCatenceMcpServer } from '../mcp/server.js';
 const MAX_REQUEST_BYTES = 1_000_000;
 function json(response, statusCode, value) {
@@ -85,6 +86,72 @@ 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 {
+        const status = await dataStatus(paths);
+        const runs = Array.isArray(status.syncRuns) ? status.syncRuns : [];
+        const completed = runs.filter((run) => String(run.status ?? '').startsWith('completed') && completedAtIso(run.completed_at));
+        const providers = {};
+        let lastCompletedAt = null;
+        for (const run of completed) {
+            const completedAt = completedAtIso(run.completed_at);
+            const provider = String(run.provider ?? 'unknown');
+            if (!providers[provider] || providers[provider] < completedAt)
+                providers[provider] = completedAt;
+            if (!lastCompletedAt || lastCompletedAt < completedAt)
+                lastCompletedAt = completedAt;
+        }
+        return { lastCompletedAt, providers, recentRuns: runs.slice(0, 5) };
+    }
+    catch (error) {
+        if (error instanceof ReadOnlyDatabaseError)
+            return null;
+        throw error;
+    }
+}
 async function handleMcpRequest(request, response, paths) {
     if (request.method !== 'POST') {
         methodNotAllowed(response);
@@ -143,6 +210,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)) {
@@ -182,6 +251,69 @@ 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 }, { 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 === '/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);
@@ -238,6 +246,28 @@ export function createCatenceMcpServer(paths = resolveCatalogPaths(), dependenci
         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

@@ -30,6 +30,10 @@ 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, 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';

package/dist/runtime/index.js

@@ -16,6 +16,8 @@ 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, 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/configuration.md

@@ -160,6 +160,12 @@ Precedence for reasoning effort: per-chat dropdown selection > model
 `reasoningEffort` > profile `defaultReasoningEffort` > provider default. See
 [`llm-providers.md`](llm-providers.md#reasoning-effort) for the full behavior.
 
+The Console's **Models** page edits this section in place (enable/disable,
+add custom variants, remove, set defaults). Disabled choices are stored in the
+Console database rather than here; every write preserves all non-console
+sections and is re-validated with the same strict parser before the file is
+replaced.
+
 ### The Console wizard
 
 On the first authenticated chat, the Console wizard (`write_provider_setup`)

package/docs/deployment/local-console.md

@@ -119,6 +119,30 @@ Preflight with:
 catence-console doctor
 ```
 
+### Manage models in the Console
+
+The **Models** page (header button) manages the model list without editing
+`config.json` by hand:
+
+- Enable/disable toggles hide models from the chat's Model dropdown. Disabled
+  choices are stored per machine in the Console database
+  (`console/chat-history.sqlite3`), never in `config.json`, and the Console
+  refuses to disable the only enabled model.
+- **Add a custom model** appends one deployment to an existing profile — id,
+  display label, LiteLLM reference (`openai/…`, `anthropic/…`,
+  `openai/responses/…`), and optional fixed reasoning effort or a custom
+  variants map.
+- **Remove / Make default** edit `config.json`'s console section directly;
+  every other section is preserved, the result is re-validated with the same
+  strict parser used at startup before it replaces the file, and secrets stay
+  forbidden (only environment-variable names are ever stored).
+
+The dashboard header has a **Sync data** button that starts the same detached
+sync as `catence-data sync --provider all` through the authenticated Console
+origin, shows live progress while the run is active, and displays the last
+completed sync afterwards. Each manual sync also refreshes OpenCode Go model
+profiles first; a discovery failure never blocks the data sync.
+
 ## Console serve options
 
 `catence-console serve` accepts:
@@ -172,12 +196,21 @@ script fetches it and merges two ready-made profiles into `config.json`:
 `opencode-go` (chat + responses models, base `…/zen/go/v1`) and
 `opencode-go-messages` (messages models, base `…/zen/go`). Existing profiles,
 limits, and `defaultProfile` are preserved unless `--set-default` is passed.
+Re-discovery refreshes each known model's routing reference but keeps your
+custom label, `reasoningEffort`, and `variants`, and keeps models that have
+disappeared from the live catalog.
 
 ```sh
 # Local (from a checkout)
 npm run discover:opencode-go -- --write ~/.catence/config.json
 ```
 
+Inside the Console's Models page, **Discover OpenCode Go models** runs the
+same merge for the current home without touching athlete data (runtime route
+`POST /api/v1/models/discover`, proxied behind the Console login). Models can
+also be edited in place there — the update action rewrites the `console`
+section atomically and never stores secret values.
+
 Then set the credentials and verify:
 
 ```sh

package/docs/deployment/local-mcp.md

@@ -100,6 +100,11 @@ athletes never leak into each other.
 - Rate limits are tracked **per athlete**: each athlete has its own sliding
   window for server, tool, and resource limits.
 - MCP responses carry an `athlete` field identifying which store served them.
+- `start_detached_sync` is the one explicitly named write tool besides the
+  Strava hydration tools: it spawns a detached `catence-data sync` child for
+  the selected athlete and returns immediately with the run handle and log
+  file. It refuses to start while another sync run is active (`sync_in_progress`);
+  follow the run with `catence_sync_progress`.
 
 ### Adding another athlete
 
@@ -298,6 +303,22 @@ override the host and port when the flags are omitted.
 - `GET /api/v1/dashboard` requires `athleteId`, for example
   `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28` (`endDate`
   is an optional `YYYY-MM-DD`; `days` ranges 1-90 and defaults to 28).
+- `POST /api/v1/sync` starts a detached data sync for one athlete:
+  `{"athleteId": "alex", "provider": "all", "from": "2026-01-01", "refresh": false}`.
+  The spawned child outlives the request, logs to `<home>/logs/`, and the call
+  returns `202` with the run handle immediately; an already-active run is
+  refused with `409 sync_in_progress`. Pass `"refreshModels": true` to also
+  refresh OpenCode Go model profiles first (failure is a non-fatal warning in
+  the response).
+- `GET /api/v1/sync/status?athleteId=alex` reports live progress heartbeats,
+  recent runs, and best-effort last-completion timestamps per provider. It
+  keeps working while a sync holds the write lock (`lastSync` becomes `null`
+  then). Finished runs are never reported as active, so a completed or
+  crashed run can never wedge the busy guard.
+- `POST /api/v1/models/discover` refreshes the OpenCode Go profiles in
+  `<home>/config.json` without starting a data sync:
+  `{"setDefault": false}` (both fields optional). Returns the merged profile
+  ids, per-route counts, and any prefix-guessed routes.
 - Browser origins must be listed with `--allow-origin` (repeatable). The
   packaged Console instead proxies the dashboard through its authenticated
   same-origin route.

package/docs/llm-providers.md

@@ -196,7 +196,18 @@ different API shapes:
 
 The script warns on stderr and skips any model that does not fit one of these
 families. Rerun it to refresh the model lists; existing profiles, limits, and
-`defaultProfile` are preserved unless `--set-default` is passed.
+`defaultProfile` are preserved unless `--set-default` is passed. Re-running
+never discards your own tweaks: per-model custom labels, `reasoningEffort`
+pins, and `variants` maps survive every refresh, and models that have dropped
+out of the live catalog stay configured.
+
+You do not have to run the script manually: the Console dashboard's **Sync
+data** button (and `POST /api/v1/sync` with `"refreshModels": true`) refreshes
+these profiles from the live catalog before starting a data sync, and the
+Models page's **Discover OpenCode Go models** button (or
+`POST /api/v1/models/discover`) refreshes them without syncing anything.
+Discovery failures — offline machine, catalog unreachable — are reported as a
+warning and never block or fail the sync itself.
 
 ```sh
 export OPENCODE_GO_API_KEY='…'                      # any non-empty value satisfies the key check

package/package.json

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

package/scripts/discover-opencode-go.mjs

@@ -1,12 +1,11 @@
+#!/usr/bin/env node
 // Discover OpenCode Go models and emit Catence Console profiles for them.
 //
-// OpenCode Go serves its catalog through three APIs: most models speak the
-// OpenAI Chat Completions API, Grok and GPT-5.6 Luna speak the OpenAI
-// Responses API, and MiniMax and Qwen speak the Anthropic Messages API. The
+// Thin CLI wrapper around the runtime's src/core/runtime/opencode-go.ts
+// module, which owns the "live discovery + trusted metadata" logic: the
 // public `GET /models` endpoint returns only model ids, not which API each
-// model needs, so routing comes from the trusted table below and is intersected
-// with the live list (the same "live discovery + trusted metadata" approach
-// OpenClaw uses).
+// model needs, so routing comes from a trusted table intersected with the
+// live list (the same approach OpenClaw uses).
 //
 // Usage:
 //   node scripts/discover-opencode-go.mjs [--base-url <url>] [--write <config.json>] [--set-default]
@@ -17,62 +16,19 @@
 //   --set-default      With --write, set console.defaultProfile to opencode-go even when one already exists.
 
 import process from 'node:process';
-import { readFile, writeFile } from 'node:fs/promises';
 
-const DEFAULT_BASE_URL = 'https://opencode.ai/zen/go/v1';
-const API_KEY_ENV = 'OPENCODE_GO_API_KEY';
-const API_BASE_ENV = 'OPENCODE_GO_API_BASE';
-const MESSAGES_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'],
-]);
-
-function classify(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 };
+let runtime;
+try {
+  runtime = await import(new URL('../dist/core/runtime/opencode-go.js', import.meta.url).href);
+} catch (error) {
+  if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+  process.stderr.write(
+    'The discovery module is not built yet. Run `npm run build` in the catence checkout first, or use an installed `catence` package.\n',
+  );
+  process.exit(1);
 }
 
-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(' ');
-}
+const { OPENCODE_GO_API_BASE_ENV, OPENCODE_GO_API_KEY_ENV, OPENCODE_GO_MESSAGES_API_BASE_ENV } = runtime;
 
 function usage() {
   process.stderr.write(
@@ -82,7 +38,7 @@ function usage() {
 
 async function main() {
   const args = process.argv.slice(2);
-  let baseUrl = DEFAULT_BASE_URL;
+  let baseUrl = runtime.OPENCODE_GO_DEFAULT_BASE_URL;
   let writePath = null;
   let setDefault = false;
   for (let i = 0; i < args.length; i += 1) {
@@ -108,100 +64,36 @@ async function main() {
   if (!baseUrl.endsWith('/v1')) {
     process.stderr.write(`Warning: --base-url ${baseUrl} does not end in /v1; chat and responses URLs may be wrong.\n`);
   }
-  const modelsUrl = `${baseUrl.replace(/\/$/, '')}/models`;
   const messagesBase = baseUrl.replace(/\/v1\/?$/, '');
 
-  let response;
-  try {
-    response = await fetch(modelsUrl, { headers: { accept: 'application/json' } });
-  } catch (error) {
-    throw new Error(`Could not reach ${modelsUrl}: ${error.message}`);
-  }
-  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' && id);
-
-  const groups = { chat: [], responses: [], messages: [] };
-  const guessed = [];
-  for (const id of ids) {
-    const { route, guessed: wasGuessed } = classify(id);
-    if (!(route in groups)) continue;
-    groups[route].push(id);
-    if (wasGuessed) guessed.push(`${id} -> ${route}`);
-  }
-  for (const route of Object.keys(groups)) groups[route].sort();
-
-  const chatProfileModels = {};
-  for (const id of groups.chat) {
-    chatProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'chat') };
-  }
-  for (const id of groups.responses) {
-    chatProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'responses') };
-  }
-  const messagesProfileModels = {};
-  for (const id of groups.messages) {
-    messagesProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'messages') };
-  }
-
-  const chatDefault = groups.chat[0] ?? groups.responses[0];
-  const profiles = {};
-  profiles['opencode-go'] = {
-    label: 'OpenCode Go',
-    ...(chatDefault ? { defaultModel: chatDefault } : {}),
-    models: chatProfileModels,
-    apiKeyEnv: API_KEY_ENV,
-    apiBaseEnv: API_BASE_ENV,
-  };
-  if (messagesProfileModels && groups.messages.length) {
-    profiles['opencode-go-messages'] = {
-      label: 'OpenCode Go (Anthropic)',
-      defaultModel: groups.messages[0],
-      models: messagesProfileModels,
-      apiKeyEnv: API_KEY_ENV,
-      apiBaseEnv: MESSAGES_BASE_ENV,
-    };
-  }
-
-  const consoleSection = { defaultProfile: 'opencode-go', profiles };
-
-  if (guessed.length) {
-    process.stderr.write('Routed by prefix heuristic (verify before use):\n');
-    for (const line of guessed) process.stderr.write(`  ${line}\n`);
-  }
-  process.stderr.write(
-    `Discovered ${ids.length} models (${groups.chat.length} chat, ${groups.responses.length} responses, ${groups.messages.length} messages).\n`,
-  );
-
   if (writePath) {
-    let root = {};
-    try {
-      root = JSON.parse(await readFile(writePath, 'utf8'));
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw new Error(`Could not read ${writePath}: ${error.message}`);
+    const result = await runtime.mergeOpenCodeGoConsoleProfiles({ configPath: writePath, baseUrl, setDefault });
+    if (result.guessedRoutes.length) {
+      process.stderr.write('Routed by prefix heuristic (verify before use):\n');
+      for (const line of result.guessedRoutes) process.stderr.write(`  ${line}\n`);
     }
-    if (typeof root !== 'object' || root === null || Array.isArray(root)) {
-      throw new Error(`${writePath} must contain a JSON object.`);
-    }
-    const existingConsole = typeof root.console === 'object' && root.console !== null ? root.console : {};
-    const mergedProfiles = { ...(existingConsole.profiles ?? {}), ...profiles };
-    const defaultProfile =
-      existingConsole.defaultProfile && !setDefault ? existingConsole.defaultProfile : 'opencode-go';
-    root.console = { ...existingConsole, defaultProfile, profiles: mergedProfiles };
-    await writeFile(writePath, `${JSON.stringify(root, null, 2)}\n`);
-    process.stderr.write(`Merged profiles into ${writePath} (defaultProfile: ${defaultProfile}).\n`);
+    process.stderr.write(
+      `Merged ${result.counts.chat} chat, ${result.counts.responses} responses, and ${result.counts.messages} messages models into ${result.configPath}` +
+        ` as ${result.mergedProfileIds.join(' + ')} (defaultProfile: ${result.defaultProfile}).\n`,
+    );
     return;
   }
 
+  const ids = await runtime.fetchOpenCodeGoModelIds(baseUrl);
+  const built = runtime.buildOpenCodeGoConsoleProfiles(ids, baseUrl);
+  if (built.guessedRoutes.length) {
+    process.stderr.write('Routed by prefix heuristic (verify before use):\n');
+    for (const line of built.guessedRoutes) process.stderr.write(`  ${line}\n`);
+  }
   process.stderr.write(
-    `Export the key and base URLs, then add the JSON below under "console" in config.json:\n` +
-      `  export ${API_KEY_ENV}='sk-…'\n` +
-      `  export ${API_BASE_ENV}='${baseUrl}'\n` +
-      `  export ${MESSAGES_BASE_ENV}='${messagesBase}'\n` +
+    `Discovered ${ids.length} models (${built.counts.chat} chat, ${built.counts.responses} responses, ${built.counts.messages} messages).\n` +
+      `Export the key and base URLs, then add the JSON below under "console" in config.json:\n` +
+      `  export ${OPENCODE_GO_API_KEY_ENV}='sk-…'\n` +
+      `  export ${OPENCODE_GO_API_BASE_ENV}='${baseUrl}'\n` +
+      `  export ${OPENCODE_GO_MESSAGES_API_BASE_ENV}='${messagesBase}'\n` +
       `(or rerun with --write ~/.catence/config.json to merge into an existing config.)\n`,
   );
-  process.stdout.write(`${JSON.stringify(consoleSection, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify({ defaultProfile: built.defaultProfile, profiles: built.profiles }, null, 2)}\n`);
 }
 
 await main().catch((error) => {