cdx-manager 0.20.13 → 0.21.0

package/docs/features.md

@@ -0,0 +1,102 @@
+# Features
+
+## Quota-aware routing
+
+The reason `cdx` exists: knowing, across every account you own, which one you can actually use.
+
+- **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.
+- **Agent notifications.** At the first interactive launch of a supported provider, cdx asks before installing its hook. Delivery starts muted; `cdx tray alerts on` enables the next event globally, with or without the tray running.
+- **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.
+
+## Isolated multi-account sessions
+
+![cdx: every registered session with its provider, state, pinned launch settings and age](assets/list.png)
+
+- **Multiple providers, one tool.** Register as many Codex, Claude, Antigravity, or Ollama sessions as you need. Codex and Claude get isolated auth environments; Antigravity is launchable through `agy` with OS-keyring auth; Ollama runs local models through `ollama run`.
+- **Instant launch.** `cdx work` opens your "work" session. `cdx personal` opens another. No config files to edit mid-flow.
+- **Quick relaunch.** `cdx last` reopens the most recently launched assistant profile.
+- **Resume by identity, not by recency.** Each session records the provider's own conversation id — imposed at launch for Claude, read back from the rollout for Codex — so `cdx resume <name>` reopens *that* conversation regardless of your working directory or of which session ran last. The conversation is looked up before it is named: a recorded id whose transcript the provider never wrote degrades to the provider's own fallback (`--continue`, or `resume --last`) and reports `reason: conversation_not_found`, rather than naming a conversation that does not exist and letting the provider exit with an error. `cdx can-resume --json` reports the strategy and where the id came from, so an automated caller can tell a named resume from a best-effort one.
+- **Auth guardrails.** `cdx` checks authentication before launching. If a session is not logged in, it tells you exactly what to run — no silent failures.
+- **Persistent launch settings.** Pin per-session power, permission, and fast-mode preferences once; `cdx` reapplies them on every launch until you unset them.
+- **Spend ceiling and model fallback.** `cdx set <name> --budget 5` caps what a headless run may spend, and `--fallback-model sonnet,haiku` lets a run continue on the next model when the first is overloaded. Both are Claude Code flags that the provider accepts with `--print` only, so they apply to `cdx run` and not to interactive launches; `cdx configs` says so.
+- **Session control.** Disable a session without deleting it when an account is temporarily out of credits; disabled sessions remain visible and sort last.
+- **Optional session labels.** `cdx label <name> <label>` adds a short human label; list and full status tables show a `LABEL` column only when at least one session has one.
+- **Clean removal.** `cdx rmv` wipes a session and its entire auth directory. No orphaned files, no stale credentials.
+
+## Headless automation
+
+- **One task, one JSON result.** `cdx run` executes a prompt against a chosen or auto-selected session and returns a stable payload; `--detach` returns a `run_id` immediately.
+- **Survives a rate limit.** `cdx run --failover` notices that a run stopped because its account ran out, moves the task to the next account the ranking allows, and carries on — one `run_id` for the whole task, with every account it occupied listed in `cdx run-report`. A spent account is always confirmed against its own refreshed quota first, so a healthy account is never abandoned. From there two routes migrate a run: the provider said so in words cdx recognises, or — since that wording differs between an enterprise workspace out of credits, a personal plan hitting its 5-hour window, and Claude's own phrasing — simply that the account's quota is gone and the run failed. `cdx run-report` names which route applied. Exhausting every account reports `failover_exhausted`, which a caller can tell apart from the task itself failing.
+- **Native background delegation (opt-in).** With `CDX_EXPERIMENTAL_NATIVE_BG=1`, `cdx run --detach` hands the run to Claude Code's own background agents (`--bg`) instead of cdx's detached launcher. The run keeps its cdx `run_id`, closes out with its token usage and final answer read from the provider's own session transcript, and the parked session is stopped once its task is done. Off by default for one release while it settles; the in-house launcher is unchanged and is what every run takes otherwise. Codex keeps the in-house path while its `cloud`/`exec-server` surfaces are marked experimental.
+- **Observable runs.** `cdx run-status`, `cdx run-tail`, `cdx run-report`, and `cdx runs --since` follow a run while it happens and after it ends.
+- **Selection without launching.** `cdx select --provider ... --require-ready --json` answers "which session should this job use?" for orchestrators.
+- **Escape hatch for unmapped flags.** `cdx set <name> --extra-args "--add-dir ../shared"` passes provider arguments cdx does not model straight through, so a flag your provider shipped last week never forces you to abandon cdx. These arguments are explicitly unvalidated: cdx does not parse or verify them, `cdx schema --json` lists them under `unvalidated` rather than describing them, and `cdx doctor --check-provider-flags` ignores them. They are split into literal argv entries and never passed through a shell.
+- **Validated contract.** `cdx schema --json` publishes the enums, mutually-exclusive argument groups, and error codes programmatic callers should validate against.
+
+## Context handoff
+
+- **Transcript-first handoff.** Switch accounts or providers using the source conversation's recorded native identity and verified workspace. CDX never chooses a conversation by file modification time. Missing, stale or mismatched identity requires an explicit choice; JSON/non-interactive callers receive candidate diagnostics instead of a launch.
+- **Instructions before action.** The receiving agent is told to read applicable `AGENTS.md`/`CLAUDE.md` and their required references (including Logics instructions), recover the task from bounded portions of the complete transcript, verify current state, then show a concise objective/state/next-action checkpoint before modifying anything. Existing clear authorization still permits continuation. CDX supplies this prompt; it cannot certify that an agent has understood or obeyed it.
+- **Shared notes remain yours.** `cdx context` and `cdx memory` remain explicit notes. Automatic handoff does not overwrite them or copy authentication. A dated reference to workspace notes is supplementary, never a substitute for the native conversation.
+- **Session transcript capture.** Every launch is recorded to a local log file via `script`, giving you a full terminal transcript for each session.
+
+Run handoff from the intended project directory:
+
+```sh
+cd /path/to/project
+cdx handoff source target --json                 # prepare only, no provider launch
+cdx handoff target                               # use that prepared entry and launch
+cdx handoff source target --source-conversation CONVERSATION_ID
+# Exact native file when several transcripts share an identity:
+cdx handoff source target --source-native-transcript /path/to/source/sessions/rollout.jsonl
+# Explicit fallback when only a terminal capture is available:
+cdx handoff source target --source-transcript /path/to/source/log/cdx-session.log
+```
+
+The three source-selection options are mutually exclusive and apply only to
+`SOURCE TARGET`. Without a usable recorded identity, an interactive terminal offers
+up to 20 valid conversations from the current workspace, ordered by actual event
+time for inspection, with no default choice. Blank input or Ctrl-C cancels. A stale
+recorded identity never silently falls back, even if there is only one candidate.
+Run from the conversation's original workspace if its metadata names another directory.
+
+Each preparation writes a private, unique `<target-auth-home>/handoffs/<uuid>.json`
+entry. `context.target_path` in JSON output names that entry; `handoff` contains its
+metadata, including recovery mode, source conversation ID, transcript path, workspace,
+preparation time, readable byte extent and SHA-256. `source_session`/`target_session`
+contain names/providers only. Transcript bodies and credentials are not emitted.
+Unresolved JSON source selection returns `ok: false`, error code
+`handoff_source_unresolved`, a bounded `candidates` array and a nonzero exit status.
+
+The original JSONL remains in place, including early decisions, tool calls/results
+and compaction records. Read it in bounded portions up to `extent_bytes`; there is
+no 120000-character tail replacement. An unfinished final JSONL record is excluded
+from that preparation. Later appends do not change its boundary. Reusing an entry
+checks the original bytes: deletion, truncation or rewriting requires a new handoff,
+not a silent downgrade to notes. Keep the original source profile/transcript available
+until recovery completes. No transcript copy or automatic artifact cleanup is performed;
+entries can be removed after use. A small per-workspace/target pointer chooses the most
+recent preparation for the one-name command; concurrent launches retain their own entry
+path and cannot overwrite each other's entry.
+
+Legacy one-name handoff without a prepared entry reads workspace notes in `notes-only`
+mode and explicitly reports that native history was not recovered. Terminal fallback
+requires a named file from that source session's launch logs and is labelled `degraded`:
+it cannot prove complete history or tools, and its workspace is operator-selected rather
+than verified from native metadata. Native resolution currently supports Codex and Claude.
+All modes ask the recipient to report material gaps, and none bypass provider access rules
+or turn historical tool output into new authorization.
+
+## Maintenance
+
+- **Launch history.** Inspect recent launches with provider, result, duration, working directory, launch settings, and transcript path.
+- **Aggregate usage.** `cdx stats` totals runs, token usage, and time spent per session over any period. Interactive Codex and Claude launches also record provider-native token totals when their local session transcript is available.
+
+- **Disk usage and cleanup.** `cdx disk` reports `CDX_HOME` usage, `cdx disk profiles --candidates` identifies reclaimable profile caches/logs with evidence, and `cdx clean profiles ...` applies explicit cleanup actions.
+- **Health and repair.** `cdx doctor` inspects dependencies, permissions, and orphan profiles; `cdx repair` plans or applies safe fixes.
+- **Portable bundles.** `cdx export` / `cdx import` move sessions between machines, with passphrase-encrypted auth data when you ask for it.
+- **Update prompts.** Periodic update checks surface `cdx update` directly in the `cdx`, `cdx status`, and launch output when a newer release is available. When `logics-manager` is installed, `cdx` can also suggest `logics-manager update`.
+- **Logics viewer shortcut.** `cdx view` opens the Logics browser/focus viewer through `logics-manager view` when the companion CLI is installed. All viewer flags are forwarded: `--lan`, `--lan-rw`, `--focus <ref>`, `--read`, `--port`, `--host`, `--refresh-interval`, `--tls`, `--tls-cert`, `--tls-key`, `--open`, `--no-open`. `cdx view --json` reports availability and update diagnostics without opening the viewer.

package/docs/getting-started.md

@@ -0,0 +1,183 @@
+# Getting started
+
+## Prerequisites
+
+- Node.js 18+ with npm
+- Python 3.9+
+- `codex`, `claude`, `agy`, and/or `ollama` CLI installed and available in your PATH
+
+On Windows, the npm launcher looks for Python in this order: `py -3`, `python`, then `python3`. Make sure at least one of those commands resolves to Python 3.
+
+## Install
+
+From npm:
+
+```bash
+npm install -g cdx-manager
+```
+
+With pipx:
+
+```bash
+pipx install cdx-manager
+```
+
+With uv:
+
+```bash
+uv tool install cdx-manager
+```
+
+On Windows with PowerShell:
+
+```powershell
+npm install -g cdx-manager
+```
+
+With the standalone PowerShell installer:
+
+```powershell
+Invoke-WebRequest https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.ps1 -OutFile install.ps1
+# Optional: set CDX_SHA256 before running if you have a trusted checksum.
+# Set CDX_ALLOW_UNVERIFIED=1 only if you intentionally accept an unverified archive.
+powershell -ExecutionPolicy Bypass -File .\install.ps1
+```
+
+With the standalone GitHub installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
+# Optional: set CDX_SHA256 before running if you have a trusted checksum.
+# Set CDX_ALLOW_UNVERIFIED=1 only if you intentionally accept an unverified archive.
+sh install.sh
+```
+
+For a specific version:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
+CDX_VERSION=v0.8.0 sh install.sh
+```
+
+From source:
+
+```bash
+git clone <repo>
+cd cdx-manager
+make install
+```
+
+For local development, install the Python toolchain as well:
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+From source on Windows:
+
+```powershell
+git clone <repo>
+cd cdx-manager
+npm install -g .
+```
+
+`cdx` is now available globally. Changes to the source take effect immediately — no reinstall needed.
+
+To update an installed copy later:
+
+```bash
+cdx update
+```
+
+To uninstall:
+
+```bash
+make uninstall
+```
+
+To uninstall on Windows after `npm install -g`:
+
+```powershell
+npm uninstall -g cdx-manager
+```
+
+Alternatively, for a non-symlinked global source install:
+
+```bash
+npm install -g .
+```
+
+Security note:
+
+- The standalone installers resolve official release checksums from the tagged GitHub Release asset `release-archives.json`.
+- You can still override verification explicitly through `CDX_SHA256`.
+- If no checksum is available, standalone installers fail closed unless `CDX_ALLOW_UNVERIFIED=1` is set; that override prints a prominent warning before continuing.
+- Prefer `npm`, `pipx`, or `uv` when you want registry-backed install flows.
+- If you use the standalone script, download it first, inspect it, and prefer a release with the official checksum asset attached.
+
+
+## Environment
+
+By default, `cdx` stores all data under `~/.cdx/`. Override with:
+
+```bash
+export CDX_HOME=/path/to/custom/dir
+```
+
+Optional runtime knobs:
+
+```bash
+export CDX_CLAUDE_STATUS_MODEL=claude-haiku-4-5-20251001
+export CDX_SCRIPT_BIN=script
+export CDX_SCRIPT_ARGS='-q -F {transcript}'
+```
+
+PowerShell equivalents:
+
+```powershell
+$env:CDX_HOME = "C:\cdx-data"
+$env:CDX_CLAUDE_STATUS_MODEL = "claude-haiku-4-5-20251001"
+$env:CDX_SCRIPT_BIN = "script"
+$env:CDX_SCRIPT_ARGS = "-q -F {transcript}"
+```
+
+Command Prompt equivalents:
+
+```cmd
+set CDX_HOME=C:\cdx-data
+set CDX_CLAUDE_STATUS_MODEL=claude-haiku-4-5-20251001
+set CDX_SCRIPT_BIN=script
+set CDX_SCRIPT_ARGS=-q -F {transcript}
+```
+
+## Quick Start
+
+```bash
+# Register a Codex session
+cdx add work
+
+# Register a Claude session
+cdx add claude personal
+
+# Register an Ollama session
+cdx add ollama local --model llama3.2
+
+# List all sessions
+cdx
+
+# Launch a session
+cdx work
+
+# Check usage across all sessions
+cdx status
+
+# Pick the best session using the same priority logic as status
+cdx next
+
+# Notify when the next cooling-down assistant is ready
+cdx ready
+
+# Inspect CDX_HOME and profile disk usage
+cdx disk
+cdx disk profiles --candidates
+```

package/docs/operations.md

@@ -0,0 +1,161 @@
+# Operations
+
+## Backup And Restore
+
+You can move sessions between machines with portable bundles:
+
+```bash
+cdx export backup.cdx
+cdx import backup.cdx
+```
+
+To migrate auth and avoid logging in again, include auth data in an encrypted bundle:
+
+```bash
+export CDX_BUNDLE_PASSPHRASE='choose-a-strong-passphrase'
+cdx export backup-auth.cdx --include-auth --passphrase-env CDX_BUNDLE_PASSPHRASE
+cdx import backup-auth.cdx --passphrase-env CDX_BUNDLE_PASSPHRASE
+```
+
+Notes:
+
+- `--include-auth` is encrypted, requires a passphrase, and exports only provider credential files rather than full profile caches, logs, or installed plugins.
+- Keychain-backed Claude authentication cannot currently be exported. If any selected profile uses it, `--include-auth` exits non-zero before writing anything, including with `--force`; text and JSON errors identify the affected profiles. Export without `--include-auth` and log in after import, or select only profiles whose authentication is file-backed. An inaccessible keychain is an explicit error, not a successful incomplete export.
+- Merge imports snapshot each existing profile before modification, preserving symlinks instead of following them. This temporarily needs space for a second copy of that profile. On failure, CDX restores the original files, record and state; if recovery also fails, the error gives the retained recovery directory containing the original metadata and any remaining profile snapshot.
+- Without `--passphrase-env`, `cdx` prompts in an interactive terminal. Non-interactive callers can pass `--passphrase-stdin` to read the passphrase from stdin (one line) instead of exposing it in the child environment.
+- `--sessions work,perso` exports or imports only a subset.
+- `--force` allows overwriting existing destination sessions during import or replacing an existing bundle file during export. Import preserves detected local `plugins/` state when the bundle does not provide it, and refuses to overwrite existing sessions from a bundle without auth payloads unless `--allow-authless-force` is also passed.
+- Auth bundles contain credentials. Treat them like secrets and delete them after transfer.
+
+## Release checklist
+
+- Name the GitHub Release `CDX Manager X.Y.Z` (for example, `CDX Manager 0.21.0`); use `vX.Y.Z` for its tag and the checked-in versioned changelog for its notes.
+- Before publishing npm or PyPI packages, run `npm run release:validate`.
+- The release tag must match `package.json`, `pyproject.toml`, `src/cli.py`, and `VERSION`.
+- `checksums/release-archives.json` must include the matching `vX.Y.Z` entry with both `github_tarball_sha256` and `github_zip_sha256`.
+- Publishing a GitHub Release runs the checksum upload workflow: it regenerates `checksums/release-archives.json` for the release tag and uploads it as the `release-archives.json` asset with replacement enabled for safe reruns.
+- If the asset is missing or stale, repair it with `python3 scripts/update_release_checksums.py --tag vX.Y.Z`, then `gh release upload vX.Y.Z checksums/release-archives.json --clobber`.
+- Publish packages only after the checksum workflow succeeds and `npm run release:validate`, `npm run lint`, and `npm test` pass.
+
+## Available Scripts
+
+- `npm test`: run the Python test suite with `pytest`
+- `npm run test:py`: run `pytest` through the portable launcher
+- `npm run test:coverage`: run `pytest` with terminal coverage reporting for `src/`
+- `npm run lint`: check project guidance, the Node launcher, `ruff`, and byte-compile the Python sources, scripts, and tests
+- `npm run release:validate`: verify version alignment and required GitHub release archive checksum metadata before publication
+- `npm run link`: link `cdx` globally for local development (`npm link`)
+- `npm run unlink`: remove the global link
+
+## Windows Support
+
+- Supported install paths on Windows:
+  - `npm install -g cdx-manager`
+  - `pipx install cdx-manager`
+  - `uv tool install cdx-manager`
+  - `install.ps1`
+- The npm launcher resolves Python via `py -3`, `python`, then `python3`, so a global npm install works even when `python3.exe` is missing.
+- `install.sh` is Unix-only.
+- `make install` and `make uninstall` are Unix-oriented convenience commands, not the default Windows path.
+- `cdx` isolates Claude sessions on Windows by setting `HOME`, `USERPROFILE`, `HOMEDRIVE`, and `HOMEPATH`.
+- Desktop notifications use PowerShell on Windows.
+- Codex transcript capture is optional on Windows:
+  - if a compatible `script` command is available and exposed via `CDX_SCRIPT_BIN`, `cdx` uses it
+  - otherwise Codex launches without transcript capture and the session still works normally
+- `cdx doctor` reports the transcript-capture fallback explicitly so missing `script` on Windows is visible without being treated as a hard failure.
+- `cdx doctor --json` includes detected `codex --version` and `claude --version` output when available, plus conservative capability hints for recent provider memory, model, and headless diagnostic surfaces. These hints are informational; `cdx` does not edit provider-private memory stores.
+
+## Disk maintenance
+
+Use `cdx disk` for a total `CDX_HOME` measurement, and `cdx disk profiles` for the `profiles/` total plus a per-profile breakdown.
+
+In an interactive terminal, long scans report their current stage and per-profile progress on stderr. JSON and redirected output remain free of progress messages.
+
+Text output uses aligned summary tables with profile size, share of total space, and reclaimable space. Candidate details are grouped by profile with separate size, type, risk, and evidence columns.
+
+```bash
+cdx disk
+cdx disk profiles
+```
+
+To find cleanup candidates without deleting anything:
+
+```bash
+cdx disk profiles --candidates
+cdx disk profiles --candidates --json
+```
+
+Candidate evidence includes profile name, path, size, risk, reason, and metadata such as modified time or old-log file counts. The current cleanup candidates are intentionally limited to:
+
+- temporary marketplace/plugin staging caches under `profiles/*/.tmp/`
+- `.log` files older than the requested age inside profile `log/` directories
+
+`cdx` also runs a passive disk cleanup check at most once per day on advisory commands such as `cdx` and `cdx status`. It writes the check timestamp and latest measurements to `~/.cdx/state/disk-cleanup-check.json`. A warning is shown only when at least one threshold is met:
+
+- `CDX_HOME` uses 10 GB or more
+- cleanup candidates can reclaim 1 GB or more
+- temporary cache candidates can reclaim 500 MB or more
+- old log candidates can reclaim 500 MB or more
+- one profile is 2 GB or more, or one profile is at least 25% of `profiles/` when `profiles/` is already 1 GB or more
+
+The passive warning is read-only and points to `cdx disk profiles --candidates`; it never deletes files.
+
+Apply cleanup only with explicit actions:
+
+```bash
+cdx clean profiles --tmp
+cdx clean profiles --old-logs 30d
+```
+
+`--tmp` removes temporary marketplace/plugin clone/backup staging directories. `--old-logs 30d` removes only `.log` files older than 30 days. The commands do not remove `auth.json`, `config.toml`, `sessions/`, SQLite state, installed `plugins/`, `skills/`, or credentials.
+
+All `cdx clean` actions require interactive confirmation before any deletion or log truncation begins. Non-interactive scripts must pass `--yes` explicitly.
+
+The cleanup action is selected only when `--tmp` or `--old-logs` is present. This keeps `cdx clean profiles` available for an existing session named `profiles`. If any candidate or old log cannot be removed, cleanup stops with a non-zero error that identifies the affected path; it does not report the operation as successful.
+
+## Banked Codex resets
+
+Eligible Codex accounts expose manually redeemable rate-limit resets through the Codex app-server. `cdx status` shows their available count in the `RESETS` column; `cdx status <name>` also shows the nearest known expiration, and JSON status includes the available reset details supplied by Codex.
+
+Activation is always explicit:
+
+```bash
+cdx reset <name>
+cdx reset <name> --yes --json
+```
+
+Without `--yes`, an interactive confirmation is required. `cdx` sends an idempotency key, consumes at most one available reset, and refreshes the session status after a successful activation. It never activates a reset from `cdx status` or any background check.
+
+## Troubleshooting
+
+### Codex credential refresh
+
+`cdx auth refresh work` makes a provider-native, non-generation request for one
+managed Codex profile. It can refresh an expiring access token, but never starts
+an agent or submits a prompt. Use `cdx auth refresh all --json` when a scheduler
+needs a stable result; CDX never installs or enables that scheduler for you.
+
+For example, a user-owned daily cron entry can run:
+
+```sh
+0 6 * * * cdx auth refresh all --json
+```
+
+`locked` means an interactive session owns the profile refresh lock and was left
+untouched. If every selected profile is locked, the command is non-zero because
+it verified no credential; a mix of valid and locked profiles remains successful.
+Bulk refresh skips disabled profiles, while `cdx auth refresh <name>` still lets
+an operator inspect one explicitly. `login_required` means the provider rejected
+the local refresh token; run the supplied `cdx login <name>` command interactively.
+Hosts keep independent rotating credentials, so copying an auth file is not ongoing
+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.
+- **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.
+- **Status shows `n/a` for all fields** — the Codex app-server rate-limit probe may be unavailable, the session may not be authenticated, and no legacy transcript/history status has been captured yet.
+- **`cdx rmv` says "Removal requires confirmation in an interactive terminal"** — pass `--force` to bypass the prompt in non-interactive environments (scripts, CI).
+- **`cdx login` hangs** — the provider's login flow requires a browser or device code. Follow the on-screen instructions in the terminal that opened.
+- **`make install` says `npm link` is not found** — ensure Node.js and npm are installed and in your PATH.
+- **On Windows, `doctor` warns that `script` is missing** — this is expected on many setups. Codex still launches, but transcript capture stays disabled unless you point `CDX_SCRIPT_BIN` to a compatible wrapper.

package/docs/sessions-and-notifications.md

@@ -0,0 +1,138 @@
+# Sessions and notifications
+
+## 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 · needs your attention
+✓ codex-a   cdx-manager · turn complete
+```
+
+CDX asks once at the first eligible interactive launch before writing a provider hook. Consent is installation-wide, but each profile receives its hook only when it is next launched. Alert delivery then starts muted; use `cdx tray alerts on` when you want banners. The older per-session commands remain compatible:
+
+```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
+cdx set work1 --notify-preview on  # include a short final-response preview
+```
+
+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.
+
+New sessions inherit response previews when agent alerts were accepted during
+tray installation. A completion notification includes at most 180 characters
+of the agent's final response, and a permission request may quote the
+provider's own one-line description of what it wants to do. That text can be
+visible on a lock screen; disable it per session with
+`cdx set <name> --notify-preview off`. Previews never read transcripts, and the
+command a permission request is about is never included.
+
+Both providers are subscribed to the same two hooks: `Stop` when a turn ends and
+`PermissionRequest` when one blocks on your approval. Claude Code is also
+subscribed to `Notification`, for the "still waiting for you" states that no
+other hook reports; the permission notifications it also sends are dropped,
+because `PermissionRequest` already reported the same call immediately and by
+name.
+
+Claude Code additionally reports a turn that ended on a provider error rather
+than on an answer — a rate limit, an overload, an authentication or billing
+problem. Those alerts are marked apart from completions, name the error class,
+and say whether the failure is one that usually clears on its own or one that
+needs you. Codex documents no equivalent hook, so a Codex turn killed by its
+provider stays silent; that is a gap in what the provider publishes, not a
+setting.
+
+A running tray companion receives each alert as fields rather than as a
+sentence, so its menu can name the session, the project and the tool, and
+clicking a recent alert opens the session it came from. The tool's arguments,
+the transcript path and the provider's own session identifiers are never part of
+that — only what cdx already knew and what the providers document as safe
+metadata.
+
+`cdx notify` is the internal hook target, called by the provider; it is not the
+setup command. `cdx ready` is separate: it notifies you when the next cooling-
+down session becomes usable.
+
+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
+cdx ready --refresh
+```
+
+## Persistent Launch Settings
+
+New sessions start with `power=medium` and `fast=off`, so launches are predictable without enabling fast mode. Set or override only the values you want to pin:
+
+```bash
+cdx set work --power medium --permission full --fast off
+cdx set personal --power low --permission review
+cdx set --sessions all --permission auto
+cdx set --provider ollama --model llama3.2
+cdx set work --priority 80
+cdx set work --rtk on
+cdx set work --logics off
+cdx power all low
+cdx perm provider:claude review
+cdx model provider:ollama llama3.2
+cdx config work
+cdx configs
+```
+
+Those values are stored on the session and reapplied every time you run `cdx work`. Remove overrides to return to provider-native defaults:
+
+```bash
+cdx unset work --power
+cdx unset --sessions work,personal --fast
+cdx unset --provider claude --permission
+cdx unset work --priority
+cdx unset work --rtk
+cdx unset work --logics
+cdx unset work --all
+cdx power all default
+cdx model provider:ollama default
+```
+
+`--model` maps to Codex `--model`, Claude `--model`, and Ollama `ollama run <model>`. `--power` maps to Codex `model_reasoning_effort` and Claude `--effort`; supported values are `minimal`, `low`, `medium`, `high`, and `xhigh`. `--permission` maps to provider-native permission flags. Codex Fast mode is separate from reasoning effort: `--fast on` opts a Codex session into the Codex Fast service tier, while new sessions, `--fast off`, and default launches force the non-Fast `flex` tier. Use `--power low` when you want low reasoning effort without enabling Codex Fast credits. Existing legacy sessions that stored `fast=on` before this split continue to behave as low effort unless the user explicitly sets `--fast on` again. `--priority` is a 0..100 selector preference used as a tie-breaker after readiness and availability. `--rtk on` adds standing guidance that encourages assistants to use RTK (`rtk <command>`) for noisy terminal commands when RTK is available, while keeping raw commands for exact output. Logics guidance is auto-enabled when `logics-manager` is available; use `--logics off` to disable that guidance for a session, or `--logics on` to pin it explicitly. This guidance is passed as instructions, never as a first message: Claude receives it through `--append-system-prompt` and Codex through `-c developer_instructions=...`, appended after any `developer_instructions` already set in the profile's `config.toml` (on Python older than 3.11 without `tomli`, a profile that sets its own is left untouched and gets no cdx guidance). Launching or resuming a session therefore never submits a turn on your behalf. Antigravity and Ollama have no instruction channel and receive no guidance. If you also pass `--append-system-prompt` through `--extra-args`, Claude receives the option twice; prefer putting your own text in the profile's `CLAUDE.md`.
+
+## Terminal Titles
+
+Interactive launches and resumes set the terminal window title to `session — folder`, where `folder` is the basename of the launch directory - for example `work — cdx-manager`. The convention is identical for Claude, Codex, and Antigravity: it comes from the shared launch runtime, not from provider flags, and cdx keeps re-asserting it so a provider TUI cannot take the title back mid-session.
+
+The title is only written when stdout is a terminal. Nothing is emitted for `--json` launches, redirected or piped output, `cdx run` and other headless runs, login flows, or Ollama sessions. Session names and directories are stripped of escape and control characters before the title is emitted, and cdx does not restore the previous title when the session ends.
+
+Claude Code writes its own animated title while an action runs, and it redraws far more often than cdx re-asserts the shared title. So interactive Claude launches and resumes started by cdx set the Claude-specific `CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1` in the provider environment, which stops Claude from setting and clearing the title and leaves `session — folder` stable while Claude is busy. Claude's in-TUI activity indicator is unaffected, the value is forced so an ambient setting in your shell cannot hand the title back, and headless `cdx run`, Claude authentication flows, and every non-Claude provider keep their previous environment.
+
+## Launch History
+
+Every interactive `cdx <name>` launch is recorded under `CDX_HOME`, including success/failure, duration, cwd, launch settings, and transcript path.
+
+```bash
+cdx history
+cdx history work
+cdx history work --limit 5
+cdx history work --json
+cdx history --summary
+cdx history --summary --since 7d
+cdx history --summary --from 2026-05-01 --to 2026-05-28
+```
+
+`cdx history --summary` aggregates total time per assistant. Add `--since`, `--from`, or `--to` to focus on a period.