cdx-manager 0.15.0 → 0.16.0

package/README.md

@@ -1,6 +1,6 @@
 # CDX Manager
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.15.0-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.16.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Stop guessing which AI account still has quota.** `cdx` tracks the rate-limit window of every Codex and Claude account you own, tells you which one is usable right now, and launches it with isolated auth — in one command.
 
@@ -70,7 +70,8 @@ The reason `cdx` exists: knowing, across every account you own, which one you ca
 
 - **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, last-updated timestamps, priority guidance, and the last launched session in one aligned table.
 - **Pick for me.** `cdx next` selects the best available assistant from your pinned priorities and the live quota picture, shows the reason, and prints the exact command to run.
-- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately. `cdx notify` covers reset times and scheduled wake-ups.
+- **Agent notifications.** When a session finishes a turn or blocks waiting for you, cdx raises a desktop notification naming the session and the repository — so you can run several in parallel without watching any of them. Opt in per session with `cdx set <name> --notify on`.
+- **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately.
 - **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
 - **Banked reset visibility.** Eligible Codex accounts show the number of manually redeemable bonus resets in `cdx status` and expose reset details in JSON output.
 
@@ -342,7 +343,43 @@ cdx disk profiles --candidates
 
 ### Next-Ready Notifications
 
-Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. It is shorthand for `cdx notify --schedule --next-ready`: cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
+### Agent notifications
+
+When a session's agent finishes a turn, or stops to wait for you, cdx raises a
+desktop notification naming the session and the repository:
+
+```text
+✓ work1     logics-manager · waiting for you
+✓ codex-a   cdx-manager · finished
+```
+
+Off until you ask for it, per session:
+
+```bash
+cdx set work1 --notify on      # turn it on for one session
+cdx set --all --notify on      # turn it on everywhere
+cdx set work1 --notify off     # and back off; cdx removes what it installed
+```
+
+Turning it on records the setting. The wiring happens at that session's **next
+launch**: cdx writes the hook into the session's own home and says so once.
+Claude Code honours it straight away. Codex only runs hooks that come from an
+installed plugin, so cdx generates one per session and installs it — and Codex
+asks you to approve it once, which cdx leaves to you rather than writing that
+trust on your behalf.
+
+It is off by default because turning it on writes into the provider's own
+configuration and, on Codex, puts an approval prompt in front of you. That is
+not something to do to sessions you already own without being asked.
+
+Per platform: macOS uses `osascript`, Linux `notify-send`, Windows a toast, and
+WSL reaches the Windows notification centre through interop. On a host with no
+way to deliver one — a headless or SSH Linux session, or WSL with interop
+disabled — cdx installs no hooks at all rather than asking you to approve
+something that could show you nothing. Headless `cdx run` never notifies: its
+caller already learns of completion from the return value.
+
+Use `cdx ready` when every useful assistant is cooling down and you want your terminal back. cdx picks the next known reset, registers a native OS notification, and exits immediately. If no future reset is known, it exits successfully and explains that no notification was scheduled.
 
 ```bash
 cdx ready
@@ -446,8 +483,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx update all [--yes] [--json]` | Check installed providers, RTK, and Ponytail across Codex profiles; show the plan and ask once before applying safe native/Homebrew updates and missing RTK/Ponytail setup |
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
-| `cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait for a session reset time or schedule an OS wake-up notification when due |
-| `cdx notify --next-ready [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait until the recommended session is usable, or schedule the next known reset notification |
+| `cdx notify` | Hook target: raises the desktop notification when a session's agent finishes a turn or waits for you. Called by the provider, not by you |
 | `cdx next [--json] [--refresh]` | Select the best next assistant using the same priority logic as `cdx status` |
 | `cdx select --provider PROVIDER [--min-reasoning-effort minimal\|low\|medium\|high\|xhigh] [--min-power minimal\|low\|medium\|high\|xhigh] [--require-ready] [--refresh] --json` | Select a suitable session for headless automation |
 | `cdx run [session] --cwd PATH (--prompt-file PATH\|--prompt TEXT\|--prompt-file -) [--provider PROVIDER] [--model MODEL] [--reasoning-effort minimal\|low\|medium\|high\|xhigh] [--power minimal\|low\|medium\|high\|xhigh] [--permission MODE] [--timeout-seconds N] [--detach] [--failover] [--refresh] --json` | Run one headless task and return a stable JSON result; `--detach` returns the `run_id` at launch without waiting, `--failover` continues the task on the next account when this one hits its rate limit, `--prompt-file -` reads the prompt from stdin |
@@ -499,7 +535,6 @@ Commands with machine-readable output:
 - `cdx view --json`
 - `cdx update --json`
 - `cdx ready --json`
-- `cdx notify ... --json`
 - `cdx select ... --json`
 - `cdx run ... --json`
 

package/changelogs/CHANGELOGS_0_15_0.md

@@ -131,9 +131,14 @@ synthetic home (`scripts/seed_demo_home.py`) so they carry no account names.
 
 ## Known gaps
 
-- The rate-limit wording of a personal-plan Codex account and of Claude has not
-  been observed; only an enterprise workspace out of credits has. The
-  `account_status_exhausted` route covers the unobserved cases, so this costs
-  the precise reason rather than the failover itself.
+- The rate-limit wording of a personal-plan Codex account has not been
+  observed; only an enterprise workspace out of credits has. Claude's wording
+  was recovered from local transcripts after the release was cut - it reports
+  `type: rate_limit_error` under HTTP 429, which the matcher already covers.
+  Worth knowing: that same 429 is also how an org policy disabling a model is
+  reported, a case no failover can fix, and the status corroboration is what
+  stops a healthy account being abandoned for it. The
+  `account_status_exhausted` route covers whatever wording remains unseen, so
+  this costs the precise reason rather than the failover itself.
 - Background delegation has been exercised on one account with one prompt
   shape, which is why it is opt-in.

package/changelogs/CHANGELOGS_0_15_1.md

@@ -0,0 +1,85 @@
+# CDX Manager 0.15.1
+
+> Two fixes, both for failures that only appear under the conditions cdx is
+> built for: an account whose credits ran out while its usage windows still
+> read healthy, and twenty parallel runs writing the registry at once on
+> Windows.
+
+## Fixes
+
+### Failover missed an exhausted account when its windows looked fine
+
+`--failover` corroborates a rate-limited run against the account's own
+refreshed status before migrating, so a healthy account is never abandoned on
+the strength of a matched phrase. That check read only the 5-hour and weekly
+percentages, which cannot see credit exhaustion: an account with 88% of its
+5-hour window and 70% of its weekly window remaining, and no credits, was
+reported as not spent. The run failed instead of moving, on an account that
+could not have succeeded.
+
+Codex publishes a typed reason for this — `rate_limit_reached_type`, null in
+normal operation and set to a value such as `workspace_owner_credits_depleted`
+when a limit is actually reached. cdx was already fetching that payload and
+dropping the field; it survived only inside `raw_status_text`, unparsed. It is
+now surfaced and treated as authoritative.
+
+Any non-null value counts. The enum belongs to the provider, and carrying a
+list of its members in cdx would reintroduce exactly the drift this removes —
+a value nobody has seen yet would silently mean "not exhausted".
+
+### Concurrent registry writes failed on Windows
+
+`_registry_lock` used `msvcrt.locking(LK_LOCK)`, which does its own waiting —
+ten attempts, one second apart — and then raises `EDEADLOCK`. POSIX
+`fcntl.flock` blocks until the lock frees. Identical contention therefore
+produced a wait on one supported platform and an `OSError` on the other.
+
+Twenty parallel runs writing the run registry is not an edge case for this
+tool; it is the load it exists to carry. Windows now takes the non-blocking
+form and waits in a loop cdx controls, bounded by a deadline cdx chooses rather
+than by `LK_LOCK`'s fixed budget. An exhausted wait raises a named error
+instead of a raw `OSError`, so contention is distinguishable from a bug.
+
+This predates 0.15.0 — it reproduces on the `v0.14.0` tag — and CI never showed
+it, a hosted runner being less contended than a physical desktop. Which also
+means CI could not be the evidence for the fix.
+
+## Also in this release
+
+- A test now fails if a flag is declared in a parser's schema and never used,
+  which is how `--failover` shipped in 0.15.0 parsing, validating and doing
+  nothing until an integration test caught it by chance.
+- `scripts/measure_option_sites.py` records the measurement behind that
+  decision: of the nine declaration sites an option touches, six restate one
+  fact and three encode a real decision, so the answer was a check rather than
+  a consolidation.
+
+## Validation
+
+- `npm run lint`
+- `npm test` — 639 tests.
+- CI green on ubuntu-latest and windows-latest.
+- On a physical Windows machine: 632 passed, 5 skipped, **no failures** —
+  including `test_concurrent_starts_do_not_lose_records`, which had failed
+  there on every run since before v0.14.0.
+- The credit-exhaustion case verified against the real payload shape recovered
+  from local transcripts: with 88% and 70% of the windows remaining and a typed
+  reason present, corroboration now confirms where it previously did not.
+
+## What closed from 0.15.0's known gaps
+
+- **Claude's rate-limit wording** was unobserved and now is not. Recovered from
+  local session transcripts: `type: rate_limit_error` under HTTP 429, already
+  covered by the existing matcher. Worth knowing, and now pinned by tests: the
+  same 429 is how an org policy disabling a model is reported, a case no
+  failover can fix, and the status corroboration is what keeps a healthy
+  account from being abandoned for it.
+
+## Still open
+
+- The rate-limit wording of a personal-plan Codex account remains unobserved.
+  The `account_status_exhausted` route covers it, so this costs the precise
+  reason rather than the failover itself.
+- Background delegation is still opt-in behind `CDX_EXPERIMENTAL_NATIVE_BG=1`.
+  It works and is verified end to end, but on one account with one prompt
+  shape — an exposure judgement, not a correctness one.

package/changelogs/CHANGELOGS_0_16_0.md

@@ -0,0 +1,97 @@
+# CDX Manager 0.16.0
+
+> cdx now tells you when one of its sessions finishes or needs you, which is
+> the one thing it could not do in the situation it was built for: several
+> assistants running in parallel across different repositories. Getting there
+> meant retiring the old `cdx notify` and reserving the name for this.
+
+## Breaking
+
+### `cdx notify` means something else
+
+`cdx notify <name> --at-reset` and `cdx notify --next-ready` are gone. Those
+answered "when does my quota come back", which `cdx status` already answers,
+and in practice the only form anyone typed was `cdx ready`.
+
+`cdx ready` is unchanged — same behaviour, same output, same flags. If you
+scripted the retired flags, `cdx ready --json` is the replacement; there is no
+equivalent for waiting on one named session's reset.
+
+`cdx notify` is now the target a provider hook calls. You do not run it
+yourself.
+
+## Features
+
+### Notifications when a session finishes or waits for you
+
+```text
+✓ work1     logics-manager · waiting for you
+✓ codex-a   cdx-manager · finished
+```
+
+The notification names the session and the repository, because the case this
+exists for is several of them at once — a notification that cannot tell you
+which one is not worth raising. Only cdx knows the session name, which is why
+this lives here rather than in a hook you write by hand.
+
+Off until you ask for it:
+
+```bash
+cdx set work1 --notify on      # one session
+cdx set --all --notify on      # all of them
+```
+
+The setting is recorded straight away; the wiring happens at that session's
+next launch, into the home directory cdx already owns, and cdx says so once.
+Turning it back off removes what cdx installed and leaves any hooks you wrote
+yourself alone.
+
+It is opt-in rather than on by default because enabling it writes into the
+provider's own configuration and, on Codex, puts an approval prompt in front of
+you — not something to do unrequested to sessions you already own.
+
+### Codex goes through a generated plugin
+
+Codex does not read hooks from a file. Not at its home root, not under a
+`hooks/` directory, not from a project `.codex/` — all three were tried and
+none is ever loaded. It runs only hooks that come from an installed plugin, so
+cdx generates one per session and installs it with `codex plugin marketplace
+add`.
+
+The generated plugin lives outside `CODEX_HOME` on purpose. Rooted inside it,
+the marketplace installs without an error and reports `installed, enabled`, and
+then never runs a thing: Codex registers it pointing at the source directory
+rather than the cache copy it executes from. Everything looks right and nothing
+happens.
+
+Codex also refuses to run a hook it has not been told to trust, so it asks you
+once per session. cdx does not answer that for you.
+
+### Delivery on every platform, and silence where there is none
+
+macOS uses `osascript`, Linux `notify-send`, native Windows a toast, and WSL
+reaches the Windows notification centre through interop rather than being
+treated as plain Linux — which is what it was before, and why it delivered
+nothing at all there.
+
+On a host with no way to show a notification — a headless or SSH Linux
+session, or WSL with interop disabled — cdx installs no hooks. Approving a
+hook that could never show you anything is a cost with no return. A host that
+gains a channel later is provisioned on its next launch.
+
+Headless `cdx run` never notifies, so a script issuing fifty runs stays quiet.
+Its caller already learns of completion from the return value.
+
+## Fixes
+
+### The Windows notification no longer blocks
+
+Windows notifications were a `MessageBox` spawned with no timeout. As an
+occasional quota alert that was survivable. As a hook firing on every agent
+turn it would have held the turn open until someone dismissed the dialog, and
+a window stealing focus every turn is worse than no notification at all. It is
+now a toast, which needs no dismissing.
+
+Claude Code honours the hooks it finds immediately. Codex is the one that
+gates them behind trust, so only Codex asks — cdx passes no bypass flag, the
+guard is there on purpose.

package/checksums/release-archives.json

@@ -172,6 +172,14 @@
     "v0.14.0": {
       "github_tarball_sha256": "5da107556442d3566a7b0787708ae700e38afdf99e74209fffd2484ce3a33d94",
       "github_zip_sha256": "bd4e070582bfc641e6176a8b8be8d7afd1ce9d76fc59c1dbeb238bae548bc699"
+    },
+    "v0.15.0": {
+      "github_tarball_sha256": "93d0a7305a5235f20e89a3e2a404029546926437952ee61d43a1f69c3ae98e4e",
+      "github_zip_sha256": "23e4e42fb746f4af5fa407f853e979ffce91e147dbb623c250e276fdcaa9638a"
+    },
+    "v0.15.1": {
+      "github_tarball_sha256": "1dc7ea87600844e4853ab12c9f123dc67548ae904f511fea9a58ddf7b3eacfef",
+      "github_zip_sha256": "7ad41c63adffdd1ef12d02a72c86fb1b6a64cbcddd9970b0741ba5516f241707"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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.15.0"
+version = "0.16.0"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9"

package/src/agent_notify.py

@@ -0,0 +1,324 @@
+"""Agent-event notifications: the hook target, and the per-session provisioning.
+
+`cdx notify` is what a provider hook calls when an agent turn ends or blocks
+waiting for input. It exists because the notification has to name *which* cdx
+session, in *which* repository — the case the feature is for is several sessions
+running in parallel — and only cdx knows the session name.
+
+Provisioning writes the hook into the session's own home, which cdx already
+owns because it sets HOME/CODEX_HOME per session at launch.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+
+from .notify import notification_channel, send_desktop_notification
+
+# Set on the provider process at launch; the hook runs as its child and inherits both.
+SESSION_ENV = "CDX_SESSION_NAME"
+ENABLED_ENV = "CDX_NOTIFY"
+
+# Our entries are recognised by the command they run, not by a marker key of our
+# own: both providers validate this file against their own schema, and an extra
+# key they do not know is a rejection risk for no gain.
+HOOK_ARG = "notify"
+
+_WAITING_EVENTS = {"notification", "permissionrequest", "userpromptsubmit"}
+
+
+def resolve_hook_command(env=None):
+    """Absolute path to cdx, not the bare name.
+
+    Codex spawns the hook without a shell, and a Windows npm install ships a
+    `.cmd` shim rather than an executable called `cdx`, so the bare name does
+    not resolve there. pipx and uv installs can likewise leave cdx off the PATH
+    the provider inherits.
+    """
+    env = env or os.environ
+    return env.get("CDX_BIN") or shutil.which("cdx", path=env.get("PATH")) or "cdx"
+
+
+def read_hook_payload(args, stdin_text=None):
+    """Accept the payload however the provider hands it over.
+
+    Claude Code and current Codex hooks write JSON to stdin. Codex's older
+    `notify` key — which it now calls `legacy_notify` — passes it as an argv.
+    Anything unparseable is an empty payload, never an error: a hook that fails
+    loudly turns a missing notification into a broken agent turn.
+    """
+    for candidate in ([stdin_text] if stdin_text else []) + list(args or []):
+        try:
+            payload = json.loads(candidate)
+        except (TypeError, ValueError):
+            continue
+        if isinstance(payload, dict):
+            return payload
+    return {}
+
+
+def compose_notification(payload, env=None, cwd=None):
+    """Title and message for this event, or None if we should stay quiet."""
+    env = env or os.environ
+    if env.get(ENABLED_ENV) == "0":
+        # Headless runs share the session's home, so they read the same hooks.
+        # Their caller already learns of completion from the return value.
+        return None
+    session = env.get(SESSION_ENV)
+    if not session:
+        return None
+    directory = payload.get("cwd") or payload.get("workspace") or cwd or os.getcwd()
+    event = str(payload.get("hook_event_name") or payload.get("eventName") or payload.get("type") or "").lower()
+    state = "waiting for you" if event.replace("_", "") in _WAITING_EVENTS else "finished"
+    where = os.path.basename(str(directory).rstrip("/\\")) or directory
+    return f"✓ {session}", f"{where} · {state}"
+
+
+def handle_notify(rest, ctx):
+    """Hook target. Never fails: a broken notification is not a broken turn."""
+    try:
+        import sys
+        stdin_text = None
+        # "stdin" in ctx is the {"isTTY": ...} descriptor, not a stream.
+        reader = ctx.get("prompt_stdin") or sys.stdin
+        if reader is not None and not ctx.get("stdin_is_tty"):
+            stdin_text = reader.read()
+        env = ctx.get("env") or os.environ
+        composed = compose_notification(read_hook_payload(rest, stdin_text), env, ctx.get("cwd"))
+        if composed:
+            send_desktop_notification(*composed, spawn_sync=ctx.get("spawn_sync"), env=env)
+    except Exception:  # noqa: BLE001 - deliberate: the caller is an agent turn
+        pass
+    return 0
+
+
+def launch_notify_env(session, enabled, env=None):
+    """Env the provider is launched with, carrying who we are and whether to notify."""
+    values = {SESSION_ENV: session["name"]}
+    if not enabled:
+        values[ENABLED_ENV] = "0"
+    return values
+
+
+def notifications_enabled(session):
+    """Off unless this session explicitly turned it on.
+
+    Opt-in rather than on-by-default: provisioning writes into the provider's
+    own configuration and, on Codex, asks the user to approve a hook. Doing
+    that to every session someone already owns, without being asked, is not a
+    default worth having.
+    """
+    launch = session.get("launch") or {}
+    return launch.get("notify") is True
+
+
+def provision(auth_home, provider, enabled, env=None, spawn_sync=None, base_dir=None):
+    """Install or remove cdx's notification hooks in this session's own home.
+
+    Idempotent, so an existing session picks the hooks up on its next launch and
+    repeated launches change nothing. Returns True when they were newly
+    installed, so the caller can say so once.
+
+    The two providers need different mechanisms, which is not a stylistic
+    choice: Claude Code reads hooks straight out of `settings.json`, while Codex
+    reads them only from an installed plugin — a free-standing hooks file
+    anywhere under `CODEX_HOME` is never looked at.
+    """
+    env = env or os.environ
+    if enabled and not notification_channel(env):
+        # Nothing could be delivered on this host, so installing a hook would only
+        # buy the user an approval prompt for a feature that shows nothing.
+        enabled = False
+    command = resolve_hook_command(env)
+    if provider == "claude":
+        return _apply_hooks(hook_config_path(auth_home, provider), enabled, command)
+    if provider == "codex":
+        return _provision_codex_plugin(auth_home, enabled, command, env, spawn_sync, base_dir)
+    return False
+
+
+def hook_config_path(auth_home, provider, base_dir=None):
+    if provider == "claude":
+        return os.path.join(auth_home, ".claude", "settings.json")
+    if provider == "codex":
+        return os.path.join(codex_plugin_root(auth_home, base_dir), "hooks", "cdx-hooks.json")
+    return None
+
+
+def codex_plugin_root(auth_home, base_dir=None):
+    """Where the generated Codex plugin lives — deliberately outside CODEX_HOME.
+
+    A marketplace rooted inside Codex's own home installs without complaint and
+    then never runs: Codex registers it pointing straight at the source
+    directory instead of taking the cache copy it executes from. Moving the same
+    plugin one directory out is the whole difference between working and
+    silently doing nothing.
+    """
+    if base_dir:
+        return os.path.join(base_dir, "state", "codex-plugins", os.path.basename(auth_home))
+    # Without a base directory, sit beside the home rather than guessing at cdx's
+    # layout by walking up from it: two levels above a home is `/` for anything
+    # not laid out as `<base>/profiles/<name>`, and writing there fails.
+    return os.path.join(os.path.dirname(auth_home), ".cdx-codex-plugins", os.path.basename(auth_home))
+
+
+# Codex only runs hooks that come from an installed plugin, identified as
+# `<plugin>@<marketplace>`. Generating one per session keeps the resolved cdx
+# path baked into it.
+CODEX_PLUGIN = "cdx-notify"
+CODEX_MARKETPLACE = "cdx"
+CODEX_PLUGIN_REF = f"{CODEX_PLUGIN}@{CODEX_MARKETPLACE}"
+
+
+def _provision_codex_plugin(auth_home, enabled, command, env, spawn_sync=None, base_dir=None):
+    installed = _codex_plugin_installed(auth_home)
+    if enabled == installed:
+        return False
+    if not enabled:
+        _run_codex(["plugin", "remove", CODEX_PLUGIN_REF], auth_home, env, spawn_sync)
+        _run_codex(["plugin", "marketplace", "remove", CODEX_MARKETPLACE], auth_home, env, spawn_sync)
+        return False
+    root = _write_codex_plugin(auth_home, command, base_dir)
+    if not root:
+        return False
+    if not _run_codex(["plugin", "marketplace", "add", root], auth_home, env, spawn_sync):
+        return False
+    return _run_codex(["plugin", "add", CODEX_PLUGIN_REF], auth_home, env, spawn_sync)
+
+
+def _codex_plugin_installed(auth_home):
+    """Whether Codex's own config already lists our plugin.
+
+    Read rather than remembered, so a plugin the user removed by hand is
+    reinstalled on the next launch instead of being assumed present.
+    """
+    try:
+        with open(os.path.join(auth_home, "config.toml"), encoding="utf-8") as handle:
+            return f'[plugins."{CODEX_PLUGIN_REF}"]' in handle.read()
+    except OSError:
+        return False
+
+
+def _write_codex_plugin(auth_home, command, base_dir=None):
+    root = codex_plugin_root(auth_home, base_dir)
+    files = {
+        os.path.join(root, ".claude-plugin", "marketplace.json"): {
+            "name": CODEX_MARKETPLACE,
+            "description": "cdx agent notifications",
+            "owner": {"name": "cdx"},
+            "plugins": [{
+                "name": CODEX_PLUGIN,
+                "description": "Notify when this cdx session finishes a turn or waits for you",
+                "source": "./",
+            }],
+        },
+        # The "hooks" key is what makes Codex load the file at all; without it
+        # the plugin installs cleanly and never runs anything.
+        os.path.join(root, ".claude-plugin", "plugin.json"): {
+            "name": CODEX_PLUGIN,
+            "version": "1.0.0",
+            "description": "Notify when this cdx session finishes a turn or waits for you",
+            "hooks": "./hooks/cdx-hooks.json",
+        },
+        os.path.join(root, "hooks", "cdx-hooks.json"): {
+            "hooks": {
+                event: [{"hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}]}]
+                for event in ("Stop", "Notification")
+            },
+        },
+    }
+    for path, document in files.items():
+        if not _write_json(path, document):
+            return None
+    return root
+
+
+def _run_codex(args, auth_home, env, spawn_sync):
+    """Run one `codex` command, following the repo's (command, args, options)
+    spawn_sync contract rather than subprocess.run's, so the same injected
+    double serves here as everywhere else."""
+    options = {"env": {**env, "CODEX_HOME": auth_home}, "cwd": auth_home}
+    try:
+        result = (spawn_sync or _subprocess_spawn_sync)("codex", list(args), options)
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        # No codex on PATH, or it hung: a skipped provisioning step, never a
+        # failed launch.
+        return False
+    if isinstance(result, dict):
+        return not result.get("error") and result.get("status", 0) == 0
+    return getattr(result, "returncode", 0) == 0
+
+
+def _subprocess_spawn_sync(command, args, options):
+    return subprocess.run(
+        [command, *args],
+        env=options.get("env"),
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+
+
+def _apply_hooks(path, enabled, command):
+    document = _read_json(path)
+    if document is None:
+        return False
+    hooks = document.get("hooks")
+    hooks = hooks if isinstance(hooks, dict) else {}
+    before = json.dumps(hooks, sort_keys=True)
+    for event in ("Stop", "Notification"):
+        # Rebuilt from whatever is there minus our own entry, so user-authored
+        # hooks on the same event survive both installing and removing.
+        entries = [entry for entry in hooks.get(event, []) if not _is_ours(entry)]
+        if enabled:
+            entries.append({
+                "hooks": [{"type": "command", "command": f"{command} {HOOK_ARG}"}],
+            })
+        if entries:
+            hooks[event] = entries
+        else:
+            hooks.pop(event, None)
+    if json.dumps(hooks, sort_keys=True) == before:
+        return False
+    document["hooks"] = hooks
+    return _write_json(path, document) and enabled
+
+
+def _is_ours(entry):
+    """Ours if any of its commands is a cdx notify invocation."""
+    if not isinstance(entry, dict):
+        return False
+    for hook in entry.get("hooks") or []:
+        command = str((hook or {}).get("command") or "")
+        if command.endswith(f" {HOOK_ARG}") and "cdx" in command:
+            return True
+    return False
+
+
+def _read_json(path):
+    """Existing content, {} when absent, or None when we must not touch it.
+
+    An unparseable file is someone else's, so we leave it exactly as it is
+    rather than replacing settings the user cares about.
+    """
+    try:
+        with open(path, encoding="utf-8") as handle:
+            document = json.load(handle)
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError):
+        return None
+    return document if isinstance(document, dict) else None
+
+
+def _write_json(path, document):
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as handle:
+            json.dump(document, handle, indent=2)
+            handle.write("\n")
+    except OSError:
+        # An unwritable home is a skipped provisioning step, not a failed launch.
+        return False
+    return True