cdx-manager 0.11.0 → 0.11.1

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.11.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.11.1-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **Run multiple Codex, Claude, Antigravity, and Ollama sessions from one terminal. Switch between accounts instantly.**
 
@@ -36,6 +36,7 @@ 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.
 - **Quick relaunch.** `cdx last` reopens the most recently launched assistant profile.
 - **Auth guardrails.** `cdx` checks authentication before launching. If a session is not logged in, it tells you exactly what to run — no silent failures.
+- **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.
 - **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.
 - **Next-ready notification.** `cdx ready` schedules a native system notification for the next assistant that comes back from cooldown, then returns immediately.
 - **Session control.** Disable a session without deleting it when an account is temporarily out of credits; disabled sessions remain visible and sort last.
@@ -345,6 +346,8 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `cdx add [provider] <name> [--model MODEL] [--json]` | Register a new session (`provider`: `codex`, `claude`, `antigravity`, or `ollama`; Ollama requires `--model`) |
 | `cdx cp <source> <dest> [--json]` | Copy a session into another session name, overwriting the destination if it exists |
 | `cdx ren <source> <dest> [--json]` | Rename a session and move its auth data |
+| `cdx label <name> <label> [--json]` | Attach one short label to a session; tables show `LABEL` only when at least one label exists |
+| `cdx label <name> --clear [--json]` | Clear a session label |
 | `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 |
@@ -399,6 +402,7 @@ Commands with machine-readable output:
 - `cdx add ... --json`
 - `cdx cp ... --json`
 - `cdx ren ... --json`
+- `cdx label ... --json`
 - `cdx rmv ... --json`
 - `cdx clean ... --json`
 - `cdx disk ... --json`

package/changelogs/CHANGELOGS_0_11_1.md

@@ -0,0 +1,34 @@
+# CDX Manager 0.11.1
+
+## Highlights
+
+- Added optional labels for saved sessions.
+- Kept existing list and compact status output clean when no labels are present.
+- Closed the session-label Logics corpus with full validation evidence.
+
+## Changes
+
+### Optional session labels
+
+`cdx label <name> <label>` now attaches one short human-readable label to a saved session. Labels are stored as session metadata outside the `launch` dictionary, so they do not affect provider commands, auth checks, runtime state, ready/next selection, or launch history behavior.
+
+`cdx label <name> --clear` removes the label and returns the session to the same shape as legacy unlabeled records.
+
+The default `cdx` list and full `cdx status` table add a `LABEL` column only when at least one row has a label. Unlabeled rows render as `-`, and `cdx status --small` remains compact.
+
+JSON outputs for `cdx --json`, `cdx status --json`, `cdx status <name> --json`, and `cdx label ... --json` expose label values for automation consumers.
+
+Session copy, rename, export, and import preserve labels.
+
+### Documentation and workflow
+
+README and CLI help now document `cdx label <name> <label>` and `cdx label <name> --clear`.
+
+The optional session-label Logics request, backlog item, product brief, and orchestration task are closed with validation evidence.
+
+## Validation
+
+- `python3 -m unittest discover -s test`
+- `logics-manager flow validate req_012_add_optional_labels_to_cdx_sessions`
+- `logics-manager status`
+- `logics-manager health`

package/checksums/release-archives.json

@@ -136,6 +136,10 @@
     "v0.10.0": {
       "github_tarball_sha256": "20c473f4b17806d565c454ad4aa28758433665d8431251ebb937ab6a909e4adb",
       "github_zip_sha256": "b6a7be359d8dc2a11d8c77749878875419fabd7cd5a6951502dec09d7791e211"
+    },
+    "v0.11.0": {
+      "github_tarball_sha256": "bc42f83f20ba1c6ff81f824c382801457f93cf8cb166acbe952c12d009560a70",
+      "github_zip_sha256": "1c03b4f03f53c46d0a5ba580fc8ade7b26fa3cb1bb5f029f703681f136b9ac1f"
     }
   }
 }

package/package.json

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

package/src/cli.py

@@ -26,6 +26,7 @@ from .cli_commands import (
     handle_handoff,
     handle_history,
     handle_import,
+    handle_label,
     handle_last,
     handle_launch,
     handle_launch_setting_alias,
@@ -76,7 +77,7 @@ from .status_view import (
 )
 from .update_check import check_for_update, check_logics_manager_for_update
 
-VERSION = "0.11.0"
+VERSION = "0.11.1"
 
 # Public surface: this module is a facade. Names below are imported above
 # purely to be re-exported (consumed by tests and external callers); listing
@@ -112,6 +113,7 @@ _COMMAND_HANDLERS = {
     "handoff": handle_handoff,
     "history": handle_history,
     "import": handle_import,
+    "label": handle_label,
     "last": handle_last,
     "login": handle_login,
     "logout": handle_logout,
@@ -200,6 +202,8 @@ def _print_help(use_color=False):
         f"  {_style('cdx add [provider] <name> [--model MODEL] [--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 label <name> <label> [--json]', '36', use_color)}",
+        f"  {_style('cdx label <name> --clear [--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)}",

package/src/cli_args.py

@@ -20,6 +20,7 @@ EXPORT_USAGE = "Usage: cdx export <file> [--include-auth] [--force] [--json] [--
 IMPORT_USAGE = "Usage: cdx import <file> [--force|--merge] [--allow-authless-force] [--json] [--sessions name1,name2] [--passphrase-env VAR|--passphrase-stdin]"
 CONTEXT_USAGE = "Usage: cdx context show|path|init|edit|clear|set [text...] [--json]"
 HANDOFF_USAGE = "Usage: cdx handoff <name> [--json] | cdx handoff <source> <target> [--json]"
+LABEL_USAGE = "Usage: cdx label <name> <label> [--json] | cdx label <name> --clear [--json]"
 SET_USAGE = "Usage: cdx set <name>|--sessions all|a,b|--provider PROVIDER [--power minimal|low|medium|high|xhigh] [--permission review|default|auto|full] [--fast on|off] [--rtk on|off] [--logics on|off] [--model MODEL] [--priority 0..100] [--json]"
 UNSET_USAGE = "Usage: cdx unset <name>|--sessions all|a,b|--provider PROVIDER (--power|--reasoning-effort|--permission|--fast|--rtk|--logics|--model|--priority|--all) [--json]"
 SETTING_ALIAS_USAGE = "Usage: cdx power|perm|fast|model <name|all|provider:PROVIDER|a,b> <value|default> [--json]"
@@ -107,6 +108,21 @@ def _parse_rename_args(args):
     return {"source": args[0], "dest": args[1]}
 
 
+def _parse_label_args(args):
+    parsed = _parse_flag_args(args, {
+        "--clear": {"key": "clear", "type": "bool", "default": False},
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, LABEL_USAGE, positionals_key="values", max_positionals=2)
+    values = parsed["values"]
+    if parsed["clear"]:
+        if len(values) != 1:
+            raise CdxError(LABEL_USAGE)
+        return {"name": values[0], "label": None, "clear": True, "json": parsed["json"]}
+    if len(values) != 2:
+        raise CdxError(LABEL_USAGE)
+    return {"name": values[0], "label": values[1], "clear": False, "json": parsed["json"]}
+
+
 def _parse_remove_args(args):
     parsed = _parse_flag_args(args, {
         "--force": {"key": "force", "type": "bool", "default": False},

package/src/cli_commands.py

@@ -37,6 +37,7 @@ from .cli_args import (
     _parse_history_args,
     _parse_import_args,
     _parse_json_flag,
+    _parse_label_args,
     _parse_launch_setting_alias_args,
     _parse_next_args,
     _parse_remove_args,
@@ -732,6 +733,21 @@ def handle_rename(rest, ctx):
     return 0
 
 
+def handle_label(rest, ctx):
+    parsed = _parse_label_args(rest)
+    if parsed["clear"]:
+        session = ctx["service"]["clear_session_label"](parsed["name"])
+        message = f"Cleared label for {parsed['name']}"
+    else:
+        session = ctx["service"]["set_session_label"](parsed["name"], parsed["label"])
+        message = f"Set label for {parsed['name']}: {session['label']}"
+    if parsed["json"]:
+        _write_json(ctx, _json_success("label", message, session=session, label=session.get("label")))
+        return 0
+    ctx["out"](f"{_success(message, ctx['use_color'])}\n")
+    return 0
+
+
 def handle_remove(rest, ctx):
     json_flag, args = _parse_json_flag(rest)
     parsed = _parse_remove_args(args)

package/src/cli_render.py

@@ -123,10 +123,13 @@ def format_error(error, env=None, stderr=None):
 def _format_sessions(service, use_color=False):
     rows = service["format_list_rows"]()
     has_provider = any(r.get("provider") for r in rows)
+    has_label = any(r.get("label") for r in rows)
     has_launch = any(r.get("launch") for r in rows)
     headers = ["SESSION"]
     if has_provider:
         headers.append("PROVIDER")
+    if has_label:
+        headers.append("LABEL")
     headers.append("STATUS")
     if has_launch:
         headers.append("LAUNCH")
@@ -138,6 +141,8 @@ def _format_sessions(service, use_color=False):
         parts = [name]
         if has_provider:
             parts.append(r.get("provider") or "n/a")
+        if has_label:
+            parts.append(r.get("label") or "-")
         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))
         if has_launch:

package/src/session_service.py

@@ -22,6 +22,7 @@ from .status_source import find_latest_status_artifact
 DEFAULT_PROVIDER = PROVIDER_CODEX
 ALLOWED_PROVIDERS = set(PROVIDERS)
 MAX_SESSION_NAME_LENGTH = 64
+MAX_SESSION_LABEL_LENGTH = 64
 RESERVED_SESSION_NAMES = {
     "add",
     "can-resume",
@@ -40,6 +41,7 @@ RESERVED_SESSION_NAMES = {
     "history",
     "import",
     "last",
+    "label",
     "login",
     "logout",
     "model",
@@ -534,10 +536,21 @@ def create_session_service(options=None):
         if name in RESERVED_SESSION_NAMES:
             raise CdxError(f"Session name is reserved: {name}")
 
+    def _normalize_session_label(label):
+        text = str(label or "").strip()
+        if not text:
+            raise CdxError("Session label is required")
+        if len(text) > MAX_SESSION_LABEL_LENGTH:
+            raise CdxError(f"Session label is too long (max {MAX_SESSION_LABEL_LENGTH} characters)")
+        if any(ord(ch) < 32 or ord(ch) == 127 for ch in text):
+            raise CdxError("Session label cannot contain control characters")
+        return text
+
     def _build_export_session_record(session):
         return {
             "name": session["name"],
             "provider": session["provider"],
+            "label": session.get("label"),
             "enabled": session.get("enabled", True) is not False,
             "createdAt": session.get("createdAt"),
             "updatedAt": session.get("updatedAt"),
@@ -698,6 +711,7 @@ def create_session_service(options=None):
             "lastStatusAt": None,
             "lastStatus": None,
             **({"launch": source.get("launch")} if source.get("launch") else {}),
+            **({"label": source.get("label")} if source.get("label") else {}),
             "auth": {
                 "status": "unknown",
                 "lastCheckedAt": None,
@@ -888,6 +902,31 @@ def create_session_service(options=None):
             "updatedAt": now,
         })
 
+    def set_session_label(name, label):
+        session = store["get_session"](name)
+        if not session:
+            raise CdxError(f"Unknown session: {name}")
+        normalized = _normalize_session_label(label)
+        now = _local_now_iso()
+        return store["update_session"](name, lambda s: {
+            **s,
+            "label": normalized,
+            "updatedAt": now,
+        })
+
+    def clear_session_label(name):
+        session = store["get_session"](name)
+        if not session:
+            raise CdxError(f"Unknown session: {name}")
+        now = _local_now_iso()
+
+        def updater(s):
+            updated = {**s, "updatedAt": now}
+            updated.pop("label", None)
+            return updated
+
+        return store["update_session"](name, updater)
+
     def set_launch_settings(name, settings):
         session = store["get_session"](name)
         if not session:
@@ -1106,6 +1145,7 @@ def create_session_service(options=None):
         row_status = status if enabled else None
         return {
             "session_name": s["name"],
+            "label": s.get("label"),
             "provider": s["provider"],
             "enabled": enabled,
             "active": bool(_session_runtime(s["name"])) if enabled else False,
@@ -1273,6 +1313,7 @@ def create_session_service(options=None):
         )
         return [{
             "name": s["name"],
+            "label": s.get("label"),
             "provider": s["provider"] if has_multiple else None,
             "enabled": s.get("enabled", True) is not False,
             "active": bool(_session_runtime(s["name"])) if s.get("enabled", True) is not False else False,
@@ -1519,6 +1560,8 @@ def create_session_service(options=None):
         "list_sessions": list_sessions,
         "get_session": get_session,
         "set_session_enabled": set_session_enabled,
+        "set_session_label": set_session_label,
+        "clear_session_label": clear_session_label,
         "set_launch_settings": set_launch_settings,
         "unset_launch_settings": unset_launch_settings,
         "record_status": record_status,

package/src/status_view.py

@@ -75,12 +75,19 @@ def _format_credits(value, empty="n/a"):
 
 def _format_status_rows(rows, use_color=False, small=False):
     has_provider = len({r["provider"] for r in rows}) > 1 and not small
+    has_label = any(r.get("label") for r in rows) and not small
     if small:
         headers = ["SESSION", "STATUS", "OK", "5H", "WEEK", "RESETS", "RESET 5H", "RESET WEEK"]
     elif has_provider:
-        headers = ["SESSION", "PROV.", "STATUS", "AUTH", "OK", "5H", "WEEK", "BLOCK", "CR", "RESETS", "RESET 5H", "RESET WEEK", "UPDATED"]
+        headers = ["SESSION", "PROV."]
+        if has_label:
+            headers.append("LABEL")
+        headers += ["STATUS", "AUTH", "OK", "5H", "WEEK", "BLOCK", "CR", "RESETS", "RESET 5H", "RESET WEEK", "UPDATED"]
     else:
-        headers = ["SESSION", "STATUS", "AUTH", "OK", "5H", "WEEK", "BLOCK", "CR", "RESETS", "RESET 5H", "RESET WEEK", "UPDATED"]
+        headers = ["SESSION"]
+        if has_label:
+            headers.append("LABEL")
+        headers += ["STATUS", "AUTH", "OK", "5H", "WEEK", "BLOCK", "CR", "RESETS", "RESET 5H", "RESET WEEK", "UPDATED"]
     if not rows:
         if small:
             return "SESSION  STATUS  OK  5H  WEEK  RESETS  RESET 5H  RESET WEEK\nNo saved sessions yet."
@@ -102,6 +109,8 @@ def _format_status_rows(rows, use_color=False, small=False):
         base = [_format_session_name(r)]
         if has_provider:
             base.append(r.get("provider") or "n/a")
+        if has_label:
+            base.append(r.get("label") or "-")
         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))
         if not small: