catence 0.2.1-beta.5 → 0.2.1-beta.8

package/docs/deployment/docker.md

@@ -26,6 +26,7 @@ explained in the [beta release notes](../../README.md#beta-releases).
 | Provider credentials | per-athlete secret file, mode 0600 | `catence-data secret set` |
 | API keys | process environment only | `.env` |
 | 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
@@ -69,10 +70,16 @@ Script options (run `./deploy-console.sh --help` for the full list):
 
 ## 2. Fill in `catence-deploy/.env`
 
+The Console always needs `CHAINLIT_AUTH_SECRET`, plus at least one login
+source: the **environment break-glass account**
+(`CATENCE_CONSOLE_USERNAME` + `CATENCE_CONSOLE_PASSWORD_HASH`, set together or
+not at all) or a **stored Console account** in the data volume (see
+[Console accounts](#console-accounts)). Add one model-provider key either way.
+
 ```sh
-CATENCE_CONSOLE_USERNAME=coach
-CATENCE_CONSOLE_PASSWORD_HASH='…'      # generate: ./catence-deploy/hash-password.sh
 CHAINLIT_AUTH_SECRET='…'               # generate: openssl rand -hex 32
+CATENCE_CONSOLE_USERNAME=coach         # environment break-glass account …
+CATENCE_CONSOLE_PASSWORD_HASH='…'      # generate: ./catence-deploy/hash-password.sh
 OPENAI_API_KEY='…'                     # or ANTHROPIC_API_KEY / OPENCODE_GO_API_KEY …
 OPENAI_API_BASE=''                     # only for OpenAI-compatible endpoints
 OPENCODE_GO_API_KEY='…'                # the OpenCode Go base URLs are pre-filled below
@@ -80,9 +87,14 @@ OPENCODE_GO_API_BASE='https://opencode.ai/zen/go/v1'
 OPENCODE_GO_MESSAGES_API_BASE='https://opencode.ai/zen/go'
 ```
 
-Generate the Console login hash with the scaffold helper (it prompts on the
-terminal, never echoes, and uses the compose project so it works whatever image
-tag the script built):
+Leave the username/hash pair empty to log in with stored accounts instead: the
+script accepts an existing `console/accounts.json` in the data volume and
+starts without the pair. Set both or neither — a lone username without a hash
+fails the deploy with a clear error.
+
+Generate the hash for the environment pair with the scaffold helper (it
+prompts on the terminal, never echoes, and uses the compose project so it works
+whatever image tag the script built):
 
 ```sh
 ./catence-deploy/hash-password.sh
@@ -102,6 +114,66 @@ Then start the stack (or re-run the script, which re-reads the saved `.env`):
 docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env up -d
 ```
 
+### Console accounts
+
+Stored accounts are the multi-user path: each account has a role and an
+athlete grant list, and the Console enforces both server-side on logins,
+roster/dashboard requests, and agent turns. Accounts live in
+`console/accounts.json` in the data volume (mode 0600, bcrypt hashes only).
+
+Manage them with the `users` command inside the container — via the generated
+helper:
+
+```sh
+./catence-deploy/users.sh add martina --athlete martina   # member: one granted athlete
+./catence-deploy/users.sh add coach --admin               # admin: every athlete
+./catence-deploy/users.sh list
+./catence-deploy/users.sh grant martina sam
+./catence-deploy/users.sh revoke martina sam
+./catence-deploy/users.sh passwd martina
+./catence-deploy/users.sh set-role martina admin
+./catence-deploy/users.sh remove martina
+```
+
+`users.sh` uses `docker compose exec`, so the stack must be running. The long
+forms are:
+
+```sh
+# Interactive: prompts for the password twice
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env exec console \
+  /opt/catence-console/bin/catence-console users add martina --athlete martina
+
+# Non-interactive: read the password from an environment variable
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm -T \
+  -e CATENCE_CONSOLE_NEW_PASSWORD='…' \
+  --entrypoint /opt/catence-console/bin/catence-console console \
+  users add martina --athlete martina --password-env CATENCE_CONSOLE_NEW_PASSWORD
+```
+
+Before the first start there is no running container **and** no login yet —
+the Console refuses to start without one — so create the first account with
+the one-off form (it prompts for the password):
+
+```sh
+docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env run --rm \
+  --entrypoint /opt/catence-console/bin/catence-console console users add coach --admin
+```
+
+Roles: `admin` sees every athlete; `member` sees only explicitly granted
+athletes. A member with zero grants can sign in and browse, but has no athlete
+to scope a chat to. The environment pair is a never-persisted break-glass
+admin: it keeps working when the accounts file is lost or the last admin is
+locked out, and unsetting the two variables revokes it.
+
+Accounts gate the Console only. The MCP server keeps its own contract — no
+authentication, the caller's `athleteId` is trusted — so port 8787 still needs
+loopback or network-layer restriction (see
+[Connecting to the Docker-based MCP from outside](#connecting-to-the-docker-based-mcp-from-outside)).
+
+The accounts file is the only copy of your stored logins: keep it in backups
+of the data volume (or bind-mounted home), along with `config.json` and the
+athlete stores.
+
 ## 3. Initialize an athlete store
 
 The data volume already contains a seeded `config.json`, so `setup` accepts
@@ -184,8 +256,9 @@ export OPENCODE_GO_API_KEY='…'                      # any non-empty value pass
 ## 7. Access the Console
 
 Open `http://127.0.0.1:8000` (or the `--bind:--port` you configured) and log in
-with `CATENCE_CONSOLE_USERNAME` and the password whose hash is in
-`CATENCE_CONSOLE_PASSWORD_HASH`.
+with a stored Console account (see [Console accounts](#console-accounts)) or
+with the environment break-glass pair (`CATENCE_CONSOLE_USERNAME` and the
+password whose hash is in `CATENCE_CONSOLE_PASSWORD_HASH`).
 
 ## 8. Verify with doctor
 
@@ -472,11 +545,17 @@ docker run --rm -it -v catence-data:/data --entrypoint catence-data catence-cons
 
 Use the same `--entrypoint catence-data` pattern for `secret set` and `sync`.
 
+Console logins work the same way: keep the environment pair together (or
+neither variable), or seed a stored account into the volume with the `users`
+command (see [Console accounts](#console-accounts)).
+
 ## Updating
 
 Docker deployments: re-run `deploy-console.sh beta` (or `stable`); it
 re-resolves the newest versions from the registries and rebuilds. The data
-volume and your `config.json` are preserved.
+volume is preserved, so your `config.json`, the stored Console accounts
+(`console/accounts.json`), chat history, and the athlete stores all survive
+the rebuild.
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/rifusaki/catence/beta/scripts/deploy-console.sh | bash -s beta

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
 
@@ -143,6 +158,68 @@ origin, shows live progress while the run is active, and displays the last
 completed sync afterwards. Each manual sync also refreshes OpenCode Go model
 profiles first; a discovery failure never blocks the data sync.
 
+## Console 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
 
 `catence-console serve` accepts:
@@ -167,12 +244,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.
@@ -260,4 +343,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
 

package/package.json

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

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({