cdx-manager 0.21.5 → 0.21.6

package/README.md

@@ -4,7 +4,7 @@
 
 <br clear="left"/>
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.21.5-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.21.6-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **The right AI coding account, when you need it.** CDX Manager keeps your Codex and Claude accounts in separate profiles, shows which ones have quota, and helps you pick the next usable session from your terminal.
 

package/VERSION

@@ -1 +1 @@
-0.21.5
+0.21.6

package/changelogs/CHANGELOGS_0_21_6.md

@@ -0,0 +1,33 @@
+# CDX Manager 0.21.6
+
+## Security
+
+- **Windows toasts.** PowerShell also ends a single-quoted string on the typographic quotes ‘ ’ ‚ ‛, so those are now escaped too, in cdx and in the tray. A crafted folder name or response preview could run code. French text such as "l’agent" no longer drops the toast (#23).
+- **Tray over WSL.** The tray no longer passes its commands through the WSL shell, which expanded `$(...)` and split arguments containing spaces. It also finds the user's own `cdx` instead of a stale system-wide one (#23).
+- **`cdx set <name> --scrub-env on`** launches Claude with `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1`. The Bash commands, hooks and MCP servers the agent starts then no longer receive credentials, including the setup-token. It is off by default; `docs/operations.md` explains the trade-off (#26).
+- **Backup bundles that include auth** use a stronger key derivation (scrypt N=2^17, or PBKDF2 at 600k iterations) and record its cost. Older bundles still import, and a crafted cost is refused (#25).
+- **Claude profile creation** no longer replaces an unparseable or symlinked `settings.json`, and keeps its permissions (#23).
+- **PyPI** releases are published with Trusted Publishing, without a stored API token (#27).
+
+## Fixes
+
+- **Windows:**
+  - `cdx.cmd` now returns the real exit code; it always returned 0;
+  - `cdx ready` schedules its task on any Windows language, where `schtasks` refused the date on non-US systems;
+  - provider output is read as UTF-8;
+  - `cdx -v` and `--help` work without a home directory;
+  - the check after `cdx update` no longer prints "Could not determine home directory" (#22, #23).
+- **`cdx run`** stops the provider when it receives SIGTERM or SIGHUP (a `kill`, a `systemctl stop` or a closed SSH session), not only on Ctrl+C (#24).
+- **No more lost writes when two commands overlap:**
+  - tray events published while another is being acknowledged are kept;
+  - `cdx context set` and `clear` no longer race with an append (#24).
+- **`cdx set`:**
+  - the usage line, help and docs list every flag;
+  - a bad on/off value names the flag, for example "Unsupported notify value: maybe (on|off)" (#25).
+- **`cdx schema --json`** publishes every run error code and warning code. `cdx run` sets its error codes at the source instead of reading the message text (#25).
+
+## Housekeeping
+
+- CI also tests Python 3.9, the minimum version declared in pyproject.
+- The tray builds with `cargo --locked`.
+- The test suite no longer touches the developer's real macOS keychain (#24, #25).

package/checksums/release-archives.json

@@ -529,6 +529,17 @@
         "x86_64-pc-windows-msvc": "0d4e6c736a789d8fddaf688cd61d899a305171fa6d7e856735b2cd7d2daef21c",
         "x86_64-unknown-linux-musl": "8320025507801fd549b8c8dd4196a9378ddb25f137e48945e61e429bf2a864aa"
       }
+    },
+    "v0.21.5": {
+      "github_tarball_sha256": "5a45b3ba4df72a4bba5bbd8c8c28728f7e804c67a4a7201d927f350d0276f432",
+      "github_zip_sha256": "b53d281da3540b85745a9b1e8abbdec797a0e97c1e1ec098d8c98753ffc334c2",
+      "tray_assets": {
+        "aarch64-apple-darwin": "e97c99054653a209b84190c2f08d3b1739527dc8e1d4795dd4b51271096fcdc7",
+        "aarch64-unknown-linux-musl": "04cfad61af12263eaa82f3b1fec12c8fad87762dc7a95b42e170f868156829e1",
+        "x86_64-apple-darwin": "b7a3beb55f34a9fae182ec164152d3295bf078a354c2788296c63c7c268c686e",
+        "x86_64-pc-windows-msvc": "d107e75e7700c2fcc7138d6bc14cdf6929fb3ad3e3d7a5b8648f44828f4ab4bb",
+        "x86_64-unknown-linux-musl": "00d93b4f16b58c203fbdc8cf80b15f1402ebf3fef8568162505142a3adb20272"
+      }
     }
   }
 }

package/docs/cli.md

@@ -23,8 +23,8 @@
 | `cdx config <name> [--json]` | Show persistent launch settings for a session |
 | `cdx configs [--json]` | Show persistent launch settings for all sessions in one table |
 | `cdx power\|perm\|fast\|model <name\|all\|provider:PROVIDER\|a,b> <value\|default> [--json]` | Shortcut commands for setting or clearing one launch setting |
-| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power minimal\|low\|medium\|high\|xhigh] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--logics on\|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
-| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--permission\|--fast\|--rtk\|--logics\|--model\|--fallback-model\|--budget\|--extra-args\|--priority\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
+| `cdx set <name>\|--sessions all\|a,b\|--provider PROVIDER [--power minimal\|low\|medium\|high\|xhigh] [--permission review\|default\|auto\|full] [--fast on\|off] [--rtk on\|off] [--logics on\|off] [--notify on\|off] [--notify-preview on\|off] [--scrub-env on\|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]` | Persist launch settings for one or more sessions |
+| `cdx unset <name>\|--sessions all\|a,b\|--provider PROVIDER (--power\|--reasoning-effort\|--permission\|--fast\|--rtk\|--logics\|--notify\|--notify-preview\|--scrub-env\|--model\|--fallback-model\|--budget\|--extra-args\|--priority\|--all) [--json]` | Remove persisted launch settings and fall back to provider defaults |
 | `cdx history [name] [--limit N] [--summary] [--since 7d\|today\|DATE] [--from DATE] [--to DATE] [--json]` | Show recent launch history or aggregate total launch time per assistant, optionally filtered by period |
 | `cdx last [--json]` | Launch the most recent existing session from launch history |
 | `cdx resume <name> [--json]` | Resume the provider-native conversation for a session using the named command form |

package/docs/operations.md

@@ -152,6 +152,7 @@ credential sync.
 
 - **`cdx <name>` fails with "not authenticated"** — run `cdx login <name>` first. `cdx doctor` uses the same Codex app-server probe as `cdx auth refresh`, so a local auth file alone is never reported as live authentication; a rejected refresh token is reported as `login_required` with the matching login command.
 - **A Claude session has no claude.ai connectors (Microsoft 365, ...) in `/mcp`** — `cdx login <name>` stores a setup-token for Claude profiles, and Claude Code can only make model requests with it: it never loads claude.ai connectors. `cdx status` shows each Claude profile's auth type (`setup-token` or `full-login`; `auth_type` in `--json`). To switch, start the session and run `/login` inside it. Once the profile holds its own claude.ai login (its `.claude/.credentials.json`, or its profile-specific `Claude Code-credentials-<hash>` keychain entry on macOS), cdx stops passing the setup-token on later launches. If that login later expires, run `/login` again, or go back to a setup-token with `cdx login <name>`, which removes the profile's `/login`.
+- **Keep credentials away from what a Claude agent runs** — by default Claude Code passes its credentials, including the setup-token cdx injects, to the Bash commands, hooks and stdio MCP servers it starts. `cdx set <name> --scrub-env on` launches that session with `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1`, which strips credential-looking variables from those subprocesses (GitHub tokens and proxy settings stay). It is off by default: it also removes other secrets an agent may need (`NPM_TOKEN`, a `DATABASE_URL` with a password), and on Linux it isolates Bash from host processes, so `ps` and `kill` no longer see them. Worth turning on for unattended sessions that read untrusted content.
 - **One of two Codex accounts keeps asking for login** — run `cdx doctor --json` and inspect each Codex session's `codex_auth_file`, `codex_live_auth`, and `codex_stale_auth_logs` checks. If recent logs mention expired auth, repair only that isolated profile with `cdx login <name>`. Codex Business profiles can share the same `tokens.account_id`; `cdx doctor` reports `codex_shared_account_id` as a workspace-level clue, not proof that two profiles use the same user. Newly created sessions seed from the current global `~/.codex/auth.json` when one exists. For two separate Codex accounts, create or repair each session by running `cdx login <name>` for that session; `cdx login` does not log out first, so use `cdx logout <name>` explicitly only when you want to clear that isolated profile.
 - **`cdx` says no compatible Python 3 interpreter was found** — install Python 3 and make `py -3`, `python`, or `python3` available on PATH.
 - **`cdx add` succeeds but the session does not appear** — check that `CDX_HOME` is consistent between calls; a mismatch creates two separate registries.

package/install.ps1

@@ -90,15 +90,18 @@ try {
     Copy-Item -Path (Join-Path $sourceDir.FullName "*") -Destination $targetDir -Recurse -Force
 
     $launcherPath = Join-Path $binDir "cdx.cmd"
+    # No parenthesized block: cmd expands %ERRORLEVEL% when it parses a block,
+    # before py runs, so `exit /b %ERRORLEVEL%` inside one always returned 0.
     $launcher = @"
 @echo off
 set SCRIPT=%~dp0..\versions\$versionDir\bin\cdx
 where py >nul 2>nul
-if %ERRORLEVEL%==0 (
-  py -3 "%SCRIPT%" %*
-  exit /b %ERRORLEVEL%
-)
+if errorlevel 1 goto nopy
+py -3 "%SCRIPT%" %*
+exit /b %ERRORLEVEL%
+:nopy
 python "%SCRIPT%" %*
+exit /b %ERRORLEVEL%
 "@
     Set-Content -Path $launcherPath -Value $launcher -Encoding ascii
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.21.5",
+  "version": "0.21.6",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cdx-manager"
-version = "0.21.5"
+version = "0.21.6"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/agent_notify.py

@@ -486,7 +486,7 @@ def _subprocess_spawn_sync(command, args, options):
         [command, *args],
         env=options.get("env"),
         capture_output=True,
-        text=True,
+        text=True, encoding="utf-8", errors="replace",
         timeout=60,
     )
 

package/src/backup_bundle.py

@@ -11,10 +11,16 @@ BUNDLE_SCHEMA_VERSION = 1
 _SALT_BYTES = 16
 _NONCE_BYTES = 16
 _AEAD_NONCE_BYTES = 12
-_SCRYPT_N = 2 ** 14
-_SCRYPT_R = 8
-_SCRYPT_P = 1
-_PBKDF2_ITERATIONS = 200000
+# New bundles record their KDF cost in `kdf_params`, at OWASP-level costs
+# (scrypt N=2^17, PBKDF2-SHA256 600k). Bundles without the field were written
+# at the earlier costs, which stay readable. Recorded costs are capped so a
+# crafted bundle cannot make an import burn minutes of CPU or gigabytes of RAM.
+_SCRYPT_PARAMS = {"n": 2 ** 17, "r": 8, "p": 1}
+_PBKDF2_PARAMS = {"iterations": 600000}
+_LEGACY_SCRYPT_PARAMS = {"n": 2 ** 14, "r": 8, "p": 1}
+_LEGACY_PBKDF2_PARAMS = {"iterations": 200000}
+_MAX_SCRYPT_N = 2 ** 20
+_MAX_PBKDF2_ITERATIONS = 10_000_000
 _AEAD_ALGORITHM = "aes-256-gcm"
 _LEGACY_ALGORITHM = "sha256-xor-hmac"
 _KDF_SCRYPT = "scrypt"
@@ -78,19 +84,49 @@ def _bundle_kdf_candidates(wrapper):
     return [recorded]
 
 
-def _derive_key_material(passphrase, salt, kdf):
+def _default_params(kdf):
+    return dict(_SCRYPT_PARAMS if kdf == _KDF_SCRYPT else _PBKDF2_PARAMS)
+
+
+def _bundle_kdf_params(wrapper, kdf):
+    """The recorded cost, or the pre-`kdf_params` cost for older bundles."""
+    recorded = wrapper.get("kdf_params")
+    if recorded is None:
+        return dict(_LEGACY_SCRYPT_PARAMS if kdf == _KDF_SCRYPT else _LEGACY_PBKDF2_PARAMS)
+    if not isinstance(recorded, dict) or ("n" in recorded) != (kdf == _KDF_SCRYPT):
+        return None  # recorded for the other KDF: not this candidate
+    try:
+        if kdf == _KDF_SCRYPT:
+            params = {key: int(recorded[key]) for key in ("n", "r", "p")}
+            valid = (2 <= params["n"] <= _MAX_SCRYPT_N and params["n"] & (params["n"] - 1) == 0
+                     and 1 <= params["r"] <= 32 and 1 <= params["p"] <= 16)
+        else:
+            params = {"iterations": int(recorded["iterations"])}
+            valid = 1 <= params["iterations"] <= _MAX_PBKDF2_ITERATIONS
+    except (TypeError, ValueError, KeyError):
+        valid = False
+    if not valid:
+        raise CdxError("Unsupported bundle key derivation parameters.")
+    return params
+
+
+def _derive_key_material(passphrase, salt, kdf, params=None):
+    params = params or _default_params(kdf)
     if kdf == _KDF_SCRYPT:
         if not _available_kdf(_KDF_SCRYPT):
             raise CdxError(
                 "This bundle records the scrypt key derivation function, which this Python runtime "
                 "does not provide. Decode it with a Python built against OpenSSL scrypt support."
             )
+        n, r, p = params["n"], params["r"], params["p"]
         return hashlib.scrypt(
             passphrase,
             salt=salt,
-            n=_SCRYPT_N,
-            r=_SCRYPT_R,
-            p=_SCRYPT_P,
+            n=n,
+            r=r,
+            p=p,
+            # scrypt needs 128*r*n bytes; OpenSSL's 32 MiB default refuses N=2^17.
+            maxmem=2 * 128 * r * n * p + 1024 * 1024,
             dklen=64,
         )
     if kdf == _KDF_PBKDF2:
@@ -98,23 +134,23 @@ def _derive_key_material(passphrase, salt, kdf):
             "sha256",
             passphrase,
             salt,
-            _PBKDF2_ITERATIONS,
+            params["iterations"],
             dklen=64,
         )
     raise CdxError("Unsupported bundle key derivation function.")
 
 
-def _derive_keys(passphrase, salt, kdf=None):
+def _derive_keys(passphrase, salt, kdf=None, params=None):
     if not passphrase:
         raise CdxError("A non-empty passphrase is required for bundles that include auth data.")
     if isinstance(passphrase, str):
         passphrase = passphrase.encode("utf-8")
-    key_material = _derive_key_material(passphrase, salt, kdf or _default_kdf())
+    key_material = _derive_key_material(passphrase, salt, kdf or _default_kdf(), params)
     return key_material[:32], key_material[32:]
 
 
-def _derive_aead_key(passphrase, salt, kdf=None):
-    enc_key, _mac_key = _derive_keys(passphrase, salt, kdf)
+def _derive_aead_key(passphrase, salt, kdf=None, params=None):
+    enc_key, _mac_key = _derive_keys(passphrase, salt, kdf, params)
     return enc_key
 
 
@@ -152,11 +188,13 @@ def encode_bundle(payload, include_auth=False, passphrase=None):
         salt = os.urandom(_SALT_BYTES)
         nonce = os.urandom(_AEAD_NONCE_BYTES)
         kdf = _default_kdf()
-        aesgcm = _load_aesgcm()(_derive_aead_key(passphrase, salt, kdf))
+        params = _default_params(kdf)
+        aesgcm = _load_aesgcm()(_derive_aead_key(passphrase, salt, kdf, params))
         ciphertext = aesgcm.encrypt(nonce, payload_bytes, None)
         wrapper.update({
             "encryption": _AEAD_ALGORITHM,
             "kdf": kdf,
+            "kdf_params": params,
             "salt": _b64_encode(salt),
             "nonce": _b64_encode(nonce),
             "payload": _b64_encode(ciphertext),
@@ -186,9 +224,12 @@ def decode_bundle(data, passphrase=None):
             payload_bytes = None
             failure = None
             for kdf in kdf_candidates:
+                params = _bundle_kdf_params(wrapper, kdf)
+                if params is None:
+                    continue
                 # Derivation errors are about the bundle, not the passphrase, so
                 # they must escape rather than be retried as a bad secret.
-                cipher = aead(_derive_aead_key(passphrase, salt, kdf))
+                cipher = aead(_derive_aead_key(passphrase, salt, kdf, params))
                 try:
                     payload_bytes = cipher.decrypt(nonce, ciphertext, None)
                     break
@@ -200,7 +241,10 @@ def decode_bundle(data, passphrase=None):
             expected_mac = _b64_decode(wrapper.get("hmac_sha256", ""))
             payload_bytes = None
             for kdf in kdf_candidates:
-                enc_key, mac_key = _derive_keys(passphrase, salt, kdf)
+                params = _bundle_kdf_params(wrapper, kdf)
+                if params is None:
+                    continue
+                enc_key, mac_key = _derive_keys(passphrase, salt, kdf, params)
                 actual_mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
                 if hmac.compare_digest(actual_mac, expected_mac):
                     payload_bytes = _xor_keystream(ciphertext, enc_key, nonce)

package/src/claude_usage.py

@@ -214,7 +214,7 @@ def _refresh_claude_cli_credentials(auth_home, runner=None, env=None):
             command,
             env=run_env,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=CLAUDE_AUTH_STATUS_TIMEOUT_SECONDS,
             check=False,
         )

package/src/cli.py

@@ -6,6 +6,7 @@ import sys
 from datetime import datetime, timezone
 
 from .agent_notify import handle_notify
+from .cli_args import SET_USAGE
 from .cli_commands import (
     API_SCHEMA_VERSION,
     STATUS_USAGE,
@@ -247,7 +248,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx config <name> [--json]', '36', use_color)}",
         f"  {_style('cdx configs [--json]', '36', use_color)}",
         f"  {_style('cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]', '36', use_color)}",
-        f"  {_style('cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--notify on|off] [--notify-preview on|off] [--model MODEL] [--priority 0..100] [--json]', '36', use_color)}",
+        f"  {_style(SET_USAGE[len('Usage: '):], '36', use_color)}",
         f"  {_style('cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--model|--priority|--all) [--json]', '36', use_color)}",
         f"  {_style('cdx history [name] [--limit N] [--summary] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
         f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--json]', '36', use_color)}",
@@ -533,7 +534,6 @@ def main(argv, options=None):
     stderr = options.get("stderr", sys.stderr)
     stdin_is_tty = options.get("stdin", {}).get("isTTY", hasattr(sys.stdin, "isatty") and sys.stdin.isatty())
     use_color = _should_use_color(env, stdout)
-    service = options.get("service") or create_session_service({"env": env})
     spawn = options.get("spawn")
     spawn_sync = options.get("spawn_sync")
     refresh_fn = options.get("refreshClaudeSessionStatus")
@@ -559,6 +559,10 @@ def main(argv, options=None):
         out(f"{_print_version()}\n")
         return 0
 
+    # Built after --help/--version: those must answer even where the home
+    # directory cannot be resolved (a service or task with a minimal environment).
+    service = options.get("service") or create_session_service({"env": env})
+
     if argv == ["--json"]:
         rows = service["format_list_rows"]()
         notices = _get_update_notices(service, env, options)

package/src/cli_args.py

@@ -16,6 +16,7 @@ from .config import (
     PROVIDERS,
     REASONING_EFFORT_VALUES,
     normalize_permission,
+    parse_on_off,
 )
 from .errors import CdxArgumentError, CdxError
 from .provider_runtime import _normalize_reasoning_effort
@@ -32,8 +33,8 @@ CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set|append [text..
 MEMORY_USAGE = "Usage: cdx memory [--global|--project NAME_OR_PATH] [show|view|path|init|edit|clear|set|append|list] [text...] [--json]"
 HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--source-conversation ID | --source-native-transcript PATH | --source-transcript PATH] [--json]"
 LABEL_USAGE = "Usage: cdx label <name> <label> [--json] | cdx label <name> --clear [--json]"
-SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
-UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"
+SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--notify on|off] [--notify-preview on|off] [--scrub-env on|off] [--model MODEL] [--fallback-model MODEL[,MODEL...]] [--budget USD] [--extra-args 'ARGS'] [--priority 0..100] [--json]"
+UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--notify|--notify-preview|--scrub-env|--model|--fallback-model|--budget|--extra-args|--priority|--all) [--json]"
 SETTING_ALIAS_USAGE = "Usage: cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]"
 CONFIG_USAGE = "Usage: cdx config <name> [--json]"
 CONFIGS_USAGE = "Usage: cdx configs [--json]"
@@ -213,13 +214,12 @@ def _parse_toggle_args(args, usage):
     return {"name": parsed["names"][0], "json": parsed["json"]}
 
 
-def _parse_fast_value(value):
-    text = str(value).strip().lower()
-    if text in ("on", "true", "1", "yes"):
-        return True
-    if text in ("off", "false", "0", "no"):
-        return False
-    raise CdxError(SET_USAGE)
+def _parse_fast_value(value, label="fast"):
+    return parse_on_off(value, label)
+
+
+def _on_off(label):
+    return lambda value: parse_on_off(value, label)
 
 
 def _parse_priority_value(value):
@@ -248,10 +248,11 @@ def _parse_set_args(args):
         "--power": {"key": "power", "type": "str", "default": None},
         "--permission": {"key": "permission", "type": "str", "default": None},
         "--fast": {"key": "fast", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--logics": {"key": "logics", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--notify": {"key": "notify", "type": "str", "default": None, "transform": _parse_fast_value},
-        "--notify-preview": {"key": "notify_preview", "type": "str", "default": None, "transform": _parse_fast_value},
+        "--rtk": {"key": "rtk", "type": "str", "default": None, "transform": _on_off("rtk")},
+        "--logics": {"key": "logics", "type": "str", "default": None, "transform": _on_off("logics")},
+        "--notify": {"key": "notify", "type": "str", "default": None, "transform": _on_off("notify")},
+        "--notify-preview": {"key": "notify_preview", "type": "str", "default": None, "transform": _on_off("notify preview")},
+        "--scrub-env": {"key": "scrub_env", "type": "str", "default": None, "transform": _on_off("scrub env")},
         "--model": {"key": "model", "type": "str", "default": None},
         "--fallback-model": {"key": "fallback_model", "type": "str", "default": None},
         "--budget": {"key": "budget", "type": "str", "default": None, "transform": _parse_budget_value},
@@ -273,7 +274,7 @@ def _parse_set_args(args):
         raise CdxError(SET_USAGE)
     settings = {
         key: parsed[key]
-        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "model", "fallback_model", "budget", "extra_args", "priority")
+        for key in ("power", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env", "model", "fallback_model", "budget", "extra_args", "priority")
         if parsed[key] is not None
     }
     if not settings:
@@ -297,6 +298,7 @@ def _parse_unset_args(args):
         "--logics": {"key": "logics", "type": "bool", "default": False},
         "--notify": {"key": "notify", "type": "bool", "default": False},
         "--notify-preview": {"key": "notify_preview", "type": "bool", "default": False},
+        "--scrub-env": {"key": "scrub_env", "type": "bool", "default": False},
         "--model": {"key": "model", "type": "bool", "default": False},
         "--fallback-model": {"key": "fallback_model", "type": "bool", "default": False},
         "--budget": {"key": "budget", "type": "bool", "default": False},
@@ -318,7 +320,7 @@ def _parse_unset_args(args):
     if not parsed["names"] and not parsed["sessions"] and not parsed["provider"]:
         raise CdxError(UNSET_USAGE)
     _UNSET_KEYS = (
-        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "notify_preview",
+        "power", "reasoning_effort", "permission", "fast", "rtk", "logics", "notify", "notify_preview", "scrub_env",
         "model", "fallback_model", "budget", "extra_args", "priority",
     )
     keys = list(_UNSET_KEYS) if parsed["all"] else [key for key in _UNSET_KEYS if parsed[key]]
@@ -510,8 +512,14 @@ def cdx_schema():
                 "provider_start_failed",
                 "provider_failed",
                 "provider_timeout",
+                "run_cancelled",
+                "invalid_request",
                 "cdx_error",
             ],
+            # The error code on a run record the stale sweep closed.
+            "run_record": [
+                "stale_process",
+            ],
             "run_lookup": [
                 "run_not_found",
                 "run_output_unavailable",
@@ -522,6 +530,26 @@ def cdx_schema():
             "network_disabled_by_permission",
             "session_selected_without_status",
             "limit_ignored_with_since",
+            "claude_auth_probe_failed",
+            "claude_refresh_failed",
+            "disk_cleanup_available",
+            "update_available",
+            "logics_manager_update_available",
+            "update_version_check_failed",
+            "update_version_mismatch",
+            "logics_manager_missing",
+            "logics_viewer_failed",
+            "logics_viewer_root_invalid",
+            "tray_autostart_unsupported",
+            "tray_companion_missing",
+            "tray_companion_not_aligned",
+            "tray_companion_not_available",
+            "tray_companion_not_installed",
+            "tray_companion_restart_pending",
+            "tray_companion_updated",
+            "tray_plugin_action_unknown",
+            "tray_plugin_unknown",
+            "tray_terminal_invalid",
         ],
     }
 

package/src/cli_helpers.py

@@ -303,6 +303,7 @@ def _format_launch_config(session, use_color=False):
         ("logics", "Logics"),
         ("notify", "Agent alerts"),
         ("notify_preview", "Response preview"),
+        ("scrub_env", "Scrub agent env"),
         ("model", "Model"),
         ("fallback_model", "Fallback"),
         ("budget", "Budget"),
@@ -329,14 +330,14 @@ def _format_launch_settings_hint(name="<name>"):
     )
 
 def _format_launch_setting_value(launch, key, use_color=False):
-    if key in ("fast", "rtk", "logics", "notify", "notify_preview"):
+    if key in ("fast", "rtk", "logics", "notify", "notify_preview", "scrub_env"):
         if launch.get(key) is True:
             return _style("on", "32", use_color)
         if launch.get(key) is False:
             return _style("off", "2", use_color)
         if key == "logics":
             return _dim("auto", use_color)
-        if key in ("notify", "notify_preview"):
+        if key in ("notify", "notify_preview", "scrub_env"):
             return _style("off", "2", use_color)
         return _dim("default", use_color)
     value = launch.get(key)

package/src/codex_usage.py

@@ -247,7 +247,7 @@ def _request_codex_app_server(auth_home, method, params, failure_reason, timeout
             stdout=subprocess.PIPE,
             stderr=subprocess.DEVNULL,
             env=env,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             bufsize=1,
         )
         thread = threading.Thread(target=_reader_thread, args=(process.stdout, output), daemon=True)

package/src/commands/runs.py

@@ -265,7 +265,7 @@ def _spawn_detached_run(parsed, prompt, artifacts, ctx, session_name, cwd):
         # Surface as a CdxError so handle_run's own handler marks the already
         # registered run failed, instead of letting a raw OSError escape as an
         # unhandled traceback on a --json call.
-        raise CdxError(f"Failed to start detached cdx run: {error}", 126) from error
+        raise CdxError(f"Failed to start detached cdx run: {error}", 126, code="provider_start_failed") from error
     return {
         "pid": getattr(child, "pid", None),
         "launch_log_path": launch_log_path,
@@ -526,7 +526,7 @@ def handle_run(rest, ctx):
             if not session:
                 raise CdxError(f"Unknown session: {parsed['name']}")
             if session.get("enabled", True) is False:
-                raise CdxError(f"Session is disabled: {parsed['name']}")
+                raise CdxError(f"Session is disabled: {parsed['name']}", code="session_disabled")
         else:
             selected = _select_headless_session(
                 ctx,
@@ -552,7 +552,7 @@ def handle_run(rest, ctx):
 
         cwd = os.path.abspath(parsed["cwd"])
         if not os.path.isdir(cwd):
-            raise CdxError(f"Invalid cwd: {parsed['cwd']}")
+            raise CdxError(f"Invalid cwd: {parsed['cwd']}", code="invalid_cwd")
         prompt = read_run_prompt(parsed, stdin=ctx.get("prompt_stdin"))
         _consume_detached_prompt_file(parsed, detached_run_id)
         launch_updates = {}

package/src/config.py

@@ -81,4 +81,20 @@ def normalize_permission(value):
 def get_cdx_home(env=None):
     if env is None:
         env = os.environ
-    return env.get("CDX_HOME", str(Path.home() / ".cdx"))
+    # `or`, not a get() default: the default is evaluated eagerly, and
+    # Path.home() raises on Windows when USERPROFILE is missing.
+    return env.get("CDX_HOME") or str(Path.home() / ".cdx")
+
+
+def parse_on_off(value, label):
+    """Shared by `cdx set` flags and stored launch settings."""
+    from .errors import CdxError
+
+    if isinstance(value, bool):
+        return value
+    text = str(value).strip().lower()
+    if text in ("on", "true", "1", "yes"):
+        return True
+    if text in ("off", "false", "0", "no"):
+        return False
+    raise CdxError(f"Unsupported {label} value: {value} (on|off)")

package/src/context_store.py

@@ -90,7 +90,11 @@ def read_context_path(path):
 
 
 def write_context(base_dir, content, cwd=None):
-    return write_context_path(get_context_path(base_dir, cwd), content)
+    # Same lock as append: otherwise an append that read the old text can land
+    # after this write and resurrect it, or this write can drop the append.
+    path = get_context_path(base_dir, cwd)
+    with _append_lock(path), _registry_lock(path, timeout_seconds=10, label="memory"):
+        return write_context_path(path, content)
 
 
 def write_context_path(path, content):
@@ -155,11 +159,12 @@ def clear_context(base_dir, cwd=None):
 
 
 def clear_context_path(path):
-    try:
-        os.remove(path)
-        removed = True
-    except FileNotFoundError:
-        removed = False
+    with _append_lock(path), _registry_lock(path, timeout_seconds=10, label="memory"):
+        try:
+            os.remove(path)
+            removed = True
+        except FileNotFoundError:
+            removed = False
     return {"path": path, "removed": removed}
 
 

package/src/errors.py

@@ -1,7 +1,11 @@
 class CdxError(Exception):
-    def __init__(self, message, exit_code=1):
+    def __init__(self, message, exit_code=1, *, code=None):
         super().__init__(message)
         self.exit_code = exit_code
+        # Machine-readable code for `cdx run --json`; when absent, callers fall
+        # back to classifying the message (run_command.run_cdx_error_code).
+        if code is not None:
+            self.code = code
 
 
 class CdxArgumentError(CdxError):

package/src/health.py

@@ -162,7 +162,7 @@ def _run_version_command(command, env, spawn_sync=None):
             [command, "--version"],
             env=env,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=5,
             check=False,
         )
@@ -228,7 +228,7 @@ def _provider_help_text(command, env, spawn_sync=None):
                 text = f"{getattr(result, 'stdout', '') or ''}\n{getattr(result, 'stderr', '') or ''}"
         else:
             completed = subprocess.run(
-                [command, "--help"], env=env, capture_output=True, text=True, timeout=10, check=False,
+                [command, "--help"], env=env, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=10, check=False,
             )
             text = f"{completed.stdout or ''}\n{completed.stderr or ''}"
     except (OSError, subprocess.TimeoutExpired):

package/src/notify.py

@@ -215,8 +215,13 @@ def windows_aumid(env=None):
     return _POWERSHELL_AUMID
 
 
+# PowerShell also ends a single-quoted string on the typographic quotes
+# U+2018..U+201B, so each must be doubled like ASCII ' (French "l’agent").
+_POWERSHELL_QUOTES = "'\u2018\u2019\u201a\u201b"
+
+
 def _escape_powershell(value):
-    return str(value).replace("'", "''")
+    return "".join(ch * 2 if ch in _POWERSHELL_QUOTES else ch for ch in str(value))
 
 
 def _escape_applescript(value):
@@ -370,23 +375,23 @@ def _schedule_linux(parsed, event, argv, spawn_sync, env):
 def _schedule_windows_task(parsed, event, argv, spawn_sync, env):
     name = _schedule_id("cdx-manager-notify", parsed, event)
     target = datetime.fromtimestamp(event["target_timestamp"]).astimezone()
-    command = subprocess.list2cmdline([str(part) for part in argv])
-    result = _run_scheduler_command([
-        "schtasks",
-        "/Create",
-        "/SC",
-        "ONCE",
-        "/TN",
-        name,
-        "/TR",
-        command,
-        "/ST",
-        target.strftime("%H:%M"),
-        "/SD",
-        target.strftime("%m/%d/%Y"),
-        "/F",
-        "/Z",
-    ], spawn_sync, env)
+    # Not `schtasks /SD`: it reads the date in the user's locale format, so
+    # mm/dd/yyyy is refused on a dd/MM/yyyy (French) Windows. An invariant
+    # ISO date through Register-ScheduledTask works on every locale.
+    start = target.strftime("%Y-%m-%dT%H:%M")
+    end = (target + timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M")
+    arguments = subprocess.list2cmdline([str(part) for part in argv[1:]])
+    script = (
+        "$c = [Globalization.CultureInfo]::InvariantCulture; "
+        f"$t = New-ScheduledTaskTrigger -Once -At ([datetime]::ParseExact('{start}', 'yyyy-MM-ddTHH:mm', $c)); "
+        f"$t.EndBoundary = ([datetime]::ParseExact('{end}', 'yyyy-MM-ddTHH:mm', $c)).ToString('s'); "
+        f"$a = New-ScheduledTaskAction -Execute '{_escape_powershell(argv[0])}' -Argument '{_escape_powershell(arguments)}'; "
+        "$s = New-ScheduledTaskSettingsSet -DeleteExpiredTaskAfter (New-TimeSpan -Seconds 1); "
+        f"Register-ScheduledTask -TaskName '{_escape_powershell(name)}' -Action $a -Trigger $t -Settings $s -Force | Out-Null"
+    )
+    result = _run_scheduler_command(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", script], spawn_sync, env,
+    )
     if not result["ok"]:
         raise CdxError(f"Failed to schedule notification with Task Scheduler: {result['error']}")
     return {"scheduled": True, "existing": False, "backend": "schtasks", "id": name}

package/src/provider_background.py

@@ -107,7 +107,7 @@ def _default_spawn_sync(argv, env=None):
         completed = subprocess.run(
             argv,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=_CAPABILITY_PROBE_TIMEOUT_SECONDS,
             env=env,
             check=False,

package/src/provider_runtime.py

@@ -419,11 +419,11 @@ def _normalize_reasoning_effort(reasoning_effort=None, power=None, usage="Unsupp
     if alias == "":
         raise CdxError(usage)
     if effort and effort not in REASONING_EFFORT_VALUES:
-        raise CdxError(f"Unsupported reasoning effort: {reasoning_effort}")
+        raise CdxError(f"Unsupported reasoning effort: {reasoning_effort}", code="invalid_reasoning_effort")
     if alias and alias not in REASONING_EFFORT_VALUES:
         raise CdxError(f"Unsupported power: {power}")
     if effort and alias and effort != alias:
-        raise CdxError("--reasoning-effort and --power must match when both are provided.")
+        raise CdxError("--reasoning-effort and --power must match when both are provided.", code="invalid_reasoning_effort")
     resolved = effort or alias
     if not resolved:
         return {}
@@ -573,6 +573,19 @@ def _rtk_enabled(session):
     return (session.get("launch") or {}).get("rtk") is True
 
 
+# Claude Code passes credentials (including the setup-token cdx injects) to
+# the Bash commands, hooks and MCP servers it starts unless this is set. Opt-in:
+# it also strips other secrets an agent may need and, on Linux, isolates Bash
+# from host processes (`ps`, `kill`).
+CLAUDE_SCRUB_ENV = "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB"
+
+
+def _scrub_env(session):
+    if session.get("provider") == PROVIDER_CLAUDE and (session.get("launch") or {}).get("scrub_env") is True:
+        return {CLAUDE_SCRUB_ENV: "1"}
+    return {}
+
+
 def _logics_manager_available(path=None):
     return shutil.which("logics-manager", path=path) is not None
 
@@ -662,6 +675,7 @@ def _build_launch_spec(session, cwd=None, env_override=None, initial_prompt=None
     for key, value in _shared_tool_cache_overrides(env).items():
         env.setdefault(key, value)
     env.update(launch_notify_env(session, notifications_enabled(session)))
+    env.update(_scrub_env(session))
     preference_args = _launch_preference_args(session, env=env)
     if session["provider"] == PROVIDER_CLAUDE:
         launch = session.get("launch") or {}
@@ -915,6 +929,7 @@ def _build_headless_launch_spec(session, cwd=None, env_override=None, initial_pr
     # Headless runs read the same home, and so the same hooks, as an interactive
     # launch. Their caller already learns of completion from the return value.
     env.update(launch_notify_env(session, enabled=False))
+    env.update(_scrub_env(session))
     preference_args = _launch_preference_args(session, env=env)
     launch = session.get("launch") or {}
     power = _launch_power(session)
@@ -1056,6 +1071,32 @@ def _signal_child_group(child, sig):
         return False
 
 
+def _raise_keyboard_interrupt(_signum, _frame):
+    raise KeyboardInterrupt
+
+
+def _route_termination_to_interrupt():
+    """Make SIGTERM and SIGHUP raise KeyboardInterrupt; returns what to restore."""
+    previous = {}
+    for name in ("SIGTERM", "SIGHUP"):
+        sig = getattr(signal, name, None)
+        if sig is None:
+            continue
+        try:
+            previous[sig] = signal.signal(sig, _raise_keyboard_interrupt)
+        except (ValueError, OSError):  # not the main thread, or not settable here
+            pass
+    return previous
+
+
+def _restore_signal_handlers(previous):
+    for sig, handler in previous.items():
+        try:
+            signal.signal(sig, handler)
+        except (ValueError, OSError):
+            pass
+
+
 def _terminate_child_tree(child):
     if not _signal_child_group(child, signal.SIGTERM):
         try:
@@ -1111,14 +1152,18 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
             )
         except FileNotFoundError as error:
             _combine_headless_transcript(paths)
-            cdx_error = CdxError(f"{spec['label']} CLI not found on PATH: {spec['command']}", 127)
+            cdx_error = CdxError(f"{spec['label']} CLI not found on PATH: {spec['command']}", 127, code="provider_cli_not_found")
             cdx_error.run_info = _headless_run_info(paths, spec, start_time, 127)
             raise cdx_error from error
         except OSError as error:
             _combine_headless_transcript(paths)
-            cdx_error = CdxError(f"Failed to start {spec['label']}: {error}", 126)
+            cdx_error = CdxError(f"Failed to start {spec['label']}: {error}", 126, code="provider_start_failed")
             cdx_error.run_info = _headless_run_info(paths, spec, start_time, 126)
             raise cdx_error from error
+        # SIGTERM/SIGHUP (kill, systemctl stop, a closed SSH session) unwind
+        # like Ctrl+C: the provider's own process group would otherwise outlive
+        # this supervisor and keep its run "running" forever.
+        previous_handlers = _route_termination_to_interrupt()
         try:
             if timeout_seconds is None:
                 child.wait()
@@ -1136,6 +1181,8 @@ def _run_headless_provider_command(session, cwd=None, env_override=None, initial
             # the run still gets a terminal record.
             cancelled = True
             _terminate_child_tree(child)
+        finally:
+            _restore_signal_handlers(previous_handlers)
 
     if cancelled:
         _combine_headless_transcript(paths)
@@ -1283,7 +1330,7 @@ def _probe_provider_auth_status(session, spawn_sync=None, env_override=None, tru
             result = subprocess.run(
                 [command] + spec["args"],
                 env=spec["env"],
-                capture_output=True, text=True,
+                capture_output=True, text=True, encoding="utf-8", errors="replace",
                 timeout=AUTH_PROBE_TIMEOUT_SECONDS,
             )
             output = (result.stdout or "") + (result.stderr or "")

package/src/session_service.py

@@ -26,7 +26,6 @@ the re-exports as unused and callers importing through this module break.
 `test_session_service_facade_still_exposes_every_name_its_callers_import`
 guards that.
 """
-import json
 import os
 import shutil
 import tempfile
@@ -49,8 +48,11 @@ from .config import (
     normalize_permission,
     split_extra_args,
 )
+from .config import (
+    parse_on_off as _parse_on_off,
+)
 from .errors import CdxError
-from .fs_utils import atomic_write, remove_tree
+from .fs_utils import remove_tree
 from .session_backup import (  # noqa: F401  (re-exported for callers and tests)
     _FORCE_IMPORT_PRESERVED_PROFILE_PATHS,
     _auth_bundle_paths,
@@ -145,18 +147,7 @@ def _seed_codex_auth_from_global(auth_home, env=None):
     return True
 
 
-_ON_OFF_SETTINGS = {"fast": "fast", "rtk": "rtk", "logics": "logics", "notify": "notify", "notify_preview": "notify preview"}
-
-
-def _parse_on_off(value, label):
-    if isinstance(value, bool):
-        return value
-    text = str(value).strip().lower()
-    if text in ("on", "true", "1", "yes"):
-        return True
-    if text in ("off", "false", "0", "no"):
-        return False
-    raise CdxError(f"Unsupported {label} value: {value}")
+_ON_OFF_SETTINGS = {"fast": "fast", "rtk": "rtk", "logics": "logics", "notify": "notify", "notify_preview": "notify preview", "scrub_env": "scrub env"}
 
 
 def _has_control_chars(text):
@@ -175,7 +166,7 @@ def _normalize_launch_settings(settings, mark_fast_service_tier=True):
     if "reasoning_effort" in settings and settings["reasoning_effort"] is not None:
         effort = str(settings["reasoning_effort"]).strip().lower()
         if effort not in LAUNCH_REASONING_EFFORT_VALUES:
-            raise CdxError(f"Unsupported reasoning effort: {settings['reasoning_effort']}")
+            raise CdxError(f"Unsupported reasoning effort: {settings['reasoning_effort']}", code="invalid_reasoning_effort")
         normalized["reasoning_effort"] = effort
     if "permission" in settings and settings["permission"] is not None:
         # Accepts the provider-native aliases (workspace-write, read-only,
@@ -260,24 +251,18 @@ def _parse_status_timeout_seconds(value):
 
 
 def _ensure_claude_attribution_disabled(auth_home):
-    settings_dir = os.path.join(auth_home, ".claude")
-    settings_path = os.path.join(settings_dir, "settings.json")
-    try:
-        os.makedirs(settings_dir, exist_ok=True)
-        with open(settings_path, encoding="utf-8") as handle:
-            settings = json.load(handle)
-    except FileNotFoundError:
-        settings = {}
-    except (OSError, json.JSONDecodeError):
-        settings = {}
-    if not isinstance(settings, dict):
-        settings = {}
-    settings["includeCoAuthoredBy"] = False
-    try:
-        atomic_write(settings_path, json.dumps(settings, indent=2, sort_keys=True) + "\n", mode=0o644)
-    except OSError:
+    # Same reader/writer as the notification hooks: an unparseable file is the
+    # user's and is left alone, a symlink stays a symlink, the mode is kept.
+    from .agent_notify import _read_json, _write_json
+
+    settings_path = os.path.join(auth_home, ".claude", "settings.json")
+    settings = _read_json(settings_path)
+    if settings is None:
         return False
-    return True
+    if settings.get("includeCoAuthoredBy") is False:
+        return True
+    settings["includeCoAuthoredBy"] = False
+    return _write_json(settings_path, settings)
 
 
 def _normalize_session_label(label):
@@ -334,7 +319,7 @@ def unset_launch_settings(store, name, keys):
         raise CdxError("At least one launch setting is required.")
     allowed = {
         "power", "reasoning_effort", "reasoningEffort", "permission", "fast", "rtk", "logics", "notify", "notify_preview",
-        "model", "fallback_model", "budget", "extra_args", "priority",
+        "scrub_env", "model", "fallback_model", "budget", "extra_args", "priority",
     }
     unknown = [key for key in keys if key not in allowed]
     if unknown:
@@ -868,7 +853,7 @@ def launch_session(store, name, resume=False):
     if not session:
         raise CdxError(f"Unknown session: {name}")
     if session.get("enabled", True) is False:
-        raise CdxError(f"Session is disabled: {name}")
+        raise CdxError(f"Session is disabled: {name}", code="session_disabled")
     # Reconcile the prior Claude conversation before a fresh launch replaces
     # its id. This is a single exact transcript lookup, not a global stats scan.
     backfill_interactive_usage(store, name=name, dry_run=False)

package/src/tray_events.py

@@ -24,6 +24,8 @@ import json
 import os
 import time
 
+from .errors import CdxError
+
 SCHEMA_VERSION = 1
 # The tray heartbeats once per poll: 30s native, 60s across WSL. This window has
 # to clear the slowest of those with room for a late tick, or a live tray reads
@@ -130,12 +132,13 @@ def publish(base_dir, title, message, kind="complete", now=None, event_id=None,
         path = events_path(base_dir)
         os.makedirs(os.path.dirname(path), exist_ok=True)
         line = json.dumps(event, ensure_ascii=False) + "\n"
-        # O_APPEND makes this atomic against other hooks firing at the same
-        # instant, which a read-modify-write of a JSON array would not be.
-        with open(path, "a", encoding="utf-8") as handle:
+        # O_APPEND keeps concurrent hooks apart; the lock keeps this append
+        # out of acknowledge()'s read-and-replace, which would otherwise
+        # overwrite it and lose the notification.
+        with _spool_lock(path), open(path, "a", encoding="utf-8") as handle:
             handle.write(line)
         return True
-    except OSError:
+    except (OSError, CdxError):
         return False
 
 
@@ -171,6 +174,11 @@ def read_events(base_dir, include_acknowledged=False):
     return events[-MAX_SPOOLED_EVENTS:]
 
 
+# A hook must never stall an agent's turn on this lock; giving up only means
+# the alert is delivered directly instead.
+SPOOL_LOCK_TIMEOUT_SECONDS = 2
+
+
 def acknowledge(base_dir, ids, now=None):
     """Mark events consumed, idempotently, and compact when it is worth it.
 
@@ -183,6 +191,17 @@ def acknowledge(base_dir, ids, now=None):
     if not wanted:
         return {"acknowledged": 0, "compacted": False}
 
+    with _spool_lock(events_path(base_dir)):
+        return _acknowledge_locked(base_dir, wanted, now)
+
+
+def _spool_lock(path):
+    from .run_registry import _registry_lock
+
+    return _registry_lock(path, timeout_seconds=SPOOL_LOCK_TIMEOUT_SECONDS, label="tray events")
+
+
+def _acknowledge_locked(base_dir, wanted, now):
     try:
         with open(events_path(base_dir), encoding="utf-8") as handle:
             lines = handle.readlines()

package/src/tray_logics.py

@@ -88,7 +88,7 @@ def _status(env=None, runner=None, executable=None, directories=None):
         try:
             completed = (runner or subprocess.run)(
                 [executable, "status", "--format", "json"], capture_output=True,
-                text=True, timeout=ADAPTER_TIMEOUT_SECONDS, check=False, **({"cwd": root} if root else {}),
+                text=True, encoding="utf-8", errors="replace", timeout=ADAPTER_TIMEOUT_SECONDS, check=False, **({"cwd": root} if root else {}),
             )
             payload = json.loads(completed.stdout) if getattr(completed, "returncode", 1) == 0 else None
         except (OSError, subprocess.SubprocessError, TypeError, ValueError):

package/src/update_all.py

@@ -33,7 +33,7 @@ def _which(command, env):
 def _run(command, env, runner=None, timeout=15):
     runner = runner or subprocess.run
     try:
-        result = runner(command, env=env, capture_output=True, text=True, check=False, timeout=timeout)
+        result = runner(command, env=env, capture_output=True, text=True, encoding="utf-8", errors="replace", check=False, timeout=timeout)
     except (OSError, subprocess.TimeoutExpired) as error:
         return {"returncode": 1, "stdout": "", "stderr": str(error)}
     if isinstance(result, dict):

package/src/update_check.py

@@ -143,7 +143,7 @@ def _installed_logics_manager_version(env=None, runner=None):
         result = runner(
             [executable, "--version"],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             timeout=2,
             env=env,
         )

package/src/update_manager.py

@@ -43,7 +43,7 @@ def _is_git_dirty(package_root):
         result = subprocess.run(
             ["git", "-C", str(package_root), "status", "--porcelain"],
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
             check=False,
         )
     except FileNotFoundError as error:
@@ -216,7 +216,11 @@ def _version_check_env(env):
     source = env or os.environ
     allowed = {
         key: source[key]
-        for key in ("PATH", "PATHEXT", "SystemRoot", "COMSPEC", "WINDIR")
+        # The home variables let the child find its home directory: without
+        # USERPROFILE, Windows Python's Path.home() raises and `cdx -v` prints
+        # a traceback instead of the version.
+        for key in ("PATH", "PATHEXT", "SystemRoot", "COMSPEC", "WINDIR",
+                    "HOME", "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "CDX_HOME")
         if source.get(key)
     }
     return allowed
@@ -244,7 +248,7 @@ def verify_updated_command(target_version, runner=None, env=None):
             env=_version_check_env(env),
             check=False,
             capture_output=True,
-            text=True,
+            text=True, encoding="utf-8", errors="replace",
         )
     except OSError as error:
         return {