catence 0.2.0-beta.9 → 0.2.0

package/dist/elt/storage/migrations.js

@@ -828,5 +828,149 @@ const swimFactsAndQualityMigration = {
     UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
   `,
 };
-export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration];
+const syncRunProgressMigration = {
+    version: 14,
+    name: 'sync_run_progress_heartbeats',
+    sql: `
+    -- Live progress heartbeats for in-flight sync runs. Written by the Node
+    -- side from progress records streamed by provider workers; read-only
+    -- surfaces (status, progress CLI, MCP) join against sync_runs.
+    CREATE TABLE IF NOT EXISTS sync_run_progress (
+      run_id VARCHAR PRIMARY KEY,
+      provider VARCHAR NOT NULL,
+      stage VARCHAR NOT NULL,
+      current_step VARCHAR,
+      completed_units INTEGER NOT NULL DEFAULT 0,
+      total_units INTEGER,
+      percent DOUBLE NOT NULL DEFAULT 0,
+      elapsed_seconds DOUBLE NOT NULL DEFAULT 0,
+      estimated_remaining_seconds DOUBLE,
+      heartbeat_at TIMESTAMPTZ NOT NULL,
+      detail_json JSON NOT NULL DEFAULT '{}'
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+const canonicalTrainingDerivedAvgPowerMigration = {
+    version: 15,
+    name: 'canonical_training_derived_avg_power_w',
+    sql: `
+    -- A2: Stop "NULL avg_power => no power" inference without rewriting provenance.
+    -- activity_summaries.avg_power is sparse (NULL for many 2024 running
+    -- activities) while authoritative Garmin FIT-derived power is present as
+    -- per-duration rows in activity_power_bests (exposed as power_best_facts).
+    -- Overwriting the summary value would conflate two layers and break the
+    -- provenance contract (summary vs FIT-derived). Instead, extend the
+    -- canonical view with a derived column that aggregates the FIT signal:
+    -- derived_avg_power_w is the per-activity mean of best_power_w across
+    -- all stored durations. Callers should prefer
+    -- coalesce(avg_power, derived_avg_power_w) or use power_coverage_report /
+    -- read_series on activity_samples for the full signal. NULL remains NULL
+    -- when no FIT bests exist for that activity, making absence explicit.
+    -- Idempotent via CREATE OR REPLACE VIEW; no table mutation.
+    -- Older test fixtures (v9) created activity_summaries with only a subset
+    -- of columns; ensure the full canonical set exists so this view's
+    -- intervals_analysis (which unconditionally references training_load etc.)
+    -- does not throw Binder Error on upgrade.
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS elevation_gain_m DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS calories DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS max_hr DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS avg_power DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS weighted_power DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS avg_cadence DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS training_load DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS rpe DOUBLE;
+    ALTER TABLE activity_summaries ADD COLUMN IF NOT EXISTS feel DOUBLE;
+    CREATE OR REPLACE VIEW canonical_activity_training AS
+    WITH ranked AS (
+      SELECT a.*, source.activity_source_id, source.provider, source.remote_activity_id, source.raw_object_hash,
+        summary.*, row_number() OVER (
+          PARTITION BY a.activity_id
+          ORDER BY CASE source.provider WHEN 'garmin' THEN 0 WHEN 'intervals' THEN 1 ELSE 2 END
+        ) AS source_rank
+      FROM activities a
+      JOIN activity_sources source USING (activity_id)
+      LEFT JOIN activity_summaries summary USING (activity_source_id)
+    ), intervals_analysis AS (
+      SELECT source.activity_id,
+        max(summary.training_load) AS intervals_training_load,
+        max(summary.rpe) AS intervals_rpe,
+        max(summary.feel) AS intervals_feel,
+        max(summary.weighted_power) AS intervals_weighted_power
+      FROM activity_sources source
+      JOIN activity_summaries summary USING (activity_source_id)
+      WHERE source.provider = 'intervals'
+      GROUP BY source.activity_id
+    ), derived_power AS (
+      SELECT activity_source_id, avg(best_power_w) AS derived_avg_power_w
+      FROM activity_power_bests
+      GROUP BY activity_source_id
+    )
+    SELECT ranked.* EXCLUDE (source_rank),
+      intervals_analysis.intervals_training_load,
+      intervals_analysis.intervals_rpe,
+      intervals_analysis.intervals_feel,
+      intervals_analysis.intervals_weighted_power,
+      derived_power.derived_avg_power_w
+    FROM ranked
+    LEFT JOIN intervals_analysis USING (activity_id)
+    LEFT JOIN derived_power USING (activity_source_id)
+    WHERE source_rank = 1;
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+const courseGeometryMigration = {
+    version: 16,
+    name: 'course_geometry',
+    sql: `
+    -- A4: Garmin course/route geometry so a race's elevation/grade profile can be
+    -- resolved and compared against a prior activity's course. garminconnect
+    -- 0.3.x has no dedicated course method, so courses are staged from the raw
+    -- Connect API (connectapi("course-service/course/{id}"), validated live:
+    -- returns metadata + a geoPoints geometry array) and normalized here.
+    -- courseId is the Garmin course identifier referenced by an event's courseId.
+    CREATE TABLE IF NOT EXISTS course_geometry (
+      course_id VARCHAR NOT NULL,
+      seq INTEGER NOT NULL,
+      lat DOUBLE,
+      lon DOUBLE,
+      altitude_m DOUBLE,
+      distance_m DOUBLE,
+      raw_object_hash VARCHAR,
+      PRIMARY KEY (course_id, seq)
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+const activityDecouplingFactsMigration = {
+    version: 17,
+    name: 'activity_decoupling_facts',
+    sql: `
+    -- A3 (persistence): make aerobic decoupling (Pa:Hr) and grade-adjusted pace
+    -- (GAP) queryable historically instead of only inside one activity's raw
+    -- metrics_json. Rows are provider-supplied when the provider payload carries
+    -- them (source_type 'provider'); locally derived values are tagged 'derived'
+    -- with caveats_json. Provider values remain authoritative and are never
+    -- overwritten by derivation.
+    CREATE TABLE IF NOT EXISTS activity_decoupling_facts (
+      provider VARCHAR NOT NULL,
+      activity_source_id VARCHAR NOT NULL,
+      sport VARCHAR,
+      started_at_utc TIMESTAMPTZ,
+      metric VARCHAR NOT NULL,
+      value_number DOUBLE,
+      unit VARCHAR,
+      source_type VARCHAR NOT NULL,
+      caveats_json JSON,
+      raw_object_hash VARCHAR,
+      PRIMARY KEY (provider, activity_source_id, metric)
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration, canonicalTrainingDerivedAvgPowerMigration, courseGeometryMigration, activityDecouplingFactsMigration];
 //# sourceMappingURL=migrations.js.map

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

@@ -0,0 +1,61 @@
+import { type SyncProgressSnapshot, type SyncProgressState, type SyncStage } from '../../contracts/progress.js';
+import type { CatencePaths } from '../../contracts/runtime.js';
+import type { SyncLogger } from '../../core/logging.js';
+import type { CatenceDatabase } from './database.js';
+export declare const PROGRESS_SIDECAR_SUFFIX = ".progress.json";
+export declare const PROGRESS_SIDECAR_STALE_MS: number;
+export declare const PROGRESS_KEEPALIVE_MS: number;
+export declare const PROGRESS_PUBLISH_THROTTLE_MS: number;
+export declare function progressSidecarPath(paths: CatencePaths, runId: string): string;
+/**
+ * Persist one progress heartbeat as a sidecar file next to the Garmin staging
+ * manifest. Reading this file needs no DuckDB lock, so `progress` stays live
+ * while a sync run holds the single-writer database lock.
+ */
+export declare function writeProgressSidecar(paths: CatencePaths, runId: string, state: SyncProgressState): Promise<void>;
+export declare function removeProgressSidecar(paths: CatencePaths, runId: string): Promise<void>;
+/**
+ * Scan every persisted sidecar heartbeat for an athlete store. Corrupt or
+ * unreadable files are skipped so a torn write can never break progress reads.
+ */
+export declare function readProgressSidecars(paths: CatencePaths): Promise<SyncProgressState[]>;
+/** Active runs from sidecars: non-terminal stage and a fresh heartbeat. */
+export declare function readRunningProgress(paths: CatencePaths, staleAfterMs?: number): Promise<SyncProgressState[]>;
+/**
+ * Merge database-backed progress with sidecar heartbeats. Sidecars win for a
+ * given run (they are freshest); database rows fill runs that never emitted a
+ * sidecar (for example Intervals runs). Recent history is deduplicated across
+ * both sources and sorted by heartbeat recency.
+ */
+export declare function mergeProgress(dbRunning: SyncProgressState[], dbRecent: SyncProgressState[], sidecars: SyncProgressState[]): SyncProgressSnapshot;
+export interface ProgressPumpOptions {
+    database: CatenceDatabase;
+    paths: CatencePaths;
+    log: SyncLogger;
+}
+/**
+ * Drives progress heartbeats for the whole lifetime of a sync run - including
+ * phases that emit no worker output (the Intervals extractor and the Garmin
+ * JSONL import). `publish` throttles writes to the database and sidecar; a
+ * 30-second keep-alive interval refreshes the last known state so a run never
+ * looks stale while it is still active, even during the lock-holding import.
+ */
+export declare class ProgressPump {
+    private readonly runId;
+    private readonly provider;
+    private readonly options;
+    private lastProgress;
+    private lastHeartbeatAt;
+    private interval;
+    private stageOverride;
+    constructor(runId: string, provider: string, options: ProgressPumpOptions);
+    start(): void;
+    publish(state: SyncProgressState): void;
+    /** Force subsequent keep-alive heartbeats to report the given stage. */
+    setStage(stage: SyncStage): void;
+    /** Transition the run to the JSONL import stage; keep-alives persist it. */
+    setStageImporting(): void;
+    /** Write a terminal heartbeat immediately, bypassing the publish throttle. */
+    publishFinal(state: SyncProgressState): Promise<void>;
+    stop(): void;
+}

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

@@ -0,0 +1,200 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeProgress, } from '../../contracts/progress.js';
+export const PROGRESS_SIDECAR_SUFFIX = '.progress.json';
+export const PROGRESS_SIDECAR_STALE_MS = 5 * 60 * 1000;
+export const PROGRESS_KEEPALIVE_MS = 30 * 1000;
+export const PROGRESS_PUBLISH_THROTTLE_MS = 2 * 1000;
+const TERMINAL_STAGES = new Set(['completed', 'failed', 'interrupted', 'timed_out']);
+export function progressSidecarPath(paths, runId) {
+    return path.join(paths.staging, 'garmin', `${runId}${PROGRESS_SIDECAR_SUFFIX}`);
+}
+/**
+ * Persist one progress heartbeat as a sidecar file next to the Garmin staging
+ * manifest. Reading this file needs no DuckDB lock, so `progress` stays live
+ * while a sync run holds the single-writer database lock.
+ */
+export async function writeProgressSidecar(paths, runId, state) {
+    const target = progressSidecarPath(paths, runId);
+    await mkdir(path.dirname(target), { recursive: true });
+    const temporary = `${target}.${Date.now()}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+    await writeFile(temporary, JSON.stringify(state));
+    await rename(temporary, target);
+}
+export async function removeProgressSidecar(paths, runId) {
+    await rm(progressSidecarPath(paths, runId), { force: true });
+}
+/**
+ * Scan every persisted sidecar heartbeat for an athlete store. Corrupt or
+ * unreadable files are skipped so a torn write can never break progress reads.
+ */
+export async function readProgressSidecars(paths) {
+    const directory = path.join(paths.staging, 'garmin');
+    if (!existsSync(directory))
+        return [];
+    const files = (await readdir(directory)).filter((file) => file.endsWith(PROGRESS_SIDECAR_SUFFIX));
+    const states = [];
+    for (const file of files) {
+        try {
+            const state = normalizeProgress(JSON.parse(await readFile(path.join(directory, file), 'utf8')));
+            if (state)
+                states.push(state);
+        }
+        catch {
+            // Torn or partial sidecar write; it is not authoritative.
+        }
+    }
+    return states;
+}
+/** 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 = [];
+    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 (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;
+}
+/**
+ * Merge database-backed progress with sidecar heartbeats. Sidecars win for a
+ * given run (they are freshest); database rows fill runs that never emitted a
+ * sidecar (for example Intervals runs). Recent history is deduplicated across
+ * both sources and sorted by heartbeat recency.
+ */
+export function mergeProgress(dbRunning, dbRecent, sidecars) {
+    const running = new Map();
+    for (const state of sidecars)
+        running.set(state.runId, state);
+    for (const state of dbRunning)
+        if (!running.has(state.runId))
+            running.set(state.runId, state);
+    const recent = new Map();
+    for (const state of dbRecent)
+        recent.set(state.runId, state);
+    for (const state of sidecars)
+        recent.set(state.runId, state);
+    return {
+        running: [...running.values()],
+        recent: [...recent.values()]
+            .sort((a, b) => Date.parse(b.heartbeatAt) - Date.parse(a.heartbeatAt))
+            .slice(0, 10),
+    };
+}
+function baselineState(runId, provider, stage) {
+    return {
+        runId,
+        provider,
+        stage,
+        currentStep: null,
+        completedUnits: 0,
+        totalUnits: null,
+        percentComplete: 0,
+        elapsedSeconds: 0,
+        estimatedRemainingSeconds: null,
+        heartbeatAt: new Date().toISOString(),
+    };
+}
+/**
+ * Drives progress heartbeats for the whole lifetime of a sync run - including
+ * phases that emit no worker output (the Intervals extractor and the Garmin
+ * JSONL import). `publish` throttles writes to the database and sidecar; a
+ * 30-second keep-alive interval refreshes the last known state so a run never
+ * looks stale while it is still active, even during the lock-holding import.
+ */
+export class ProgressPump {
+    runId;
+    provider;
+    options;
+    lastProgress = null;
+    lastHeartbeatAt = 0;
+    interval = null;
+    stageOverride = null;
+    constructor(runId, provider, options) {
+        this.runId = runId;
+        this.provider = provider;
+        this.options = options;
+    }
+    start() {
+        if (this.interval)
+            return;
+        this.interval = setInterval(() => {
+            this.publish(this.lastProgress
+                ? { ...this.lastProgress, heartbeatAt: new Date().toISOString() }
+                : baselineState(this.runId, this.provider, this.stageOverride ?? 'starting'));
+        }, PROGRESS_KEEPALIVE_MS);
+        this.interval.unref();
+    }
+    publish(state) {
+        const now = Date.now();
+        if (this.lastHeartbeatAt !== 0 && now - this.lastHeartbeatAt < PROGRESS_PUBLISH_THROTTLE_MS) {
+            this.lastProgress = state;
+            return;
+        }
+        this.lastHeartbeatAt = now;
+        this.lastProgress = state;
+        const { database, paths, log } = this.options;
+        void database.heartbeatRun(this.runId, state).catch((error) => {
+            log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+        });
+        void writeProgressSidecar(paths, this.runId, state).catch((error) => {
+            log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+        });
+    }
+    /** Force subsequent keep-alive heartbeats to report the given stage. */
+    setStage(stage) {
+        this.stageOverride = stage;
+        if (this.lastProgress) {
+            this.lastProgress = { ...this.lastProgress, stage };
+            this.publish(this.lastProgress);
+        }
+    }
+    /** Transition the run to the JSONL import stage; keep-alives persist it. */
+    setStageImporting() {
+        this.setStage('importing');
+    }
+    /** Write a terminal heartbeat immediately, bypassing the publish throttle. */
+    async publishFinal(state) {
+        this.lastHeartbeatAt = Date.now();
+        this.lastProgress = state;
+        const { database, paths, log } = this.options;
+        // 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) });
+        });
+        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) });
+        });
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+}
+//# sourceMappingURL=progress-sidecar.js.map

package/dist/interfaces/cli/commands.js

@@ -2,7 +2,7 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
     .description('Athlete-scoped Catence data setup, extraction, and normalization.')
@@ -158,6 +158,38 @@ program.command('status').action(async () => {
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await dataStatus(paths), null, 2)}\n`);
 });
+function renderProgress(snapshot) {
+    const lines = snapshot.running.map((run) => {
+        const pct = run.percentComplete.toFixed(1).padStart(5);
+        const units = run.totalUnits !== null ? `${run.completedUnits}/${run.totalUnits}` : String(run.completedUnits);
+        const eta = run.estimatedRemainingSeconds !== null ? `${Math.round(run.estimatedRemainingSeconds)}s` : '?';
+        const step = run.currentStep ?? '';
+        return `${pct}%  ${run.stage.padEnd(12)} ${units.padEnd(11)} ${eta.padEnd(6)} ${step}`;
+    });
+    return lines.length === 0 ? 'no active sync runs' : lines.join('\n');
+}
+program.command('progress')
+    .description('Show live progress for active sync runs.')
+    .option('--watch', 'refresh every few seconds until no sync runs are active')
+    .action(async (options) => {
+    const { paths } = await currentAthlete();
+    if (!options.watch) {
+        process.stdout.write(`${JSON.stringify(await syncProgress(paths), null, 2)}\n`);
+        return;
+    }
+    while (true) {
+        const snapshot = await syncProgress(paths);
+        if (output.isTTY) {
+            output.write(`\x1b[2J\x1b[H${renderProgress(snapshot)}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+        }
+        if (snapshot.running.length === 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+});
 program.command('update')
     .description('Check for and apply the newest Catence release on the tracked channel (runtime and Console).')
     .option('--check', 'report available releases without changing anything')
@@ -220,5 +252,66 @@ program.command('build-retrieval-index').description('Build derived local retrie
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await rebuildRetrievalIndex(paths), null, 2)}\n`);
 });
+program.command('reimport-nutrition').description('Re-run normalization over captured nutrition entities without contacting providers.').action(async () => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await reimportNutrition(paths), null, 2)}\n`);
+});
+program
+    .command('import')
+    .description('Import a staged JSONL file (for example a swim-length backfill) into one athlete’s data store.')
+    .requiredOption('--provider <provider>', 'garmin, intervals, or strava')
+    .argument('<file>', 'path to the staged JSONL file')
+    .action(async (file, options) => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await importStagedFile(paths, options.provider, file), null, 2)}\n`);
+});
+program
+    .command('resolve-errors')
+    .description('Mark unresolved extraction errors as resolved (for example stale bootstrap failures from an environment that has since recovered).')
+    .option('--run <run-id>', 'resolve errors from a specific run only (repeatable)')
+    .option('--provider <provider>', 'resolve errors for garmin, intervals, or strava only')
+    .option('--before <timestamp>', 'resolve errors created before this ISO timestamp')
+    .option('--all', 'resolve every unresolved error')
+    .action(async (options) => {
+    const { paths } = await currentAthlete();
+    const runIds = Array.isArray(options.run) ? options.run : options.run ? [options.run] : undefined;
+    process.stdout.write(`${JSON.stringify(await resolveExtractionErrors(paths, { runIds, provider: options.provider, before: options.before, all: options.all }), null, 2)}\n`);
+});
+program
+    .command('migrate')
+    .description('Apply pending DuckDB schema migrations. Without --all it migrates the selected --athlete store; with --all it migrates every athlete in the catalog.')
+    .option('--all', 'migrate every athlete in the catalog')
+    .option('--home <directory>', 'Catence catalog home directory (also accepts global --home)')
+    .action(async (options) => {
+    const effectiveHome = options.home ?? program.opts().home;
+    const effectiveCatalog = effectiveHome ? resolveCatalogPaths(effectiveHome) : currentCatalog();
+    const migratePaths = async (paths) => {
+        const database = await CatenceDatabase.open(paths);
+        const applied = await database.rows('SELECT version FROM schema_migrations ORDER BY version');
+        await database.close();
+        return { migrated: true, appliedVersions: applied.map((row) => row.version) };
+    };
+    if (options.all) {
+        const catalog = await loadCatalog(effectiveCatalog);
+        const results = {};
+        for (const athlete of catalog.athletes) {
+            const paths = athleteStorePaths(effectiveCatalog, athlete.id);
+            try {
+                results[athlete.id] = await migratePaths(paths);
+            }
+            catch (error) {
+                results[athlete.id] = { migrated: false, error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+        process.stdout.write(`${JSON.stringify({ catalog: effectiveCatalog.root, results }, null, 2)}\n`);
+        return;
+    }
+    const athleteId = program.opts().athlete;
+    if (!athleteId)
+        throw new Error('--athlete is required for this command. Run catence-data athlete list to inspect the catalog or use --all.');
+    const { athlete, paths } = await resolveAthlete(effectiveCatalog, athleteId);
+    const result = await migratePaths(paths);
+    process.stdout.write(`${JSON.stringify({ athleteId: athlete.id, ...result }, null, 2)}\n`);
+});
 await program.parseAsync();
 //# sourceMappingURL=commands.js.map

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

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

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

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

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

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