cdx-manager 0.4.3 → 0.5.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.4.3-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.5.0-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Run multiple Codex and Claude sessions from one terminal. Switch between accounts instantly.**
 
@@ -36,6 +36,8 @@ One command to launch any session. Zero auth juggling.
 - **Instant launch.** `cdx work` opens your "work" session. `cdx personal` opens another. No config files to edit mid-flow.
 - **Auth guardrails.** `cdx` checks authentication before launching. If a session is not logged in, it tells you exactly what to run — no silent failures.
 - **Usage at a glance.** `cdx status` shows token usage, 5-hour window quota, weekly quota, and last-updated timestamps for every session in one aligned table.
+- **Session control.** Disable a session without deleting it when an account is temporarily out of credits; disabled sessions remain visible and sort last.
+- **Shared handoff context.** Keep a per-workspace Markdown context and install it into another assistant session before switching providers or accounts.
 - **Passive status resolution.** If a session has no recorded status, `cdx` reads it directly from the provider's session logs and JSONL history — no manual sync required.
 - **Session transcript capture.** Every launch is recorded to a local log file via `script`, giving you a full terminal transcript for each session.
 - **Clean removal.** `cdx rmv` wipes a session and its entire auth directory. No orphaned files, no stale credentials.
@@ -52,6 +54,7 @@ One command to launch any session. Zero auth juggling.
 - Persistence:
   - Session registry at `~/.cdx/sessions.json` (versioned JSON store).
   - Per-session state at `~/.cdx/state/<name>.json`.
+  - Per-workspace shared context at `~/.cdx/contexts/<workspace-hash>/context.md`.
   - Auth and provider data under `~/.cdx/profiles/<name>/`.
   - All paths are URL-encoded to support arbitrary session names.
 - Status resolution pipeline:
@@ -122,7 +125,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.4.3 sh install.sh
+CDX_VERSION=v0.5.0 sh install.sh
 ```
 
 From source:
@@ -143,6 +146,12 @@ 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
@@ -236,12 +245,17 @@ cdx status
 | `cdx ren <source> <dest> [--json]` | Rename a session and move its auth data |
 | `cdx login <name> [--json]` | Re-authenticate a session (logout + login) |
 | `cdx logout <name> [--json]` | Log out of a session |
+| `cdx disable <name> [--json]` | Disable a session without deleting it; disabled sessions stay visible and cannot launch |
+| `cdx enable <name> [--json]` | Re-enable a disabled session |
+| `cdx context show\|path\|init\|edit\|clear\|set [text...] [--json]` | Manage the shared Markdown context for the current workspace |
+| `cdx handoff <name> [--json]` | Install the current workspace context into a target session and launch it unless `--json` is used |
 | `cdx rmv <name> [--force] [--json]` | Remove a session and its auth data (prompts for confirmation unless `--force`) |
 | `cdx clean [name] [--json]` | Clear launch transcript logs for one session or all sessions |
 | `cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR] [--force] [--json]` | Export sessions to a portable bundle; `--include-auth` encrypts auth data with a passphrase |
 | `cdx import <file> [--sessions a,b] [--passphrase-env VAR] [--force] [--json]` | Import sessions from a bundle into the current `CDX_HOME` |
 | `cdx doctor [--json]` | Inspect CLI dependencies, CDX_HOME permissions, missing state, orphan profiles, and pending quarantines |
 | `cdx repair [--dry-run] [--force] [--json]` | Plan or apply safe repairs for missing state files, quarantines, and orphan profiles |
+| `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx notify <name> --at-reset [--poll seconds] [--once] [--json]` | Wait for a session reset time and send a desktop notification when due |
 | `cdx notify --next-ready [--poll seconds] [--once] [--json]` | Wait until the recommended session is usable or needs a refresh after reset |
 | `cdx status [--json] [--refresh]` | Show token usage table for all sessions; JSON returns a versioned payload with structured warnings |
@@ -270,8 +284,13 @@ Commands with machine-readable output:
 - `cdx import ... --json`
 - `cdx login ... --json`
 - `cdx logout ... --json`
+- `cdx disable ... --json`
+- `cdx enable ... --json`
+- `cdx context ... --json`
+- `cdx handoff ... --json`
 - `cdx doctor --json`
 - `cdx repair --json`
+- `cdx update --json`
 - `cdx notify ... --json`
 
 Success payloads follow a shared envelope:

package/changelogs/CHANGELOGS_0_4_4.md

@@ -0,0 +1,33 @@
+# Changelog (`0.4.3 -> 0.4.4`)
+
+Release date: 2026-04-20
+
+## Major Highlights
+
+- Generated from the release work on `cdx update`, the first built-in self-update path for `cdx-manager`.
+- Added a version-aware update command that can check for a newer release, confirm interactively, and delegate to the right installer for the current installation type.
+- Kept the existing update warning behavior intact so the CLI still surfaces newer releases on startup.
+- Reserved `update` as a session name to avoid collisions with the new command.
+
+## `cdx update`
+
+- Added `cdx update --check` for a quick release check without applying changes.
+- Added `cdx update --yes` for non-interactive environments.
+- Added `cdx update --version TAG` so maintainers can target a specific release.
+- Routed standalone installs through `install.sh` / `install.ps1`.
+- Routed npm installs through `npm install -g cdx-manager@...`.
+- Routed Python environment installs through `python -m pip install --upgrade ...`.
+- Routed source checkouts through `git pull --ff-only` or an explicit tag checkout when a version is requested.
+- Refused source updates when the checkout contains uncommitted changes.
+
+## Validation and Regression Coverage
+
+- Added CLI coverage for update checks, update execution, and version-aware help text.
+- Added session-service coverage for the new reserved command name.
+- Added unit coverage for installation detection and source-checkout safety in the update planner.
+- Kept the existing CLI and session-service test suites green.
+
+## Validation and Regression Evidence
+
+- `python3 -m unittest test.test_cli_py test.test_session_service_py test.test_update_manager_py`
+- `npm run lint`

package/changelogs/CHANGELOGS_0_5_0.md

@@ -0,0 +1,45 @@
+# Changelog (`0.4.4 -> 0.5.0`)
+
+Release date: 2026-05-20
+
+## Major Highlights
+
+- Added session disable/enable controls so an assistant can be kept in the registry while temporarily removed from launch rotation.
+- Added shared workspace context commands to make provider/account handoff explicit when moving between Codex and Claude sessions.
+- Prepared the package metadata for the 0.5.0 release across npm, PyPI, CLI version output, and README install examples.
+
+## Session Disable Toggle
+
+- Added `cdx disable <name> [--json]` and `cdx enable <name> [--json]`.
+- Disabled sessions remain visible in the main list and status views with a `disabled` status.
+- Disabled sessions sort after enabled sessions and are excluded from status priority recommendations.
+- Launching a disabled session now fails with a clear `Session is disabled: <name>` error.
+- Claude live status refresh skips disabled sessions.
+
+## Shared Context Handoff
+
+- Added per-workspace shared context storage at `~/.cdx/contexts/<workspace-hash>/context.md`.
+- Added `cdx context show`, `path`, `init`, `edit`, `clear`, and `set`.
+- Added `cdx handoff <name>` to install the current workspace context into the target session as `shared-context.md` before launching it.
+- Added `cdx handoff <name> --json` for non-interactive integrations that only need to install the context and inspect the resulting paths.
+- Reserved `context` and `handoff` as session names to avoid command collisions.
+
+## Packaging
+
+- Bumped `package.json`, `package-lock.json`, `pyproject.toml`, and `src/cli.py` to `0.5.0`.
+- Updated the README version badge, pinned installer example, command table, JSON command list, and data layout notes.
+- Removed the accidental npm self-dependency from `package.json` and regenerated the lockfile.
+
+## Validation and Regression Coverage
+
+- Added CLI coverage for context storage, workspace isolation, and handoff installation.
+- Added session-service coverage for disabled-session ordering, launch blocking, and new reserved command names.
+- Kept the full Python test suite green.
+
+## Validation and Regression Evidence
+
+- `python -m pytest`
+- `npm run lint`
+- `npm test`
+- `node bin/cdx.js --version`
+- `npm pack --dry-run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -28,6 +28,8 @@
     "checksums",
     "changelogs",
     "src",
+    "!src/__pycache__",
+    "!src/**/*.pyc",
     "install.sh",
     "install.ps1",
     "pyproject.toml",

package/pyproject.toml

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

package/src/claude_refresh.py

@@ -36,6 +36,7 @@ def _refresh_claude_sessions(service, refresh_fn=None, target_names=None, force=
     claude_sessions = [
         s for s in sessions
         if s["provider"] == "claude"
+        and s.get("enabled", True) is not False
         and (not target_names or s["name"] in target_names)
         and (force or _is_stale(s, ttl_seconds=ttl_seconds))
     ]

package/src/cli.py

@@ -9,10 +9,14 @@ from .cli_commands import (
     STATUS_USAGE,
     handle_add,
     handle_clean,
+    handle_context,
     handle_copy,
     handle_doctor,
+    handle_disable,
+    handle_enable,
     handle_export,
     handle_import,
+    handle_handoff,
     handle_launch,
     handle_login,
     handle_logout,
@@ -21,6 +25,7 @@ from .cli_commands import (
     handle_repair,
     handle_rename,
     handle_status,
+    handle_update,
 )
 from .cli_render import (
     _format_sessions,
@@ -44,7 +49,7 @@ from .status_view import (
 )
 from .update_check import check_for_update
 
-VERSION = "0.4.3"
+VERSION = "0.5.0"
 
 
 # ---------------------------------------------------------------------------
@@ -61,17 +66,22 @@ def _print_help(use_color=False):
         f"  {_style('cdx status [--json] [--refresh]', '36', use_color)}",
         f"  {_style('cdx status --small|-s [--refresh]', '36', use_color)}",
         f"  {_style('cdx status <name> [--json] [--refresh]', '36', use_color)}",
+        f"  {_style('cdx context show|path|init|edit|clear|set [text...] [--json]', '36', use_color)}",
+        f"  {_style('cdx handoff <name> [--json]', '36', use_color)}",
         f"  {_style('cdx add [provider] <name> [--json]', '36', use_color)}",
         f"  {_style('cdx cp <source> <dest> [--json]', '36', use_color)}",
         f"  {_style('cdx ren <source> <dest> [--json]', '36', use_color)}",
         f"  {_style('cdx login <name> [--json]', '36', use_color)}",
         f"  {_style('cdx logout <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx disable <name> [--json]', '36', use_color)}",
+        f"  {_style('cdx enable <name> [--json]', '36', use_color)}",
         f"  {_style('cdx rmv <name> [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx clean [name] [--json]', '36', use_color)}",
         f"  {_style('cdx export <file> [--include-auth] [--sessions a,b] [--passphrase-env VAR] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx import <file> [--sessions a,b] [--passphrase-env VAR] [--force] [--json]', '36', use_color)}",
         f"  {_style('cdx doctor [--json]', '36', use_color)}",
         f"  {_style('cdx repair [--dry-run] [--force] [--json]', '36', use_color)}",
+        f"  {_style('cdx update [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
         f"  {_style('cdx notify <name> --at-reset [--json]', '36', use_color)}",
         f"  {_style('cdx notify --next-ready [--json]', '36', use_color)}",
         f"  {_style('cdx <name> [--json]', '36', use_color)}",
@@ -99,6 +109,8 @@ def format_json_error(error):
         code = "unknown_command"
     elif message.startswith("Session already exists:"):
         code = "session_exists"
+    elif message.startswith("Session is disabled:"):
+        code = "session_disabled"
     elif "requires an interactive terminal" in message or "requires confirmation" in message:
         code = "interactive_terminal_required"
     return json.dumps({
@@ -205,8 +217,10 @@ def main(argv, options=None):
         "spawn": spawn,
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
+        "version": VERSION,
+        "cwd": options.get("cwd") or os.getcwd(),
         "update_notice": _get_update_notice(service, env, options) if command not in (
-            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "notify", "status", "login", "logout", "export", "import", "help", "version"
+            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "notify", "status", "context", "handoff", "login", "logout", "disable", "enable", "export", "import", "help", "version"
         ) else None,
         "use_color": use_color,
     }
@@ -223,6 +237,12 @@ def main(argv, options=None):
     if command == "rmv":
         return handle_remove(rest, ctx)
 
+    if command == "disable":
+        return handle_disable(rest, ctx)
+
+    if command == "enable":
+        return handle_enable(rest, ctx)
+
     if command == "clean":
         return handle_clean(rest, ctx)
 
@@ -238,9 +258,18 @@ def main(argv, options=None):
     if command == "repair":
         return handle_repair(rest, ctx)
 
+    if command == "update":
+        return handle_update(rest, ctx)
+
     if command == "notify":
         return handle_notify(rest, ctx)
 
+    if command == "context":
+        return handle_context(rest, ctx)
+
+    if command == "handoff":
+        return handle_handoff(rest, ctx)
+
     if command == "status":
         return handle_status(rest, ctx)
 

package/src/cli_commands.py

@@ -2,10 +2,20 @@ import asyncio
 import getpass
 import json
 import os
+import sys
 from datetime import datetime
 
 from .claude_refresh import _refresh_claude_sessions
 from .cli_render import _dim, _info, _success, _warn
+from .context_store import (
+    clear_context,
+    edit_context,
+    get_context_path,
+    init_context,
+    install_context_for_session,
+    read_context,
+    write_context,
+)
 from .errors import CdxError
 from .health import collect_health_report, format_health_report
 from .notify import (
@@ -22,13 +32,18 @@ from .provider_runtime import (
 from .repair import format_repair_report, repair_health
 from .backup_bundle import read_bundle_meta
 from .status_view import _format_status_detail, _format_status_rows
+from .update_check import fetch_latest_release, is_newer_version
+from .update_manager import build_update_plan, format_update_failure, run_update_plan
 
 
 STATUS_USAGE = "Usage: cdx status [--json] [--refresh] | cdx status --small|-s [--refresh] | cdx status <name> [--json] [--refresh]"
 DOCTOR_USAGE = "Usage: cdx doctor [--json]"
 REPAIR_USAGE = "Usage: cdx repair [--dry-run] [--force] [--json]"
+UPDATE_USAGE = "Usage: cdx update [--check] [--yes] [--json] [--version TAG]"
 EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
 IMPORT_USAGE = "Usage: cdx import <file> [--force] [--json] [--sessions name1,name2] [--passphrase-env VAR]"
+CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set [text...] [--json]"
+HANDOFF_USAGE = "Usage: cdx handoff <name> [--json]"
 API_SCHEMA_VERSION = 1
 
 
@@ -87,6 +102,13 @@ def _parse_remove_args(args):
     return {"name": names[0], "force": force}
 
 
+def _parse_toggle_args(args, usage):
+    json_flag, cleaned = _parse_json_flag(args)
+    if len(cleaned) != 1:
+        raise CdxError(usage)
+    return {"name": cleaned[0], "json": json_flag}
+
+
 def _read_option_value(args, index, usage):
     if index + 1 >= len(args):
         raise CdxError(usage)
@@ -102,6 +124,45 @@ def _parse_session_names(value):
     return names
 
 
+def _parse_update_args(args):
+    parsed = {
+        "check": False,
+        "json": False,
+        "yes": False,
+        "version": None,
+    }
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--check":
+            parsed["check"] = True
+            index += 1
+            continue
+        if arg == "--json":
+            parsed["json"] = True
+            index += 1
+            continue
+        if arg == "--yes":
+            parsed["yes"] = True
+            index += 1
+            continue
+        if arg == "--version":
+            value, index = _read_option_value(args, index, UPDATE_USAGE)
+            parsed["version"] = value
+            continue
+        if arg.startswith("--version="):
+            parsed["version"] = arg.split("=", 1)[1]
+            index += 1
+            continue
+        raise CdxError(UPDATE_USAGE)
+
+    if parsed["check"] and parsed["version"]:
+        raise CdxError("Usage: cdx update --check cannot be combined with --version.")
+    if parsed["version"] is not None and not parsed["version"].strip():
+        raise CdxError("Usage: cdx update [--check] [--yes] [--json] [--version TAG]")
+    return parsed
+
+
 def _parse_export_args(args):
     parsed = {
         "file_path": None,
@@ -329,6 +390,28 @@ def handle_remove(rest, ctx):
     return 0
 
 
+def handle_disable(rest, ctx):
+    parsed = _parse_toggle_args(rest, "Usage: cdx disable <name> [--json]")
+    session = ctx["service"]["set_session_enabled"](parsed["name"], False)
+    message = f"Disabled session {parsed['name']}"
+    if parsed["json"]:
+        _write_json(ctx, _json_success("disable", message, session=session))
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
+def handle_enable(rest, ctx):
+    parsed = _parse_toggle_args(rest, "Usage: cdx enable <name> [--json]")
+    session = ctx["service"]["set_session_enabled"](parsed["name"], True)
+    message = f"Enabled session {parsed['name']}"
+    if parsed["json"]:
+        _write_json(ctx, _json_success("enable", message, session=session))
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
 def handle_clean(rest, ctx):
     json_flag, args = _parse_json_flag(rest)
     service = ctx["service"]
@@ -465,6 +548,103 @@ def handle_notify(rest, ctx):
     return 0
 
 
+def handle_context(rest, ctx):
+    json_flag, args = _parse_json_flag(rest)
+    if not args:
+        args = ["show"]
+    action = args[0]
+    base_dir = ctx["service"]["base_dir"]
+    cwd = ctx.get("cwd")
+
+    if action == "show":
+        if len(args) != 1:
+            raise CdxError(CONTEXT_USAGE)
+        content = read_context(base_dir, cwd)
+        payload = {
+            "path": get_context_path(base_dir, cwd),
+            "exists": bool(content.strip()),
+            "content": content,
+        }
+        if json_flag:
+            _write_json(ctx, _json_success("context.show", "Loaded shared context", context=payload))
+            return 0
+        if content.strip():
+            ctx["out"](content if content.endswith("\n") else f"{content}\n")
+        else:
+            ctx["out"](f"{_dim('No shared context for this workspace. Run: cdx context init or cdx context set <text>', ctx['use_color'])}\n")
+        return 0
+
+    if action == "path":
+        if len(args) != 1:
+            raise CdxError(CONTEXT_USAGE)
+        path = get_context_path(base_dir, cwd)
+        if json_flag:
+            _write_json(ctx, _json_success("context.path", "Resolved shared context path", path=path))
+            return 0
+        ctx["out"](f"{path}\n")
+        return 0
+
+    if action == "init":
+        if len(args) != 1:
+            raise CdxError(CONTEXT_USAGE)
+        result = init_context(base_dir, cwd)
+        message = "Created shared context" if result.get("created") else "Shared context already exists"
+        if json_flag:
+            _write_json(ctx, _json_success("context.init", message, context=result))
+            return 0
+        text = f"{message}: {result['path']}"
+        ctx["out"](f"{_success(text, ctx['use_color'])}\n")
+        return 0
+
+    if action == "edit":
+        if len(args) != 1:
+            raise CdxError(CONTEXT_USAGE)
+        result = edit_context(
+            base_dir,
+            cwd,
+            env=ctx.get("env"),
+            spawn_sync=ctx.get("spawn_sync"),
+        )
+        if json_flag:
+            _write_json(ctx, _json_success("context.edit", "Edited shared context", context=result))
+            return 0
+        text = f"Edited shared context: {result['path']}"
+        ctx["out"](f"{_success(text, ctx['use_color'])}\n")
+        return 0
+
+    if action == "clear":
+        if len(args) != 1:
+            raise CdxError(CONTEXT_USAGE)
+        result = clear_context(base_dir, cwd)
+        message = "Cleared shared context" if result["removed"] else "No shared context to clear"
+        if json_flag:
+            _write_json(ctx, _json_success("context.clear", message, context=result))
+            return 0
+        ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+        return 0
+
+    if action == "set":
+        content_args = args[1:]
+        if content_args:
+            content = " ".join(content_args)
+        else:
+            stdin = ctx["options"].get("stdin_data")
+            if stdin is None and not ctx.get("stdin_is_tty"):
+                stdin = sys.stdin.read()
+            if stdin is None:
+                raise CdxError("Usage: cdx context set <text> [--json]")
+            content = stdin
+        result = write_context(base_dir, content, cwd)
+        if json_flag:
+            _write_json(ctx, _json_success("context.set", "Saved shared context", context=result))
+            return 0
+        text = f"Saved shared context: {result['path']}"
+        ctx["out"](f"{_success(text, ctx['use_color'])}\n")
+        return 0
+
+    raise CdxError(CONTEXT_USAGE)
+
+
 def handle_status(rest, ctx):
     json_flag = "--json" in rest
     small_flag = "--small" in rest or "-s" in rest
@@ -649,6 +829,91 @@ def handle_logout(rest, ctx):
     return 0
 
 
+def handle_update(rest, ctx):
+    parsed = _parse_update_args(rest)
+    json_flag = parsed["json"]
+    current_version = str(ctx.get("version") or "").strip()
+    release_fetcher = ctx["options"].get("fetchLatestRelease") or fetch_latest_release
+    target_version = None
+    release_url = None
+    update_available = False
+
+    if parsed["version"] is not None:
+        target_version = str(parsed["version"]).strip().lstrip("v")
+    else:
+        latest = release_fetcher()
+        if not latest:
+            raise CdxError("Unable to check for the latest cdx-manager release. Check your network and try again.")
+        target_version = str(latest.get("latest_version") or "").strip()
+        release_url = latest.get("url")
+        if not target_version:
+            raise CdxError("Unable to determine the latest cdx-manager release.")
+        update_available = is_newer_version(current_version, target_version)
+        if parsed["check"] or not update_available:
+            message = (
+                f"Update available: cdx-manager {target_version} (current {current_version})"
+                if update_available
+                else f"cdx-manager {current_version} is already up to date."
+            )
+            if json_flag:
+                _write_json(ctx, _json_success(
+                    "update",
+                    message,
+                    checked=True,
+                    update_available=update_available,
+                    current_version=current_version,
+                    target_version=target_version,
+                    release_url=release_url,
+                    warnings=[{
+                        "code": "update_available",
+                        "message": message,
+                        "latest_version": target_version,
+                        "url": release_url,
+                    }] if update_available else [],
+                ))
+                return 0
+            ctx["out"](f"{_warn(message, ctx['use_color']) if update_available else _success(message, ctx['use_color'])}\n")
+            return 0
+
+    if not parsed["yes"]:
+        if not ctx["stdin_is_tty"]:
+            raise CdxError("Update requires an interactive terminal or --yes in non-interactive mode.")
+        answer = input(f"Update cdx-manager to {target_version}? [y/N] ")
+        if answer.strip().lower() not in ("y", "yes"):
+            message = "Cancelled."
+            if json_flag:
+                _write_json(ctx, _json_success("update", message, cancelled=True, current_version=current_version, target_version=target_version))
+                return 0
+            ctx["out"](f"{_warn(message, ctx['use_color'])}\n")
+            return 0
+
+    plan = build_update_plan(
+        target_version=target_version,
+        package_root=ctx["options"].get("packageRoot"),
+        prefix=ctx["options"].get("prefix"),
+        base_prefix=ctx["options"].get("basePrefix"),
+    )
+    results = run_update_plan(plan, runner=ctx["options"].get("runUpdate"), env=ctx.get("env"))
+    failed = any((result.get("returncode") not in (0, None)) for result in results)
+    if failed:
+        raise CdxError(format_update_failure(results))
+
+    message = f"Updated cdx-manager to {target_version}"
+    if json_flag:
+        _write_json(ctx, _json_success(
+            "update",
+            message,
+            updated=True,
+            current_version=current_version,
+            target_version=target_version,
+            mode=plan["mode"],
+            steps=results,
+        ))
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
 def handle_launch(command, ctx):
     json_flag = "--json" in ctx["options"].get("raw_args", [])
     update_notice = ctx.get("update_notice")
@@ -689,3 +954,26 @@ def handle_launch(command, ctx):
     if json_flag:
         _write_json(ctx, _json_success("launch", message, warnings=warnings, session=ctx["service"]["get_session"](session["name"])))
     return 0
+
+
+def handle_handoff(rest, ctx):
+    json_flag, args = _parse_json_flag(rest)
+    if len(args) != 1:
+        raise CdxError(HANDOFF_USAGE)
+    name = args[0]
+    session = ctx["service"]["get_session"](name)
+    if not session:
+        raise CdxError(f"Unknown session: {name}")
+    install = install_context_for_session(ctx["service"]["base_dir"], session, ctx.get("cwd"))
+    if json_flag:
+        _write_json(ctx, _json_success(
+            "handoff",
+            f"Installed shared context for {name}",
+            context=install,
+            session=session,
+        ))
+        return 0
+    text = f"Shared context installed for {name}: {install['target_path']}"
+    ctx["out"](f"{_info(text, ctx['use_color'])}\n")
+    ctx["out"](f"{_dim('Ask the assistant to read shared-context.md if it does not pick it up automatically.', ctx['use_color'])}\n")
+    return handle_launch(name, ctx)

package/src/cli_render.py

@@ -108,6 +108,7 @@ def _format_sessions(service, use_color=False):
     headers = ["SESSION"]
     if has_provider:
         headers.append("PROVIDER")
+    headers.append("STATUS")
     headers.append("UPDATED")
     headers = [_style(header, "1", use_color) for header in headers]
     table_rows = []
@@ -115,6 +116,8 @@ def _format_sessions(service, use_color=False):
         parts = [r["name"]]
         if has_provider:
             parts.append(r.get("provider") or "n/a")
+        status = r.get("enabled_status") or ("enabled" if r.get("enabled", True) else "disabled")
+        parts.append(_style(status, "2" if status == "disabled" else "32", use_color))
         parts.append(_dim(_format_relative_age(r.get("updated_at")), use_color))
         table_rows.append(parts)
     lines = [_style("Known sessions:", "1", use_color), _pad_table([headers] + table_rows), ""]
@@ -124,6 +127,10 @@ def _format_sessions(service, use_color=False):
         f"  {_style('cdx <name>', '36', use_color)}",
         f"  {_style('cdx login <name>', '36', use_color)}",
         f"  {_style('cdx logout <name>', '36', use_color)}",
+        f"  {_style('cdx context show', '36', use_color)}",
+        f"  {_style('cdx handoff <name>', '36', use_color)}",
+        f"  {_style('cdx disable <name>', '36', use_color)}",
+        f"  {_style('cdx enable <name>', '36', use_color)}",
         f"  {_style('cdx ren <source> <dest>', '36', use_color)}",
         f"  {_style('cdx rmv <name>', '36', use_color)}",
         f"  {_style('cdx status', '36', use_color)}",

package/src/context_store.py

@@ -0,0 +1,127 @@
+import hashlib
+import os
+import shlex
+import subprocess
+from datetime import datetime
+
+from .errors import CdxError
+from .session_store import _ensure_dir
+
+
+DEFAULT_CONTEXT_TEMPLATE = """# Shared Context
+
+## Goal
+
+## Current State
+
+## Decisions
+
+## Files Changed
+
+## Open Questions
+
+## Next Steps
+"""
+
+
+def _local_now_iso():
+    return datetime.now().astimezone().isoformat()
+
+
+def _workspace_key(cwd):
+    normalized = os.path.realpath(cwd or os.getcwd())
+    digest = hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:16]
+    return digest
+
+
+def _context_dir(base_dir, cwd):
+    return os.path.join(base_dir, "contexts", _workspace_key(cwd))
+
+
+def get_context_path(base_dir, cwd=None):
+    return os.path.join(_context_dir(base_dir, cwd), "context.md")
+
+
+def get_context_meta_path(base_dir, cwd=None):
+    return os.path.join(_context_dir(base_dir, cwd), "meta.json")
+
+
+def read_context(base_dir, cwd=None):
+    path = get_context_path(base_dir, cwd)
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            return handle.read()
+    except FileNotFoundError:
+        return ""
+
+
+def write_context(base_dir, content, cwd=None):
+    path = get_context_path(base_dir, cwd)
+    _ensure_dir(os.path.dirname(path))
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(content.rstrip() + "\n")
+    return {
+        "path": path,
+        "updated_at": _local_now_iso(),
+        "bytes": os.path.getsize(path),
+    }
+
+
+def init_context(base_dir, cwd=None):
+    current = read_context(base_dir, cwd)
+    if current.strip():
+        return {
+            "path": get_context_path(base_dir, cwd),
+            "created": False,
+            "bytes": len(current.encode("utf-8")),
+        }
+    result = write_context(base_dir, DEFAULT_CONTEXT_TEMPLATE, cwd)
+    return {**result, "created": True}
+
+
+def clear_context(base_dir, cwd=None):
+    path = get_context_path(base_dir, cwd)
+    try:
+        os.remove(path)
+        removed = True
+    except FileNotFoundError:
+        removed = False
+    return {"path": path, "removed": removed}
+
+
+def edit_context(base_dir, cwd=None, editor=None, env=None, spawn_sync=None):
+    result = init_context(base_dir, cwd)
+    path = result["path"]
+    env = env or os.environ
+    editor = editor or env.get("VISUAL") or env.get("EDITOR")
+    if not editor:
+        raise CdxError("Context edit requires VISUAL or EDITOR.")
+    spawn_sync = spawn_sync or subprocess.run
+    argv = shlex.split(editor) + [path]
+    if spawn_sync is subprocess.run:
+        completed = subprocess.run(argv)
+        returncode = completed.returncode
+    else:
+        completed = spawn_sync(argv[0], argv[1:], {"env": env})
+        returncode = completed.get("returncode", 0) if isinstance(completed, dict) else getattr(completed, "returncode", 0)
+    if returncode not in (0, None):
+        raise CdxError(f"Context editor exited with code {returncode}")
+    return {"path": path, "edited": True}
+
+
+def install_context_for_session(base_dir, session, cwd=None):
+    content = read_context(base_dir, cwd)
+    if not content.strip():
+        raise CdxError("No shared context for this workspace. Run: cdx context init or cdx context set <text>")
+    auth_home = session.get("authHome") or session.get("sessionRoot")
+    if not auth_home:
+        raise CdxError(f"Session auth home missing for {session['name']}")
+    target_path = os.path.join(auth_home, "shared-context.md")
+    _ensure_dir(os.path.dirname(target_path))
+    with open(target_path, "w", encoding="utf-8") as handle:
+        handle.write(content.rstrip() + "\n")
+    return {
+        "source_path": get_context_path(base_dir, cwd),
+        "target_path": target_path,
+        "bytes": os.path.getsize(target_path),
+    }

package/src/session_service.py

@@ -19,10 +19,14 @@ MAX_SESSION_NAME_LENGTH = 64
 RESERVED_SESSION_NAMES = {
     "add",
     "clean",
+    "context",
     "cp",
+    "disable",
     "doctor",
+    "enable",
     "export",
     "help",
+    "handoff",
     "import",
     "login",
     "logout",
@@ -33,6 +37,7 @@ RESERVED_SESSION_NAMES = {
     "rename",
     "rmv",
     "status",
+    "update",
     "version",
     "--help",
     "-h",
@@ -272,6 +277,7 @@ def create_session_service(options=None):
         return {
             "name": session["name"],
             "provider": session["provider"],
+            "enabled": session.get("enabled", True) is not False,
             "createdAt": session.get("createdAt"),
             "updatedAt": session.get("updatedAt"),
             "lastLaunchedAt": session.get("lastLaunchedAt"),
@@ -324,6 +330,7 @@ def create_session_service(options=None):
         session = {
             "name": name,
             "provider": normalized_provider,
+            "enabled": True,
             "sessionRoot": session_root,
             "authHome": auth_home,
             "createdAt": now,
@@ -398,6 +405,7 @@ def create_session_service(options=None):
         replacement = {
             "name": dest_name,
             "provider": source["provider"],
+            "enabled": True,
             "sessionRoot": dest_root,
             "authHome": dest_auth_home,
             "createdAt": now,
@@ -484,6 +492,8 @@ def create_session_service(options=None):
         session = store["get_session"](name)
         if not session:
             raise CdxError(f"Unknown session: {name}")
+        if session.get("enabled", True) is False:
+            raise CdxError(f"Session is disabled: {name}")
         state = store["read_session_state"](name)
         if not state:
             raise CdxError(f"Session state missing for {name}. Reconnect required.")
@@ -514,6 +524,17 @@ def create_session_service(options=None):
     def get_session(name):
         return store["get_session"](name)
 
+    def set_session_enabled(name, enabled):
+        session = store["get_session"](name)
+        if not session:
+            raise CdxError(f"Unknown session: {name}")
+        now = _local_now_iso()
+        return store["update_session"](name, lambda s: {
+            **s,
+            "enabled": bool(enabled),
+            "updatedAt": now,
+        })
+
     def record_status(name, payload):
         normalized = _normalize_status_payload(payload)
         updated = store["update_session"](name, lambda s: {
@@ -604,10 +625,15 @@ def create_session_service(options=None):
 
         def sort_key(s):
             at = s.get("lastStatusAt") or ""
-            return ("" if at else "\xff", at, s["name"])
+            disabled_rank = 1 if s.get("enabled", True) is False else 0
+            return (disabled_rank, "" if at else "\xff", at, s["name"])
 
         resolved.sort(key=sort_key)
-        resolved.reverse()
+        enabled = [s for s in resolved if s.get("enabled", True) is not False]
+        disabled = [s for s in resolved if s.get("enabled", True) is False]
+        enabled.reverse()
+        disabled.sort(key=lambda s: s["name"])
+        resolved = enabled + disabled
 
         rows = []
         for s in resolved:
@@ -615,6 +641,8 @@ def create_session_service(options=None):
             rows.append({
                 "session_name": s["name"],
                 "provider": s["provider"],
+                "enabled": s.get("enabled", True) is not False,
+                "status": "disabled" if s.get("enabled", True) is False else "enabled",
                 "remaining_5h_pct": status.get("remaining_5h_pct") if status else None,
                 "remaining_week_pct": status.get("remaining_week_pct") if status else None,
                 "credits": status.get("credits") if status else None,
@@ -630,9 +658,18 @@ def create_session_service(options=None):
         sessions = list_sessions()
         providers = {s["provider"] for s in sessions}
         has_multiple = len(providers) > 1
+        sessions = sorted(
+            sessions,
+            key=lambda s: (
+                1 if s.get("enabled", True) is False else 0,
+                s.get("name", ""),
+            ),
+        )
         return [{
             "name": s["name"],
             "provider": s["provider"] if has_multiple else None,
+            "enabled": s.get("enabled", True) is not False,
+            "enabled_status": "disabled" if s.get("enabled", True) is False else "enabled",
             "status": s.get("lastStatus"),
             "updated_at": _to_local_iso(s.get("updatedAt")),
         } for s in sessions]
@@ -722,6 +759,7 @@ def create_session_service(options=None):
             session_record = {
                 **session_payload,
                 "provider": provider,
+                "enabled": session_payload.get("enabled", True) is not False,
                 "sessionRoot": session_root,
                 "authHome": auth_home,
             }
@@ -762,6 +800,7 @@ def create_session_service(options=None):
         "ensure_session_state": ensure_session_state,
         "list_sessions": list_sessions,
         "get_session": get_session,
+        "set_session_enabled": set_session_enabled,
         "record_status": record_status,
         "update_auth_state": update_auth_state,
         "get_status_rows": get_status_rows,

package/src/status_view.py

@@ -55,22 +55,29 @@ def _style_reset_time(value, use_color=False):
 def _format_status_rows(rows, use_color=False, small=False):
     has_provider = len({r["provider"] for r in rows}) > 1 and not small
     if small:
-        headers = ["SESSION", "OK", "5H", "WEEK", "RESET 5H", "RESET WEEK"]
+        headers = ["SESSION", "STATUS", "OK", "5H", "WEEK", "RESET 5H", "RESET WEEK"]
     elif has_provider:
-        headers = ["SESSION", "PROV.", "OK", "5H", "WEEK", "BLOCK", "CR", "RESET 5H", "RESET WEEK", "UPDATED"]
+        headers = ["SESSION", "PROV.", "STATUS", "OK", "5H", "WEEK", "BLOCK", "CR", "RESET 5H", "RESET WEEK", "UPDATED"]
     else:
-        headers = ["SESSION", "OK", "5H", "WEEK", "BLOCK", "CR", "RESET 5H", "RESET WEEK", "UPDATED"]
+        headers = ["SESSION", "STATUS", "OK", "5H", "WEEK", "BLOCK", "CR", "RESET 5H", "RESET WEEK", "UPDATED"]
     if not rows:
         if small:
-            return "SESSION  OK  5H  WEEK  RESET 5H  RESET WEEK\nNo saved sessions yet."
-        return "SESSION  OK  5H  WEEK  BLOCK  CR  RESET 5H  RESET WEEK  UPDATED\nNo saved sessions yet."
+            return "SESSION  STATUS  OK  5H  WEEK  RESET 5H  RESET WEEK\nNo saved sessions yet."
+        return "SESSION  STATUS  OK  5H  WEEK  BLOCK  CR  RESET 5H  RESET WEEK  UPDATED\nNo saved sessions yet."
     headers = [_style(header, "1", use_color) for header in headers]
-    priority = _recommend_priority_sessions(rows)
+    active_rows = [r for r in rows if r.get("enabled", True) is not False]
+    disabled_rows = sorted(
+        [r for r in rows if r.get("enabled", True) is False],
+        key=lambda r: r.get("session_name") or "",
+    )
+    priority = _recommend_priority_sessions(active_rows)
     table_rows = []
-    for r in priority:
+    for r in priority + disabled_rows:
         base = [r["session_name"]]
         if has_provider:
             base.append(r.get("provider") or "n/a")
+        status = r.get("status") or ("enabled" if r.get("enabled", True) else "disabled")
+        base.append(_style(status, "2" if status == "disabled" else "32", use_color))
         usage_columns = [
             _style_pct(r.get("available_pct"), use_color),
             _style_pct(r.get("remaining_5h_pct"), use_color),
@@ -258,6 +265,7 @@ def _format_status_detail(row, use_color=False):
     lines = [
         f"{_style('Session:', '1', use_color)} {row['session_name']}",
         f"{_style('Provider:', '1', use_color)} {row.get('provider') or 'n/a'}",
+        f"{_style('Status:', '1', use_color)} {_style(row.get('status') or ('enabled' if row.get('enabled', True) else 'disabled'), '2' if row.get('enabled', True) is False else '32', use_color)}",
         f"{_style('Available:', '1', use_color)} {_style_pct(row.get('available_pct'), use_color)}",
         f"{_style('5h left:', '1', use_color)} {_style_pct(row.get('remaining_5h_pct'), use_color)}",
         f"{_style('Week left:', '1', use_color)} {_style_pct(row.get('remaining_week_pct'), use_color)}",

package/src/update_check.py

@@ -28,6 +28,10 @@ def _is_newer_version(current_version, latest_version):
     return latest > current
 
 
+def is_newer_version(current_version, latest_version):
+    return _is_newer_version(current_version, latest_version)
+
+
 def _cache_path(base_dir):
     return os.path.join(base_dir, "state", "update-check.json")
 
@@ -63,6 +67,13 @@ def _fetch_latest_release():
     }
 
 
+def fetch_latest_release():
+    try:
+        return _fetch_latest_release()
+    except (urllib.error.URLError, TimeoutError, ValueError, OSError):
+        return None
+
+
 def check_for_update(base_dir, current_version, env=None, now_fn=None):
     env = env or os.environ
     now_fn = now_fn or (lambda: datetime.now(timezone.utc).timestamp())
@@ -83,9 +94,8 @@ def check_for_update(base_dir, current_version, env=None, now_fn=None):
             }
         return None
 
-    try:
-        latest = _fetch_latest_release()
-    except (urllib.error.URLError, TimeoutError, ValueError, OSError):
+    latest = fetch_latest_release()
+    if not latest:
         return None
 
     payload = {

package/src/update_manager.py

@@ -0,0 +1,208 @@
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from .errors import CdxError
+
+
+def _package_root(path=None):
+    if path is not None:
+        return Path(path).resolve()
+    return Path(__file__).resolve().parents[1]
+
+
+def _normalize_version(value):
+    if value is None:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    return text.lstrip("v")
+
+
+def _is_standalone_install(package_root):
+    return package_root.parent.name == "versions"
+
+
+def _is_source_checkout(package_root):
+    return (package_root / ".git").exists()
+
+
+def _is_git_dirty(package_root):
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(package_root), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise CdxError("git is required to update a source checkout.") from error
+    return bool((result.stdout or "").strip())
+
+
+def _is_python_env(prefix=None, base_prefix=None):
+    prefix = prefix or sys.prefix
+    base_prefix = base_prefix or sys.base_prefix
+    return prefix != base_prefix
+
+
+def detect_installation(package_root=None, prefix=None, base_prefix=None):
+    root = _package_root(package_root)
+    if _is_standalone_install(root):
+        return {"mode": "standalone", "package_root": str(root)}
+    if _is_source_checkout(root):
+        return {"mode": "source", "package_root": str(root)}
+    if _is_python_env(prefix=prefix, base_prefix=base_prefix):
+        return {"mode": "python", "package_root": str(root)}
+    if (root / "package.json").exists():
+        return {"mode": "npm", "package_root": str(root)}
+    return {"mode": "unknown", "package_root": str(root)}
+
+
+def _join_command(*parts):
+    return [str(part) for part in parts if part is not None]
+
+
+def _build_standalone_step(package_root, target_version):
+    package_root = _package_root(package_root)
+    env = {}
+    if target_version:
+        env["CDX_VERSION"] = target_version
+    if sys.platform == "win32":
+        return {
+            "label": "standalone installer",
+            "command": _join_command("powershell", "-ExecutionPolicy", "Bypass", "-File", package_root / "install.ps1"),
+            "cwd": str(package_root),
+            "env": env,
+        }
+    return {
+        "label": "standalone installer",
+        "command": _join_command("sh", package_root / "install.sh"),
+        "cwd": str(package_root),
+        "env": env,
+    }
+
+
+def _build_source_steps(package_root, target_version):
+    package_root = _package_root(package_root)
+    if _is_git_dirty(package_root):
+        raise CdxError(
+            "Your source checkout has uncommitted changes. "
+            "Commit or stash them before running cdx update."
+        )
+    if target_version:
+        return [
+            {
+                "label": "fetch tags",
+                "command": _join_command("git", "-C", package_root, "fetch", "--tags", "--force"),
+                "cwd": str(package_root),
+                "env": {},
+            },
+            {
+                "label": f"checkout v{target_version}",
+                "command": _join_command("git", "-C", package_root, "checkout", f"v{target_version}"),
+                "cwd": str(package_root),
+                "env": {},
+            },
+        ]
+    return [
+        {
+            "label": "git pull --ff-only",
+            "command": _join_command("git", "-C", package_root, "pull", "--ff-only"),
+            "cwd": str(package_root),
+            "env": {},
+        }
+    ]
+
+
+def _build_python_step(target_version):
+    command = [sys.executable, "-m", "pip", "install", "--upgrade"]
+    if target_version:
+        command.append(f"cdx-manager=={target_version}")
+    else:
+        command.append("cdx-manager")
+    return {
+        "label": "python package upgrade",
+        "command": command,
+        "cwd": None,
+        "env": {},
+    }
+
+
+def _build_npm_step(target_version):
+    spec = f"cdx-manager@{target_version}" if target_version else "cdx-manager@latest"
+    return {
+        "label": "npm global upgrade",
+        "command": ["npm", "install", "-g", spec],
+        "cwd": None,
+        "env": {},
+    }
+
+
+def build_update_plan(target_version=None, package_root=None, env=None, prefix=None, base_prefix=None):
+    root = _package_root(package_root)
+    version = _normalize_version(target_version)
+    detection = detect_installation(root, prefix=prefix, base_prefix=base_prefix)
+    mode = detection["mode"]
+    if mode == "standalone":
+        steps = [_build_standalone_step(root, version)]
+    elif mode == "source":
+        steps = _build_source_steps(root, version)
+    elif mode == "python":
+        steps = [_build_python_step(version)]
+    elif mode == "npm":
+        steps = [_build_npm_step(version)]
+    else:
+        raise CdxError(
+            "Unable to determine how cdx-manager was installed. "
+            "Set CDX_UPDATE_METHOD or update it manually."
+        )
+    return {
+        "mode": mode,
+        "package_root": str(root),
+        "target_version": version,
+        "steps": steps,
+    }
+
+
+def _result_code(result):
+    if isinstance(result, dict):
+        return result.get("returncode") if result.get("returncode") is not None else result.get("status")
+    return getattr(result, "returncode", getattr(result, "status", None))
+
+
+def _result_text(result, attr):
+    if isinstance(result, dict):
+        return result.get(attr)
+    return getattr(result, attr, "")
+
+
+def run_update_plan(plan, runner=None, env=None):
+    runner = runner or subprocess.run
+    results = []
+    for step in plan["steps"]:
+        step_env = {**(env or os.environ), **(step.get("env") or {})}
+        kwargs = {"cwd": step.get("cwd"), "env": step_env, "check": False}
+        result = runner(step["command"], **kwargs)
+        code = _result_code(result)
+        results.append({
+            "label": step["label"],
+            "command": step["command"],
+            "cwd": step.get("cwd"),
+            "returncode": code,
+            "stdout": _result_text(result, "stdout"),
+            "stderr": _result_text(result, "stderr"),
+        })
+        if code not in (0, None):
+            break
+    return results
+
+
+def format_update_failure(results):
+    if not results:
+        return "Update failed."
+    last = results[-1]
+    message = last.get("stderr") or last.get("stdout") or "Update failed."
+    return f"{last['label']} failed: {str(message).strip()}"