catence 0.2.0 → 0.2.1-beta.10

package/docs/deployment/local-console.md

@@ -2,7 +2,8 @@
 
 Catence Console is a password-protected local web chat that starts a matching
 Catence runtime on loopback. It uses Chainlit password login and fails closed
-unless all three authentication variables are supplied.
+unless `CHAINLIT_AUTH_SECRET` and at least one login source — a stored Console
+account or the environment account pair — are configured.
 
 This guide covers the **local** path: the npm package plus the Python Console
 on your machine. The Docker path (one container built from the public
@@ -27,6 +28,7 @@ model.
 | Provider credentials | per-athlete secret file, mode 0600 | `catence-data secret set` |
 | API keys | process environment only | shell exports |
 | Chat history + preferences | data home | `console/chat-history.sqlite3` |
+| Console logins + athlete grants | data home (mode 0600, bcrypt hashes) | `console/accounts.json` |
 
 Credentials never land in `config.json`; profiles reference environment
 variable *names* (`apiKeyEnv`, `apiBaseEnv`, `apiVersionEnv`). See
@@ -95,15 +97,28 @@ To add OpenCode Go models, run the
 
 ```sh
 export OPENAI_API_KEY='…'                        # or ANTHROPIC_API_KEY / OPENCODE_GO_API_KEY …
-export CATENCE_CONSOLE_USERNAME='coach'
-export CATENCE_CONSOLE_PASSWORD_HASH="$(catence-console auth hash-password)"
 export CHAINLIT_AUTH_SECRET="$(openssl rand -hex 32)"
 ```
 
-The Console fails closed unless `CATENCE_CONSOLE_USERNAME`,
-`CATENCE_CONSOLE_PASSWORD_HASH` (a bcrypt hash), and `CHAINLIT_AUTH_SECRET`
-are all set. There is one shared account; the username/password pair grants a
-single `console-owner` role.
+`CHAINLIT_AUTH_SECRET` is always required: it signs Chainlit sessions. On top
+of it, the Console needs at least one login source:
+
+- **Stored accounts** (the multi-user path). Each account carries a role and
+  an athlete grant list and lives in `<home>/console/accounts.json`. Create
+  the first one with the users CLI, which prompts for the password twice:
+
+  ```sh
+  catence-console users add coach --admin
+  ```
+
+- **The environment break-glass account**: set both
+  `CATENCE_CONSOLE_USERNAME` and `CATENCE_CONSOLE_PASSWORD_HASH` (the bcrypt
+  hash printed by `catence-console auth hash-password`). The pair is never
+  persisted and always acts as an admin — the way back in when the accounts
+  file is lost.
+
+Roles, grants, and the rest of the CLI are described under
+[Console accounts](#console-accounts).
 
 ## 7. Start the Console
 
@@ -121,7 +136,7 @@ catence-console doctor
 
 ### Manage models in the Console
 
-The **Models** page (header button) manages the model list without editing
+The **Settings → Models** tab manages the model list without editing
 `config.json` by hand:
 
 - Enable/disable toggles hide models from the chat's Model dropdown. Disabled
@@ -137,11 +152,87 @@ The **Models** page (header button) manages the model list without editing
   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
+**Settings → Status** 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.
+completed sync afterwards; the Dashboard keeps a read-only “Syncing…” pill and
+links there when a write lock makes its data unavailable. Each manual sync also
+refreshes OpenCode Go model profiles first; a discovery failure never blocks the
+data sync.
+
+### Add athletes in the Console
+
+Admins can add a catalog athlete from **Settings → Athletes** (athlete id,
+display name, and optionally “set as default”). The form calls the runtime's
+`POST /api/v1/athletes` through the Console, which rejects members with
+`403 admin_required` and otherwise performs the same catalog write as
+`catence-data athlete add --id <id> --label <label>`. The id must match
+`^[a-z][a-z0-9-]{0,62}$` and must not already exist (`409 athlete_exists`);
+single-store runtimes without a catalog refuse with `400 catalog_required`.
+The roster refreshes immediately, so a new athlete can be granted to members
+and selected in chat without restarting the Console.
+
+## Console accounts
+
+Console accounts are Catence's multi-user login model, enforced entirely by
+the Console: sign-in, the athlete roster, dashboard and athlete-file requests,
+and the athlete scoping of every chat turn are all checked server-side against
+the account's role and athlete grants. The MCP server itself is untouched — it
+has no authentication and trusts the `athleteId` each call names (see
+[local-mcp.md](local-mcp.md#streamable-http-server)); accounts only gate what
+goes through the Console.
+
+| Role | Athlete access |
+| --- | --- |
+| `admin` | Every athlete in the catalog (`athletes: "all"`) |
+| `member` | Only the explicitly granted athletes; zero grants allowed |
+
+Accounts live in `<home>/console/accounts.json` (mode 0600, bcrypt hashes
+only), where `<home>` is `$CATENCE_HOME` or `~/.catence`. The Console re-reads
+the file on every login, so new accounts, password resets, and grant changes
+apply without a restart.
+
+### Manage accounts with the users CLI
+
+```sh
+catence-console users add coach --admin                    # admin: all athletes
+catence-console users add martina --athlete martina        # member with one grant
+catence-console users add sam                              # member, zero grants
+catence-console users list
+catence-console users passwd martina
+catence-console users set-role sam member
+catence-console users grant sam martina
+catence-console users revoke sam martina
+catence-console users remove sam
+```
+
+- `add <username> (--admin | --athlete <id> [--athlete <id> …])` — members
+  default to zero grants; `--admin` cannot be combined with `--athlete` and
+  always stores access to every athlete.
+- `add` and `passwd` prompt for the password twice (never echoed). For
+  automation, `--password-env VAR` reads the password from environment
+  variable `VAR` instead, so it never appears in the command line or shell
+  history.
+- `grant`/`revoke` change a member's athlete list; revoking the last grant
+  leaves a zero-grant member. `set-role` promotes or demotes: promoting to
+  `admin` coerces the grants to `"all"`, demoting to `member` keeps them.
+- `add`/`grant`/`revoke` validate athlete ids against `catalog.json` when it
+  exists, and `--home <dir>` points any subcommand at a non-default catalog.
+
+A member with zero grants can sign in and browse the Console, but there is no
+athlete to scope a chat to: the Athlete selector is disabled with *"You don't
+have access to any athlete yet. Ask an administrator to grant you access."*
+and every chat turn is answered with the same notice. A member that requests
+an athlete outside their grants receives `403 athlete_forbidden`; the Console
+never forwards the request to the runtime.
+
+### The environment break-glass account
+
+`CATENCE_CONSOLE_USERNAME` and `CATENCE_CONSOLE_PASSWORD_HASH` must be set
+together. When they are, the pair always acts as an `admin` and is never
+written to `accounts.json`: unsetting the two variables revokes it. Use it as
+the recovery path when the accounts file is lost or a lockout leaves nobody
+who can grant access — not as the everyday login.
 
 ## Console serve options
 
@@ -167,12 +258,18 @@ chat starts.
 
 ## How multi-athlete works in the Console
 
-The Console shares the same per-athlete stores as MCP, but scoping is
-**server-owned, not model-owned**:
+The Console shares the same per-athlete stores as MCP. Access is layered:
+per-account grants at the login, then server-owned scoping per chat.
 
+- **Per-account grants.** Each stored account is an `admin` (every athlete) or
+  a `member` with an explicit grant list (see
+  [Console accounts](#console-accounts)). The **Athlete** selector and the
+  proxied roster are narrowed to the account's grants; requests that name an
+  ungranted athlete are refused with `403 athlete_forbidden` before they reach
+  the runtime, and a zero-grant member sees no athletes at all.
 - The settings panel has an **Athlete** selector built from
   `GET /api/v1/athletes` on the runtime. The default is the catalog's
-  `defaultAthleteId`.
+  `defaultAthleteId` (for a member, the first granted athlete).
 - On every personal-data tool call, the Console **forces** the selected
   athleteId onto the arguments — the model cannot name or switch athletes, and
   a chat's system message states: *"This Console chat is scoped to athleteId X.
@@ -183,10 +280,12 @@ The Console shares the same per-athlete stores as MCP, but scoping is
   announces *"This chat is scoped to athlete **<id>**."*
 - `list_athletes` is exempt from forcing so the roster can be rendered.
 
-The dashboard is fetched through the authenticated Console origin: Chainlit
-middleware proxies `GET /api/v1/dashboard` and `GET /api/v1/athletes` to the
-runtime only when the Console's JWT cookie is valid (otherwise 401), so raw
-port 8787 does not need to be exposed.
+Console pages and chats reach the runtime through the authenticated Console
+origin: Chainlit middleware proxies the Console's API surface — `GET
+/api/v1/dashboard`, `GET`/`POST /api/v1/athletes` (POST is admin-only), `GET
+/api/v1/threads/<id>/generation`, and the models, accounts, tool-server, and
+sync routes — to the runtime only when the Console's JWT cookie is valid
+(otherwise 401), so raw port 8787 does not need to be exposed.
 
 ## Model discovery (OpenCode Go)
 
@@ -205,8 +304,8 @@ disappeared from the live catalog.
 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
+Inside **Settings → Models**, **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.
@@ -260,4 +359,8 @@ uv tool install --upgrade catence-console
   environment variables; set them in the shell and restart the Console.
 - **Runtime not reachable** — `catence-console doctor --home "$HOME/.catence"
   --mcp-url http://127.0.0.1:8787/mcp` checks the handshake; confirm the
-  runtime is running on that port and the protocol versions agree.
+  runtime is running on that port and the protocol versions agree.
+- **Locked out of the Console** — sign in with the environment break-glass
+  account (`CATENCE_CONSOLE_USERNAME`/`CATENCE_CONSOLE_PASSWORD_HASH`) and
+  restore access with `catence-console users` (reset a password, re-grant
+  athletes, or add a new admin).

package/docs/deployment/local-mcp.md

@@ -81,14 +81,17 @@ catence
 ```
 
 An agent first calls `list_athletes`, then includes `athleteId` with every
-data tool. This is intentional: a shared agent may access the stores you
-configured, but no tool implicitly aggregates or crosses between athletes.
+data tool. Tools act only on the named athlete store and never merge athletes
+implicitly; the MCP server does not authenticate callers — it trusts the
+`athleteId` each call names.
 
 ## Multi-athlete catalog
 
-Catence is designed to serve **several isolated athlete stores** from one
-shared server. Each store has its own DuckDB, raw data, and tokens, so
-athletes never leak into each other.
+Catence serves several athlete stores from one server. Each store has its own
+DuckDB, raw data, and tokens; a call acts on the single store it names and
+never merges athletes implicitly. That is a tool contract, not an access
+boundary: the MCP server does not authenticate callers and trusts the
+`athleteId` they pass — see [MCP clients and HTTP](#streamable-http-server).
 
 ### MCP behavior
 
@@ -300,6 +303,10 @@ By default it is loopback-only. `CATENCE_HTTP_HOST` and `CATENCE_HTTP_PORT`
 override the host and port when the flags are omitted.
 
 - `GET /api/v1/athletes` returns IDs and labels only.
+- `POST /api/v1/athletes` creates a catalog athlete from
+  `{"id": "sam", "label": "Sam", "setDefault": false}` and answers with the
+  updated roster; duplicate ids are refused with `409 athlete_exists`, and
+  single-store runtimes without a catalog with `400 catalog_required`.
 - `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).

package/docs/development.md

@@ -321,9 +321,11 @@ Recommended dev defaults:
 - The deployed scaffold's `sync.sh` / `hash-password.sh` / `doctor.sh` helpers are generated by `scripts/deploy-console.sh`; the dev container does not generate them — use the `npm run` / `uv run` equivalents above, or run the same `catence-data --home /data` commands via `docker compose exec`.
 - If the Console settings panel shows no Model dropdown, the data home's `config.json` has no `console.profiles` — re-copy `config.example.json` or re-run the discovery script, then restart the Console.
 
-### Status vs Dashboard
+### Settings, Status, and Dashboard
 
-The **Dashboard** (`/dashboard`) is now a pure analytics view — it renders charts and recent activities from `GET /api/v1/dashboard` and, when a detached sync holds the DuckDB write lock, shows a non-blocking amber banner (“Data temporarily unavailable — a sync is running. View live progress on the Status page.”) instead of a full-page `dashboard_unavailable` error. The **Status** page (`/status`) is the lock-safe control plane: it reads `GET /api/v1/health` (runtime `catenceRuntimeHealth()`), `GET /api/v1/sync/status` (sidecar heartbeats + `lastSync`), and `GET /api/v1/athletes` (roster), so it never needs a successful `dashboardSnapshot` and never 400s under lock. The interactive **Sync** button (with instant grey-out via `startingRef`) lives only on Status; Dashboard keeps a read-only “Syncing…” pill and a “Sync moved to Status →” banner.
+Top-level navigation is **Chat**, **Dashboard**, and **Settings**; the chat-history sidebar only renders on Chat routes, so the other pages use the full width. **Settings** (`/settings`) is a single page whose tabs — Profile, Status, and Models for every account, plus Athletes and Accounts for admins — are deep-linkable as `/settings?tab=<tab>`; asking for a tab the account cannot see falls back to the first visible one.
+
+The **Dashboard** (`/dashboard`) is a pure analytics view — it renders charts and recent activities from `GET /api/v1/dashboard` and, when a detached sync holds the DuckDB write lock, shows a non-blocking amber banner (“Data temporarily unavailable — a sync is running. View live progress in Settings → Status.”) instead of a full-page `dashboard_unavailable` error. **Settings → Status** (`/settings?tab=status`) is the lock-safe control plane: it reads `GET /api/v1/health` (runtime `catenceRuntimeHealth()`), `GET /api/v1/sync/status` (sidecar heartbeats + `lastSync`), and `GET /api/v1/athletes` (roster), so it never needs a successful `dashboardSnapshot` and never 400s under lock. The interactive **Sync** button (with instant grey-out via `startingRef`) lives only there; Dashboard keeps a read-only “Syncing…” pill and a “Sync moved to Settings → Status” banner.
 
 ## Troubleshooting
 
@@ -334,4 +336,4 @@ The **Dashboard** (`/dashboard`) is now a pure analytics view — it renders cha
   1. Runtime status API: `curl -s "http://127.0.0.1:8787/api/v1/sync/status?athleteId=<id>" | jq '.progress.running'` (through the Console instead: `/api/v1/sync/status` behind your login).
   2. Detached-child log files: `ls -t "$CATENCE_HOME/logs" | head`. A successful `POST /api/v1/sync` creates `logs/sync-<athlete>-<stamp>.log` before spawning, so an absent or empty `logs/` directory proves no detached sync ever started.
   3. The MCP progress tools (`catence_sync_progress`) read the same heartbeats.
-- **Models page clutter** — unused shipped profiles can be hidden per device from the Models page (`Hide` on the profile card); hidden profiles disappear from the chat Model dropdown but stay configured, and are restored with `Unhide`. Hiding lives in the Console database, never in `config.json`.
+- **Models page clutter** — unused shipped profiles can be hidden per device from **Settings → Models** (`Hide` on the profile card); hidden profiles disappear from the chat Model dropdown but stay configured, and are restored with `Unhide`. Hiding lives in the Console database, never in `config.json`.

package/docs/llm-providers.md

@@ -203,10 +203,10 @@ of the live catalog are pruned from the managed profiles, so the Console never
 offers a route the gateway no longer serves; if a pruned model was the
 profile's default, discovery selects a current one instead.
 
-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
+You do not have to run the script manually: the **Sync data** button in
+**Settings → Status** (and `POST /api/v1/sync` with `"refreshModels": true`)
+refreshes these profiles from the live catalog before starting a data sync, and
+the **Discover OpenCode Go models** button in **Settings → Models** (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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.2.0",
+  "version": "0.2.1-beta.10",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -55,6 +55,7 @@
     "test:watch": "vitest",
     "catence-data": "tsx src/interfaces/cli/main.ts",
     "mcp": "tsx src/interfaces/mcp/main.ts",
+    "dev": "node scripts/dev.mjs",
     "console": "uv run --project console catence-console serve",
     "console:doctor": "uv run --project console catence-console doctor",
     "discover:opencode-go": "node scripts/discover-opencode-go.mjs",
@@ -79,11 +80,12 @@
     "@types/node": "^24.3.0",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^5.0.0"
   },
   "overrides": {
-    "fast-uri": "3.1.5",
-    "hono": "4.12.34",
-    "nanoid": "3.3.18"
+    "fast-uri": "3.1.8",
+    "hono": "4.13.7",
+    "nanoid": "3.3.18",
+    "qs": "6.16.0"
   }
 }

package/pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
 
 [tool.uv.sources]
 # fork commit
-garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "cd4e3d9ef81a93681950138e08f57af226fd5735" }
+garminconnect = { git = "https://github.com/rifusaki/python-garminconnect.git", rev = "38b3d5003ae348de384f679976d0527316775f94" }
 
 [tool.uv]
 package = false

package/python/catence/providers/garmin/cli.py

@@ -8,6 +8,7 @@ import signal
 import sys
 from datetime import date
 from pathlib import Path
+from typing import Any
 
 from .progress import ProgressReporter
 from .staging import StagingWriter
@@ -40,7 +41,31 @@ def parse_args() -> argparse.Namespace:
         type=date.fromisoformat,
         help="Fetch calendar events from this date instead of the default short lookback.",
     )
-    return parser.parse_args()
+    parser.add_argument(
+        "--concurrency",
+        type=int,
+        default=5,
+        help="Maximum in-flight Garmin requests (1 disables request parallelization).",
+    )
+    args = parser.parse_args()
+    if args.concurrency < 1:
+        parser.error("--concurrency must be at least 1")
+    return args
+
+
+def _print_run_summary(run_id: str, worker: GarminStagingWorker, reporter: ProgressReporter) -> None:
+    """Emit one stderr record with per-stage timings and capture counts.
+
+    The management layer surfaces stderr in the sync log, so quiet-day runs
+    carry their own performance profile without an extra instrumentation pass.
+    """
+    record: dict[str, Any] = {
+        "kind": "stage_timings",
+        "runId": run_id,
+        "timings": {name: round(seconds, 2) for name, seconds in reporter.stage_summary().items()},
+    }
+    record.update(worker.capture_summary())
+    print(json.dumps(record, separators=(",", ":")), file=sys.stderr, flush=True)
 
 
 def main() -> None:
@@ -65,7 +90,7 @@ def main() -> None:
         loaded = json.loads(args.known_activities.read_text(encoding="utf-8"))
         if isinstance(loaded, dict):
             known_hashes = {str(key): str(value) for key, value in loaded.items()}
-    worker = GarminStagingWorker(client, writer, args.data_dir, known_hashes, progress=reporter)
+    worker = GarminStagingWorker(client, writer, args.data_dir, known_hashes, progress=reporter, concurrency=args.concurrency)
     interrupt_signal: int | None = None
 
     def _request_interrupt(signum: int, _frame: object) -> None:
@@ -89,7 +114,10 @@ def main() -> None:
     except WorkerInterrupted:
         reporter.finish("interrupted")
         raise SystemExit(130 if interrupt_signal == signal.SIGINT else 143)
-    reporter.finish("completed")
+    else:
+        reporter.finish("completed")
+    finally:
+        _print_run_summary(args.run_id, worker, reporter)
 
 
 if __name__ == "__main__":

package/python/catence/providers/garmin/progress.py

@@ -2,19 +2,26 @@
 
 Emits single-line JSON progress records (kind: 'progress') on stdout so the
 Node management layer can persist heartbeats without parsing the staging
-JSONL consumed by the importer.
+JSONL consumed by the importer. Captures run on several threads once sync
+concurrency is enabled, so every state mutation happens under a lock while
+the actual emit stays outside it.
+
+The reporter also accumulates per-stage wall-clock timings; the CLI prints
+them to stderr as a single `stage_timings` record so each sync run carries
+its own phase profile.
 """
 
 from __future__ import annotations
 
 import json
+import threading
 import time
 from datetime import datetime, timezone
 from typing import Any, Callable
 
 
 class ProgressReporter:
-    """Throttled progress publisher writing NDJSON records to stdout."""
+    """Throttled, thread-safe progress publisher writing NDJSON records to stdout."""
 
     def __init__(
         self,
@@ -27,59 +34,88 @@ class ProgressReporter:
         self.provider = provider
         self.emit = emit
         self.interval_seconds = interval_seconds
+        self._lock = threading.Lock()
         self._started = time.monotonic()
         self._last_emitted = 0.0
+        self._stage_started = self._started
         self.stage = "starting"
         self.current_step: str | None = None
         self.completed_units = 0
         self.total_units: int | None = None
+        self.stage_timings: dict[str, float] = {}
 
     def set_stage(self, stage: str) -> None:
         """Switch phases, resetting phase-local counters and forcing a publish."""
-        if stage != self.stage:
+        with self._lock:
+            if stage == self.stage:
+                return
+            self._close_stage_locked()
             self.stage = stage
             self.current_step = None
             self.completed_units = 0
             self.total_units = None
-            self.publish(force=True)
+        self.publish(force=True)
 
     def advance(self, completed: int | None = None, total: int | None = None, step: str | None = None) -> None:
-        if completed is not None:
-            self.completed_units = completed
-        if total is not None:
-            self.total_units = total
-        if step is not None:
-            self.current_step = step
+        with self._lock:
+            if completed is not None:
+                self.completed_units = completed
+            if total is not None:
+                self.total_units = total
+            if step is not None:
+                self.current_step = step
+        self.publish()
+
+    def add_completed(self, amount: int = 1) -> None:
+        """Increment the completed-unit counter without replacing it."""
+        with self._lock:
+            self.completed_units += amount
         self.publish()
 
     def publish(self, force: bool = False) -> None:
         now = time.monotonic()
-        if not force and now - self._last_emitted < self.interval_seconds:
-            return
-        self._last_emitted = now
-        elapsed = now - self._started
-        percent = 0.0
-        eta: float | None = None
-        if self.total_units and self.total_units > 0:
-            percent = min(100.0, max(0.0, self.completed_units / self.total_units * 100.0))
-            if self.completed_units > 0 and self.completed_units < self.total_units:
-                rate = elapsed / self.completed_units
-                eta = rate * (self.total_units - self.completed_units)
-        record = {
-            "kind": "progress",
-            "runId": self.run_id,
-            "provider": self.provider,
-            "stage": self.stage,
-            "currentStep": self.current_step,
-            "completedUnits": self.completed_units,
-            "totalUnits": self.total_units,
-            "percentComplete": round(percent, 2),
-            "elapsedSeconds": round(elapsed, 1),
-            "estimatedRemainingSeconds": round(eta, 1) if eta is not None else None,
-            "heartbeatAt": datetime.now(timezone.utc).isoformat(),
-        }
+        with self._lock:
+            if not force and now - self._last_emitted < self.interval_seconds:
+                return
+            self._last_emitted = now
+            elapsed = now - self._started
+            percent = 0.0
+            eta: float | None = None
+            if self.total_units and self.total_units > 0:
+                percent = min(100.0, max(0.0, self.completed_units / self.total_units * 100.0))
+                if 0 < self.completed_units < self.total_units:
+                    rate = elapsed / self.completed_units
+                    eta = rate * (self.total_units - self.completed_units)
+            record: dict[str, Any] = {
+                "kind": "progress",
+                "runId": self.run_id,
+                "provider": self.provider,
+                "stage": self.stage,
+                "currentStep": self.current_step,
+                "completedUnits": self.completed_units,
+                "totalUnits": self.total_units,
+                "percentComplete": round(percent, 2),
+                "elapsedSeconds": round(elapsed, 1),
+                "estimatedRemainingSeconds": round(eta, 1) if eta is not None else None,
+                "heartbeatAt": datetime.now(timezone.utc).isoformat(),
+            }
+        # Emitting outside the lock keeps a slow pipe from stalling captures.
         self.emit(json.dumps(record, separators=(",", ":")))
 
+    def stage_summary(self) -> dict[str, float]:
+        """Per-stage elapsed seconds, including the still-open stage."""
+        with self._lock:
+            summary = dict(self.stage_timings)
+            summary[self.stage] = summary.get(self.stage, 0.0) + (time.monotonic() - self._stage_started)
+        return summary
+
     def finish(self, stage: str = "completed") -> None:
-        self.stage = stage
+        with self._lock:
+            self._close_stage_locked()
+            self.stage = stage
+            self._stage_started = time.monotonic()
         self.publish(force=True)
+
+    def _close_stage_locked(self) -> None:
+        self.stage_timings[self.stage] = self.stage_timings.get(self.stage, 0.0) + (time.monotonic() - self._stage_started)
+        self._stage_started = time.monotonic()

package/python/catence/providers/garmin/staging.py

@@ -3,10 +3,12 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import threading
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
+from uuid import uuid4
 
 from . import STAGING_SCHEMA_VERSION
 from .contracts import validate_record
@@ -28,12 +30,15 @@ class StagingWriter:
     def __post_init__(self) -> None:
         self.output.parent.mkdir(parents=True, exist_ok=True)
         self.output.touch(exist_ok=True)
+        self._lock = threading.Lock()
 
     def emit(self, record: dict[str, Any]) -> None:
         record["schemaVersion"] = STAGING_SCHEMA_VERSION
-        with self.output.open("a", encoding="utf-8") as file:
-            file.write(json.dumps(validate_record(record), separators=(",", ":"), default=str))
-            file.write("\n")
+        line = json.dumps(validate_record(record), separators=(",", ":"), default=str) + "\n"
+        # Sync runs fan capture out across threads; serialize whole lines so the
+        # JSONL never interleaves, even though each write still opens the file.
+        with self._lock, self.output.open("a", encoding="utf-8") as file:
+            file.write(line)
 
     def manifest(self, run_id: str, from_date: str) -> None:
         self.emit({
@@ -54,7 +59,9 @@ class StagingWriter:
         destination = self.data_dir / relative
         destination.parent.mkdir(parents=True, exist_ok=True)
         if not destination.exists():
-            temporary = destination.with_suffix(f".{extension}.tmp")
+            # Unique same-directory temp name: concurrent writers can race on
+            # the same content hash, and a shared temp path would clobber.
+            temporary = destination.with_name(f".{destination.name}.{os.getpid()}.{uuid4().hex}.tmp")
             temporary.write_bytes(contents)
             os.replace(temporary, destination)
         self.emit({