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

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.
@@ -24,12 +24,14 @@ Catence helps explore recovery, training load, trends, activity detail, swimming
 
 Install Catence and create the first athlete. The default catalog home is `~/.catence`; set `CATENCE_HOME` or pass `--home` to use a different location.
 
+Every `catence-data` command requires `--athlete <id>`; there is no default athlete. Pair it with `--home <dir>` to select the catalog when not using the default home.
+
 ```sh
-npm install --global catence@0.2.0
+npm install --global catence@beta          # or catence@latest for stable
 catence-data setup --athlete alex --label "Alex"
 ```
 
-Store each provider value through stdin so it does not enter shell history. Values are written to the selected athlete’s owner-only local secret file.
+Store each provider value through stdin so it does not enter shell history. Values are written to the selected athlete's owner-only local secret file.
 
 ```sh
 printf %s 'alex@example.com' | catence-data --athlete alex secret set --provider garmin --field email --value-stdin
@@ -63,49 +65,42 @@ catence-data --athlete sam sync --provider garmin
 catence-data athlete list
 ```
 
-The catalog layout is deliberately simple:
-
-```text
-~/.catence/
-  catalog.json
-  config.json                     # shared Console configuration; no secrets
-  console/chat-history.sqlite3
-  athletes/
-    alex/                         # isolated DuckDB, raw data, and tokens
-      secrets/providers.json      # mode 0600
-    sam/
-      ...
-```
-
-Garmin, Intervals, and Strava client credentials are isolated per athlete. Strava OAuth tokens remain in that athlete’s own store. The old 0.1 single-store directory cannot be migrated safely: create a fresh home and re-sync each athlete.
+Garmin, Intervals, and Strava client credentials are isolated per athlete. Strava OAuth tokens remain in that athlete's own store. The old 0.1 single-store directory cannot be migrated safely: create a fresh home and re-sync each athlete.
 
 ### Common operations
 
 ```sh
-# Incremental or explicit data work for one athlete
 catence-data --athlete alex status
 catence-data --athlete alex sync --provider intervals
 catence-data --athlete alex sync --provider garmin --from 2025-07-29
 catence-data --athlete alex backfill --provider garmin --from 2020-01-01 --refresh
 catence-data --athlete alex retry --run <run-id>
-
-# Strava OAuth uses clientId and clientSecret previously stored for this athlete
+catence-data --athlete alex progress --watch
 catence-data --athlete alex auth strava --callback
 catence-data --athlete alex disconnect strava
-
-# Choose a non-default catalog location
-catence-data --home /srv/catence setup --athlete alex --label "Alex"
-catence --home /srv/catence
+catence-data update --check
+catence-data update
 ```
 
-Register `http://127.0.0.1:8765/strava/callback` with the Strava application for the callback flow. The manual `auth strava --code <authorization-code>` flow remains available for headless environments.
+## Documentation
+
+| Document | Covers |
+| --- | --- |
+| [Deployment: local MCP](docs/deployment/local-mcp.md) | Install, catalog, secrets, sync, background progress, stdio/HTTP MCP, demo, common operations |
+| [Deployment: local Console](docs/deployment/local-console.md) | Local web chat setup, model config, doctor, updates, troubleshooting |
+| [Deployment: Docker](docs/deployment/docker.md) | One-container stack: deploy script, `.env`, sync.sh, MCP exposure (SSH/Tailscale), Cloudflare Tunnel |
+| [Configuration](docs/configuration.md) | Complete `config.json` schema: rate limits, Strava budget, Console profiles, environment variables |
+| [LLM providers](docs/llm-providers.md) | Model providers (OpenAI, Anthropic, OpenAI-compatible/Azure, Opencode Go/Zen), reasoning effort |
+| [Architecture](docs/architecture.md) | Design rationale, layers, data flow, serving |
+| [MCP activity retrieval](docs/mcp-activity-retrieval.md) | Implementation contract for answering questions, current tools, planned endpoints |
+| [Distribution](docs/distribution.md) | Release artifacts: npm, PyPI, APM, MCPB |
 
 ## Safe demo and Glama
 
 Run a clearly marked generated dataset without provider accounts:
 
 ```sh
-npx --yes catence@0.2.0 demo
+npx --yes catence@beta demo
 ```
 
 It creates or reuses `~/.catence-demo` with one `demo` athlete. The generated data has explicit caveats in every tool response and never contains personal measurements. The Glama registry entry uses this command for **Try in Browser**, so the hosted sandbox has no access to local credentials or personal data.
@@ -137,58 +132,11 @@ Optional local Streamable HTTP MCP and dashboard APIs:
 catence serve --host 127.0.0.1 --port 8787
 ```
 
-`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route.
-
-## Catence Console
-
-The Console is a local web chat that starts a matching Catence HTTP server on loopback. It uses Chainlit password login and fails closed unless all three authentication variables are supplied.
-
-```sh
-export CATENCE_HOME="$HOME/.catence"
-export CATENCE_CONSOLE_USERNAME='coach'
-export CATENCE_CONSOLE_PASSWORD_HASH="$(catence-console auth hash-password)"
-export CHAINLIT_AUTH_SECRET="$(openssl rand -hex 32)"
-export OPENAI_API_KEY='…'
-
-uvx catence-console@0.2.0 serve
-```
-
-On the first authenticated visit, the Console wizard asks for an OpenAI-compatible, OpenAI, or Anthropic model and writes only the non-secret model configuration to `~/.catence/config.json`. The `openai-compatible` option covers Azure and Opencode; see [`docs/llm-providers.md`](docs/llm-providers.md). Model-provider keys remain process environment variables. The Console settings include an athlete selector; the server overwrites model-supplied athlete scope with that selected value on every personal-data call.
-
-To preflight the Console and a running runtime:
-
-```sh
-uvx catence-console@0.2.0 doctor --home "$HOME/.catence" --mcp-url http://127.0.0.1:8787/mcp
-```
-
-Console chats and saved tool context are local at `~/.catence/console/chat-history.sqlite3`.
-
-### Docker and Cloudflare Tunnel
-
-The Console image contains the Node runtime, Catence, and Console. Its MCP server remains loopback-only inside the container; only the Console port is exposed.
-
-```sh
-docker build -f console/Dockerfile -t catence-console .
-docker run --rm -p 127.0.0.1:8000:8000 -v catence-data:/data \
-  -e CATENCE_CONSOLE_USERNAME='coach' \
-  -e CATENCE_CONSOLE_PASSWORD_HASH='replace-with-bcrypt-hash' \
-  -e CHAINLIT_AUTH_SECRET='replace-with-a-long-random-secret' \
-  -e OPENAI_API_KEY='…' \
-  catence-console
-```
-
-Initialize the mounted volume before its first production sync, for example:
-
-```sh
-docker run --rm -it -v catence-data:/data --entrypoint catence-data catence-console \
-  setup --athlete alex --label "Alex"
-```
-
-Use the same `--entrypoint catence-data` pattern for `secret set` and `sync`. Route a Cloudflare Tunnel to `http://127.0.0.1:8000`; do not run a tunnel client in this image. Use HTTPS at the tunnel and retain the Console login—the dashboard is fetched through the authenticated Console origin rather than directly from port 8787.
+`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route. The MCP server has no authentication of its own — keep it on loopback or restrict it at the network layer (see [Docker MCP exposure](docs/deployment/docker.md#connecting-to-the-docker-based-mcp-from-outside) for the remote-access patterns).
 
 ## Configuration
 
-[`config.example.json`](config.example.json) documents rate limits, Strava budgets, and Console model profiles. It intentionally contains environment-variable names rather than credential values. Keep per-athlete provider values in `catence-data secret set`, not in `.env` or `config.json`.
+[`config.example.json`](config.example.json) documents rate limits, Strava budgets, and Console model profiles. It intentionally contains environment-variable names rather than credential values. Keep per-athlete provider values in `catence-data secret set`, not in `.env` or `config.json`. The full `config.json` schema — including per-model reasoning effort — is documented in [`docs/configuration.md`](docs/configuration.md) and [`docs/llm-providers.md`](docs/llm-providers.md).
 
 For source development:
 
@@ -201,9 +149,7 @@ UV_CACHE_DIR=$PWD/.cache/uv uv run --project console --group dev python -m pytes
 
 ## Beta releases
 
-Registry betas use distinct npm and Python prerelease formats: for example,
-`catence@0.2.0-beta.1` pairs with `catence-console==0.2.0b1` and
-`catence-chainlit==0.2.0b1`. The protected `beta` branch verifies candidates;
+Registry betas use distinct npm, console, and UI-runtime prerelease formats. Each `catence@0.2.0-beta.N` npm release maps to a `catence-console==0.2.0bN` wheel, but the console depends on a range of `catence-chainlit` (the UI runtime), so the `catence-chainlit` version does not need to match the npm or console version. For example, `catence@0.2.0-beta.1` pairs with `catence-console==0.2.0b1` and can use any compatible `catence-chainlit` (such as `0.2.0b1`). The protected `beta` branch verifies candidates;
 a `v0.2.0-beta.1` tag publishes to npm's `beta` channel and creates a GitHub
 prerelease. Follow [the beta release checklist](release/beta-checklist.md) to
 publish the UI wheel first, deploy the registry artifacts with Compose, and
@@ -212,6 +158,6 @@ data.
 
 ## Data and caveats
 
-Garmin is the primary source for activity and wellness data; Intervals.icu supplements training analysis; Strava is used for targeted segments, efforts, and gear. Missing fields mean a provider did not supply a value. The source credentials and source APIs determine the data available. Catence does not use the official Garmin API; Garmin sync relies on the selected athlete’s email/password credentials.
+Garmin is the primary source for activity and wellness data; Intervals.icu supplements training analysis; Strava is used for targeted segments, efforts, and gear. Missing fields mean a provider did not supply a value. The source credentials and source APIs determine the data available. Catence does not use the official Garmin API; Garmin sync relies on the selected athlete's email/password credentials.
 
-See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.
+See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.

package/config.example.json

@@ -44,6 +44,31 @@
         "label": "Anthropic",
         "model": "anthropic/claude-sonnet-4-5",
         "apiKeyEnv": "ANTHROPIC_API_KEY"
+      },
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": {
+            "label": "DeepSeek V4 Flash Free",
+            "model": "openai/deepseek-v4-flash-free",
+            "variants": { "High": "high", "Max": "max" }
+          },
+          "nemotron-3-ultra-free": { "label": "Nemotron 3 Ultra Free", "model": "openai/nemotron-3-ultra-free" },
+          "big-pickle": { "label": "Big Pickle", "model": "openai/big-pickle" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      },
+      "opencode-zen-responses": {
+        "label": "OpenCode Zen (Responses)",
+        "defaultModel": "gpt-5.6-luna",
+        "models": {
+          "gpt-5.6-luna": { "label": "GPT 5.6 Luna", "model": "openai/responses/gpt-5.6-luna" },
+          "gpt-5.6-terra": { "label": "GPT 5.6 Terra", "model": "openai/responses/gpt-5.6-terra" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_RESPONSES_API_BASE"
       }
     }
   }

package/dist/contracts/index.d.ts

@@ -1,3 +1,4 @@
+export * from './progress.js';
 export * from './runtime.js';
 export * from './release.js';
 export * from './staging.js';

package/dist/contracts/index.js

@@ -1,3 +1,4 @@
+export * from './progress.js';
 export * from './runtime.js';
 export * from './release.js';
 export * from './staging.js';

package/dist/contracts/progress.d.ts

@@ -0,0 +1,23 @@
+export declare const STALE_RUN_TIMEOUT_MS: number;
+export declare const SYNC_STAGES: readonly ["starting", "login", "singletons", "daily", "range", "ftp_history", "max_metrics", "hrv_history", "scores", "activities", "collections", "intervals", "importing", "completed", "interrupted", "failed", "timed_out"];
+export type SyncStage = (typeof SYNC_STAGES)[number];
+export interface SyncProgressState {
+    runId: string;
+    provider: string;
+    stage: SyncStage;
+    currentStep: string | null;
+    completedUnits: number;
+    totalUnits: number | null;
+    percentComplete: number;
+    elapsedSeconds: number;
+    estimatedRemainingSeconds: number | null;
+    heartbeatAt: string;
+}
+export interface SyncProgressSnapshot {
+    running: SyncProgressState[];
+    recent: SyncProgressState[];
+}
+export interface InterruptedRuns {
+    runIds: string[];
+}
+export declare function normalizeProgress(value: unknown): SyncProgressState | null;

package/dist/contracts/progress.js

@@ -0,0 +1,49 @@
+export const STALE_RUN_TIMEOUT_MS = 15 * 60 * 1000;
+export const SYNC_STAGES = [
+    'starting',
+    'login',
+    'singletons',
+    'daily',
+    'range',
+    'ftp_history',
+    'max_metrics',
+    'hrv_history',
+    'scores',
+    'activities',
+    'collections',
+    'intervals',
+    'importing',
+    'completed',
+    'interrupted',
+    'failed',
+    'timed_out',
+];
+export function normalizeProgress(value) {
+    if (typeof value !== 'object' || value === null) {
+        return null;
+    }
+    const record = value;
+    const runId = typeof record.runId === 'string' ? record.runId : '';
+    const provider = typeof record.provider === 'string' ? record.provider : '';
+    if (!runId || !provider) {
+        return null;
+    }
+    const stage = SYNC_STAGES.includes(record.stage)
+        ? record.stage
+        : 'starting';
+    const numberOr = (value, fallback) => typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    const roundOrNull = (value) => typeof value === 'number' && Number.isFinite(value) ? Math.max(0, Math.round(value)) : null;
+    return {
+        runId,
+        provider,
+        stage,
+        currentStep: typeof record.currentStep === 'string' ? record.currentStep : null,
+        completedUnits: Math.max(0, Math.round(numberOr(record.completedUnits, 0))),
+        totalUnits: roundOrNull(record.totalUnits),
+        percentComplete: Math.min(100, Math.max(0, numberOr(record.percentComplete, 0))),
+        elapsedSeconds: Math.max(0, numberOr(record.elapsedSeconds, 0)),
+        estimatedRemainingSeconds: roundOrNull(record.estimatedRemainingSeconds),
+        heartbeatAt: typeof record.heartbeatAt === 'string' ? record.heartbeatAt : new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=progress.js.map

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

package/dist/core/logging.d.ts

@@ -0,0 +1,16 @@
+import type { CatencePaths } from '../contracts/runtime.js';
+export type SyncLogger = {
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+    debug: (message: string, context?: Record<string, unknown>) => void;
+};
+/**
+ * Resolve the sync log file path.
+ *
+ * `CATENCE_LOG` may be an absolute path or a path relative to the catalog home.
+ * When unset (the default), logs go to stderr only so the console stays clean
+ * and stdout remains machine-readable for callers like sync.sh.
+ */
+export declare function resolveLogFile(paths: CatencePaths, environment?: NodeJS.ProcessEnv): string | null;
+export declare function createSyncLogger(paths: CatencePaths, environment?: NodeJS.ProcessEnv): SyncLogger;

package/dist/core/logging.js

@@ -0,0 +1,68 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+const LEVEL_WEIGHT = { debug: 10, info: 20, warn: 30, error: 40 };
+function configuredLevel(environment = process.env) {
+    const raw = (environment.CATENCE_LOG_LEVEL ?? 'info').toLowerCase();
+    if (raw === 'debug')
+        return LEVEL_WEIGHT.debug;
+    if (raw === 'warn')
+        return LEVEL_WEIGHT.warn;
+    if (raw === 'error')
+        return LEVEL_WEIGHT.error;
+    return LEVEL_WEIGHT.info;
+}
+/**
+ * Resolve the sync log file path.
+ *
+ * `CATENCE_LOG` may be an absolute path or a path relative to the catalog home.
+ * When unset (the default), logs go to stderr only so the console stays clean
+ * and stdout remains machine-readable for callers like sync.sh.
+ */
+export function resolveLogFile(paths, environment = process.env) {
+    const configured = environment.CATENCE_LOG;
+    if (!configured)
+        return null;
+    return path.isAbsolute(configured) ? configured : path.join(paths.root, configured);
+}
+export function createSyncLogger(paths, environment = process.env) {
+    const threshold = configuredLevel(environment);
+    const logFile = resolveLogFile(paths, environment);
+    const write = (level, message, context) => {
+        if (LEVEL_WEIGHT[level] < threshold)
+            return;
+        const line = formatLogLine(level, message, context);
+        process.stderr.write(`${line}\n`);
+        if (logFile) {
+            // Fire-and-forget: never block a sync run on log persistence.
+            appendLogLine(logFile, `${line}\n`).catch(() => { });
+        }
+    };
+    return {
+        info: (message, context) => write('info', message, context),
+        warn: (message, context) => write('warn', message, context),
+        error: (message, context) => write('error', message, context),
+        debug: (message, context) => write('debug', message, context),
+    };
+}
+function formatLogLine(level, message, context) {
+    const timestamp = new Date().toISOString();
+    const tag = level.toUpperCase().padEnd(5);
+    let line = `[${timestamp}] [${tag}] ${message}`;
+    if (context && Object.keys(context).length > 0) {
+        line += ` ${serializeContext(context)}`;
+    }
+    return line;
+}
+function serializeContext(context) {
+    try {
+        return JSON.stringify(context);
+    }
+    catch {
+        return '';
+    }
+}
+let appendLogLine = async (file, line) => {
+    await mkdir(path.dirname(file), { recursive: true });
+    await appendFile(file, line, 'utf8');
+};
+//# sourceMappingURL=logging.js.map

package/dist/core/query/repository.d.ts

@@ -1,4 +1,5 @@
 import type { CatencePaths } from '../../contracts/runtime.js';
+import { type SyncProgressSnapshot } from '../../contracts/progress.js';
 import type { QueryValues, ReadDataStore } from '../../contracts/storage.js';
 import { type DatasetDefinition } from './catalog.js';
 export declare class ReadOnlyRepository {
@@ -10,6 +11,7 @@ export declare class ReadOnlyRepository {
     datasetRelation(datasetName: string): Promise<string>;
     activitySampleRelation(): Promise<string>;
     status(): Promise<Record<string, unknown>>;
+    progress(): Promise<SyncProgressSnapshot>;
     coverage(): Promise<Record<string, unknown>>;
     activity(activityId: string): Promise<Record<string, unknown> | null>;
     summary(startDate: string, endDate: string): Promise<Record<string, unknown>>;

package/dist/core/query/repository.js

@@ -1,5 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { SYNC_STAGES } from '../../contracts/progress.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 {
@@ -137,6 +139,38 @@ export class ReadOnlyRepository {
             incrementalCursors: cursors,
         };
     }
+    async progress() {
+        // Same sequential-read discipline as status(): the shared native
+        // connection must not run these small reads concurrently.
+        const running = await this.rows(`
+      SELECT runs.run_id, runs.provider, coalesce(progress.stage, 'starting') AS stage,
+        progress.current_step,
+        coalesce(progress.completed_units, 0) AS completed_units,
+        progress.total_units,
+        coalesce(progress.percent, 0) AS percent,
+        coalesce(progress.elapsed_seconds, 0) AS elapsed_seconds,
+        progress.estimated_remaining_seconds,
+        cast(coalesce(progress.heartbeat_at, runs.started_at) AS VARCHAR) AS heartbeat_at
+      FROM sync_runs AS runs
+      LEFT JOIN sync_run_progress AS progress USING (run_id)
+      WHERE runs.status = 'running'
+      ORDER BY runs.started_at DESC
+    `);
+        const recent = await this.rows(`
+      SELECT run_id, provider, stage, current_step, completed_units, total_units, percent,
+        elapsed_seconds, estimated_remaining_seconds,
+        cast(heartbeat_at AS VARCHAR) AS heartbeat_at
+      FROM sync_run_progress
+      ORDER BY heartbeat_at DESC
+      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. 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(`
       SELECT 'activities' AS dataset, min(cast(started_at_utc AS DATE)) AS start_date, max(cast(started_at_utc AS DATE)) AS end_date, count(*)::INTEGER AS row_count FROM activities
@@ -166,6 +200,20 @@ export class ReadOnlyRepository {
         return Object.values(DATASET_CATALOG);
     }
 }
+function toSyncProgressState(row) {
+    return {
+        runId: row.run_id,
+        provider: row.provider,
+        stage: SYNC_STAGES.includes(row.stage) ? row.stage : 'starting',
+        currentStep: row.current_step,
+        completedUnits: Math.max(0, Number(row.completed_units) || 0),
+        totalUnits: row.total_units === null || row.total_units === undefined ? null : Math.max(0, Number(row.total_units) || 0),
+        percentComplete: Math.min(100, Math.max(0, Number(row.percent) || 0)),
+        elapsedSeconds: Math.max(0, Number(row.elapsed_seconds) || 0),
+        estimatedRemainingSeconds: row.estimated_remaining_seconds === null || row.estimated_remaining_seconds === undefined ? null : Math.max(0, Number(row.estimated_remaining_seconds) || 0),
+        heartbeatAt: row.heartbeat_at,
+    };
+}
 /** Converts DuckDB's Date/BigInt values into MCP-safe JSON values. */
 export function jsonSafe(value) {
     if (typeof value === 'bigint')

package/dist/core/runtime/catalog.js

@@ -40,9 +40,8 @@ export function athleteStorePaths(catalogPaths, athleteId) {
 function legacyStoreMessage(paths) {
     return `Catence 0.2 uses a catalog at ${paths.root}. The existing directory looks like a 0.1 data store and cannot be migrated automatically. Create a fresh catalog and re-sync each athlete.`;
 }
-async function hasEntries(directory) {
-    return (await readdir(directory).catch((error) => error.code === 'ENOENT' ? [] : Promise.reject(error))).length > 0;
-}
+/** Home-directory entries the Console creates on its own and must not block catalog initialization. */
+const CONSOLE_ARTIFACTS = new Set(['config.json', 'console', '.files', '.chainlit', 'public']);
 export async function loadCatalog(paths = resolveCatalogPaths()) {
     const contents = await readFile(paths.catalog, 'utf8').catch((error) => {
         if (error.code !== 'ENOENT')
@@ -68,10 +67,21 @@ async function writeCatalog(paths, catalog) {
 export async function initializeCatalog(paths = resolveCatalogPaths(), athlete) {
     if (existsSync(paths.catalog))
         return loadCatalog(paths);
-    if (await hasEntries(paths.root)) {
-        if (existsSync(path.join(paths.root, 'catence.duckdb')))
-            throw new Error(legacyStoreMessage(paths));
-        throw new Error(`Refusing to initialize ${paths.root}: choose an empty --home directory or remove its unrelated contents.`);
+    let entries;
+    try {
+        entries = await readdir(paths.root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            entries = [];
+        else
+            throw error;
+    }
+    if (entries.includes('catence.duckdb'))
+        throw new Error(legacyStoreMessage(paths));
+    const unrelated = entries.filter((entry) => !CONSOLE_ARTIFACTS.has(entry));
+    if (unrelated.length > 0) {
+        throw new Error(`Refusing to initialize ${paths.root}: found ${unrelated.join(', ')}. Remove these or choose an empty --home directory.`);
     }
     const id = athleteIdSchema.parse(athlete.id);
     const record = { id, label: athlete.label.trim(), createdAt: new Date().toISOString() };

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,58 @@
+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[];
+    /** Model ids removed from the managed profiles because they left the live catalog. */
+    prunedModelIds?: 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, per-model customizations (custom label, `reasoningEffort`,
+ * `variants`) survive for models still in the catalog, and models that
+ * disappeared upstream are pruned so the Console never offers stale routes.
+ * 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>;