config: drop the cross-process config.toml lock and filelock dependency

The filelock-based serialization of config.toml's read-modify-write was a
recurring source of Windows CI flakiness, and the lost-update race it closed
(two concurrent `assembly` processes clobbering each other's profile/telemetry
writes) isn't worth that cost for a single-user CLI. Remove core/config_lock.py,
core/locking.py, and the filelock dependency.

Writes still go through a load -> mutate -> dump (now config._update) whose
_dump does a temp-file + atomic os.replace, so a reader never sees a torn file;
writers and readers are otherwise unsynchronized (last write wins). The Windows
os.replace sharing-window retry (config._retry_on_sharing_violation) stays, since
the lock-free read/replace race it guards is independent of the removed lock.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JrDRFsdAYyXwWSudM2da8g

Author: claude

aai_cli/AGENTS.md

@@ -34,7 +34,7 @@ between layers is enforced — higher may import lower, never the reverse:
   `config_builder`, `keyring_store`, `environments`, `env`, `errors`, `llm`,
   `telemetry`, `debuglog`, `remotefs`, `sync_stt`, `signals`, `ws`, `youtube`,
   `wer`, `argscan`, `jsonshape`, `timeparse`, `microphone`, `procs`, `stdio`,
-  `choices`, `locking`, `config_lock`. Contract 4 also forbids `rich` here, so
+  `choices`. Contract 4 also forbids `rich` here, so
   "no Rich below the UI layer" is structural.
 
 Three things sit *beside* the stack, intentionally unlisted in the layers
@@ -139,7 +139,7 @@ heavily-reworked commands with long bodies; small commands keep the inline
 ### Cross-cutting state (resolution order matters)
 
 - **`app/context.py`** — `AppState` (profile, env) is attached to the Typer context in the root `@app.callback()`. `run_command` is the standard command wrapper.
-- **`core/config.py`** — profiles persisted in `config.toml` (via `platformdirs`); the **API key lives only in the OS keyring**, never in a dotfile. The keyring access itself is factored into **`core/keyring_store.py`** (the single importer of `keyring`, holding `KEYRING_SERVICE = "assemblyai-cli"` + `set_secret`/`get_secret`/`restore_secret`/`delete_secret`/`usable`), so the "secrets never touch the dotfile" split is structural; `config` reads/writes secrets through it and only `config.keyring_usable` re-surfaces the probe on the auth facade. Key resolution order: `--api-key` flag (validation paths only) → `ASSEMBLYAI_API_KEY` env → keyring. **Run commands deliberately expose no `--api-key` flag** so keys can't leak into `ps`/shell history. Every `config.toml` write is a read-modify-write (`_load` → mutate → `_dump`): `_dump` is a temp-file + atomic `os.replace` (a reader never sees a torn file), and the whole RMW runs under a cross-process `filelock` (`config_lock.update`/`.locked`, built on `core/locking.py`) so two concurrent `assembly` processes can't lose each other's updates. Readers stay lock-free. The lock helpers live in `config_lock.py` (not `config.py`) only to keep the latter under the file-length gate; reuse one cached `FileLock` per path so nested writers (`persist_login`) stay reentrant.
+- **`core/config.py`** — profiles persisted in `config.toml` (via `platformdirs`); the **API key lives only in the OS keyring**, never in a dotfile. The keyring access itself is factored into **`core/keyring_store.py`** (the single importer of `keyring`, holding `KEYRING_SERVICE = "assemblyai-cli"` + `set_secret`/`get_secret`/`restore_secret`/`delete_secret`/`usable`), so the "secrets never touch the dotfile" split is structural; `config` reads/writes secrets through it and only `config.keyring_usable` re-surfaces the probe on the auth facade. Key resolution order: `--api-key` flag (validation paths only) → `ASSEMBLYAI_API_KEY` env → keyring. **Run commands deliberately expose no `--api-key` flag** so keys can't leak into `ps`/shell history. Every `config.toml` write is a read-modify-write (`_load` → mutate → `_dump`) via the `config._update` context manager: `_dump` is a temp-file + atomic `os.replace`, so a reader never sees a torn file. Writers and readers are otherwise unsynchronized — last write wins (there is **no** cross-process lock; an earlier `filelock`-based serialization was removed because it was a recurring Windows CI flake and the lost-update race it closed isn't worth the cost for a single-user CLI). On Windows the atomic replace has no replace-over-open guarantee, so both the lock-free read and the `os.replace` ride out the transient `PermissionError` through `config._retry_on_sharing_violation` (a no-op on POSIX).
 - **`core/environments.py`** — a frozen `Environment` (api_base, streaming_host, llm_gateway_base, ams_base, stytch_*). `DEFAULT_ENV` is **`production`**; use `--sandbox` (or `--env sandbox000` / `AAI_ENV`) to target the sandbox. The active environment is a process-global set once at startup; precedence: `--env` → `AAI_ENV` → profile's stored env → default. A credential is only valid against the environment that minted it.
 - **`core/client.py`** — thin wrappers over the `assemblyai` SDK (`transcribe`, `list_transcripts`, `stream_audio`, etc.). It normalizes SDK exceptions: auth failures become a single clean `auth_failure()` `CLIError`; everything else becomes `APIError`. New SDK calls should follow this try/except shape.
 - **`core/errors.py`** — the `CLIError` hierarchy (each with `error_type` + `exit_code`). `ui/output.py` emits errors to **stderr**; stdout stays clean for pipelines. `--json` switches to machine-readable output; it is never auto-enabled — `output.resolve_json()` deliberately keeps human text the default even when piped or agent-run.

aai_cli/core/config.py

@@ -8,14 +8,14 @@
 import time
 import tomllib
 import uuid
-from collections.abc import Callable
+from collections.abc import Callable, Generator
 from pathlib import Path
 
 import platformdirs
 import tomli_w
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
-from aai_cli.core import config_lock, debuglog, env, keyring_store
+from aai_cli.core import debuglog, env, keyring_store
 from aai_cli.core.errors import CLIError, NotAuthenticated
 
 ENV_API_KEY = "ASSEMBLYAI_API_KEY"
@@ -193,6 +193,17 @@ def _dump(cfg: Config) -> None:
         raise
 
 
+@contextlib.contextmanager
+def _update() -> Generator[Config]:
+    """Run a config.toml read-modify-write: ``_load`` -> mutate the yielded config ->
+    ``_dump``. The dump runs on clean exit; an exception in the block propagates and
+    skips it. The atomic os.replace in ``_dump`` keeps a reader from ever seeing a torn
+    file (writers and readers are otherwise unsynchronized: last write wins)."""
+    cfg = _load()
+    yield cfg
+    _dump(cfg)
+
+
 def get_active_profile() -> str:
     return _load().active_profile or DEFAULT_PROFILE
 
@@ -210,7 +221,7 @@ def set_active_profile(name: str) -> None:
     with no hint why, so the typo is rejected here with the known names listed.
     """
     validate_profile(name)
-    with config_lock.update(_load, _dump) as cfg:
+    with _update() as cfg:
         if name not in cfg.profiles:
             known = ", ".join(sorted(cfg.profiles)) or "none yet"
             raise CLIError(
@@ -225,7 +236,7 @@ def set_active_profile(name: str) -> None:
 def set_api_key(profile: str, api_key: str) -> None:
     validate_profile(profile)
     keyring_store.set_secret(profile, api_key)
-    with config_lock.update(_load, _dump) as cfg:
+    with _update() as cfg:
         cfg.profiles.setdefault(profile, Profile())
         if cfg.active_profile is None:
             cfg.active_profile = profile
@@ -255,7 +266,7 @@ def get_profile_env(profile: str) -> str | None:
 def set_profile_env(profile: str, env: str) -> None:
     """Bind a backend environment to a profile so its key and hosts stay matched."""
     validate_profile(profile)
-    with config_lock.update(_load, _dump) as cfg:
+    with _update() as cfg:
         cfg.profiles.setdefault(profile, Profile()).env = env
 
 
@@ -268,7 +279,7 @@ def get_profile_email(profile: str) -> str | None:
 def set_profile_email(profile: str, email: str) -> None:
     """Persist the login email for a profile (gates internal-environment access)."""
     validate_profile(profile)
-    with config_lock.update(_load, _dump) as cfg:
+    with _update() as cfg:
         cfg.profiles.setdefault(profile, Profile()).email = email
 
 
@@ -294,7 +305,7 @@ def set_session(profile: str, *, session_jwt: str, session_token: str, account_i
         _session_username(profile),
         StoredSession(jwt=session_jwt, token=session_token).model_dump_json(),
     )
-    with config_lock.update(_load, _dump) as cfg:
+    with _update() as cfg:
         cfg.profiles.setdefault(profile, Profile()).account_id = account_id
 
 
@@ -318,12 +329,11 @@ def get_account_id(profile: str) -> int | None:
 
 def clear_session(profile: str) -> None:
     keyring_store.delete_secret(_session_username(profile))
-    with config_lock.locked():
-        cfg = _load()
-        prof = cfg.profiles.get(profile)
-        if prof and prof.account_id is not None:
-            prof.account_id = None
-            _dump(cfg)
+    cfg = _load()
+    prof = cfg.profiles.get(profile)
+    if prof and prof.account_id is not None:
+        prof.account_id = None
+        _dump(cfg)
 
 
 def persist_login(
@@ -346,32 +356,29 @@ def persist_login(
     restored best-effort.
     """
     validate_profile(profile)
-    # Hold the write lock across the whole snapshot -> writes -> rollback so a concurrent
-    # writer can't slip a change between the snapshot and a rollback dump. The set_*
-    # helpers re-take the same (reentrant) lock, so the nesting is safe.
-    with config_lock.locked():
-        prior_api_key = keyring_store.get_secret(profile)
-        prior_session = keyring_store.get_secret(_session_username(profile))
-        prior_cfg = _load()
-        done = False
-        try:
-            set_api_key(profile, api_key)
-            set_profile_env(profile, env)
-            set_session(
-                profile,
-                session_jwt=session_jwt,
-                session_token=session_token,
-                account_id=account_id,
-            )
-            # Within the same atomic rollback so the sandbox gate can't read stale identity.
-            if email is not None:
-                set_profile_email(profile, email)
-            done = True
-        finally:
-            if not done:
-                keyring_store.restore_secret(profile, prior_api_key)
-                keyring_store.restore_secret(_session_username(profile), prior_session)
-                _dump(prior_cfg)
+    # Snapshot the prior state so a mid-sequence failure rolls back cleanly to it.
+    prior_api_key = keyring_store.get_secret(profile)
+    prior_session = keyring_store.get_secret(_session_username(profile))
+    prior_cfg = _load()
+    done = False
+    try:
+        set_api_key(profile, api_key)
+        set_profile_env(profile, env)
+        set_session(
+            profile,
+            session_jwt=session_jwt,
+            session_token=session_token,
+            account_id=account_id,
+        )
+        # Within the same atomic rollback so the sandbox gate can't read stale identity.
+        if email is not None:
+            set_profile_email(profile, email)
+        done = True
+    finally:
+        if not done:
+            keyring_store.restore_secret(profile, prior_api_key)
+            keyring_store.restore_secret(_session_username(profile), prior_session)
+            _dump(prior_cfg)
 
 
 def has_device_id() -> bool:
@@ -385,12 +392,11 @@ def get_device_id() -> str:
     """A stable anonymous install id for telemetry: a random UUID minted locally on
     first use and persisted in config.toml. Carries nothing derivable from the
     machine or account."""
-    with config_lock.locked():
-        cfg = _load()
-        if cfg.device_id is None:
-            cfg.device_id = str(uuid.uuid4())
-            _dump(cfg)
-        return cfg.device_id
+    cfg = _load()
+    if cfg.device_id is None:
+        cfg.device_id = str(uuid.uuid4())
+        _dump(cfg)
+    return cfg.device_id
 
 
 def get_telemetry_enabled() -> bool | None:
@@ -400,7 +406,7 @@ def get_telemetry_enabled() -> bool | None:
 
 
 def set_telemetry_enabled(*, enabled: bool) -> None:
-    with config_lock.update(_load, _dump) as cfg:
+    with _update() as cfg:
         cfg.telemetry_enabled = enabled
 
 
@@ -413,7 +419,7 @@ def get_update_cache() -> tuple[float | None, str | None]:
 def set_update_cache(*, last_check: float, latest_version: str | None) -> None:
     """Persist the update-notifier cache. ``latest_version`` is None when the last
     fetch failed — the timestamp is still recorded so we don't re-spawn every run."""
-    with config_lock.update(_load, _dump) as cfg:
+    with _update() as cfg:
         cfg.update_last_check = last_check
         cfg.update_latest_version = latest_version
 

aai_cli/core/config_lock.py

@@ -65,11 +65,6 @@ dependencies = [
     # lazily). Strips boilerplate down to the readable body; ships prebuilt wheels
     # (lxml included), so it adds no source-compile step to Homebrew bottling.
     "trafilatura>=2.1.0",
-    # Cross-process advisory lock around config.toml's read-modify-write (config.py),
-    # so two concurrent `assembly` processes can't lose each other's profile/telemetry
-    # updates (last-writer-wins). Pure-Python, no compiled deps; already arrived
-    # transitively via the dev toolchain, so the lock pins the same release.
-    "filelock>=3.16.0",
 ]
 
 [project.urls]

aai_cli/core/locking.py

@@ -3,11 +3,10 @@
 Two real concurrency surfaces exist in the CLI, and neither was directly exercised:
 
 1. ``core.config`` persists ``config.toml`` with a temp-file + atomic ``os.replace``
-   (`config._dump`) so a reader never observes a truncated file, and serializes its
-   read-modify-write under a cross-process ``filelock`` (`config._write_lock`) so two
-   concurrent ``assembly`` processes can't lose each other's updates. These tests pin
-   both: the at-rest atomicity under thread contention, and that distinct concurrent
-   updates all survive (no last-writer-wins clobber).
+   (`config._dump`) so a reader never observes a truncated file. Writers and readers are
+   otherwise unsynchronized (last write wins), and on Windows the replace window is ridden
+   out by a small retry (`config._retry_on_sharing_violation`). These tests pin the at-rest
+   atomicity under thread contention and that retry helper.
 2. ``streaming.StreamSession.on_turn`` runs on the SDK reader thread, and the
    ``--system-audio`` path drives two of those threads at once (`session._drive`). The
    turn write is serialized by ``_callback_lock`` so two sources can't interleave a
@@ -22,7 +21,7 @@
 
 import pytest
 
-from aai_cli.core import config, config_lock
+from aai_cli.core import config
 
 # --- config.toml: the Windows os.replace sharing-window retry -----------------------
 
@@ -112,58 +111,6 @@ def reader() -> None:
     assert sorted(p.name for p in tmp_config.iterdir()) == ["config.toml"]  # no temp leftover
 
 
-def test_concurrent_writers_do_not_lose_distinct_updates(tmp_config):
-    # The cross-process write lock makes the read-modify-write atomic, so many threads
-    # each adding a DISTINCT profile through the public API all survive. Without the lock
-    # the interleaved RMW would drop some (two writers _load the same config; the second
-    # _dump clobbers the first's new profile) — this is the lost-update race the lock closes.
-    workers = 16
-    barrier = threading.Barrier(workers)  # release all writers at once for max contention
-
-    def add(i: int) -> None:
-        barrier.wait()
-        config.set_profile_env(f"p{i:02d}", f"sandbox{i:03d}")
-
-    with ThreadPoolExecutor(max_workers=workers) as pool:
-        for f in [pool.submit(add, i) for i in range(workers)]:
-            f.result()
-
-    # Every concurrent update is present with its own value — none clobbered.
-    assert config.list_profiles() == {f"p{i:02d}": f"sandbox{i:03d}" for i in range(workers)}
-
-
-def test_write_lock_targets_the_config_dir_lock_file(tmp_config):
-    # The lock guards config.toml via a sibling lock file in the same dir.
-    assert config_lock.write_lock().lock_file == str(tmp_config / "config.toml.lock")
-
-
-def test_write_lock_rebuilds_when_config_dir_changes(monkeypatch, tmp_path):
-    # The instance is cached per path, but a changed config dir (the suite repoints it per
-    # test) must yield a fresh lock pointed at the new dir — not the stale one.
-    first = config_lock.write_lock()
-    moved = tmp_path / "moved"
-    moved.mkdir()
-    monkeypatch.setattr(config, "config_dir", lambda: moved)
-    second = config_lock.write_lock()
-    assert second is not first
-    assert second.lock_file == str(moved / "config.toml.lock")
-
-
-def test_update_holds_the_write_lock_during_the_dump(tmp_config, monkeypatch):
-    # The mutate -> dump runs inside the lock: while _dump executes, the lock is held.
-    # (Drop the `with locked()` and is_locked would be False here.)
-    seen: dict[str, bool] = {}
-    real_dump = config._dump
-
-    def spy_dump(cfg):
-        seen["locked"] = config_lock.write_lock().is_locked
-        return real_dump(cfg)
-
-    monkeypatch.setattr(config, "_dump", spy_dump)
-    config.set_profile_env("default", "sandbox000")
-    assert seen["locked"] is True
-
-
 # --- streaming: on_turn serialization under _callback_lock -------------------------