cdx-manager 0.11.0 → 0.11.2

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.2-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`
@@ -679,7 +683,7 @@ Without `--yes`, an interactive confirmation is required. `cdx` sends an idempot
 ## Troubleshooting
 
 - **`cdx <name>` fails with "not authenticated"** — run `cdx login <name>` first.
-- **One of two Codex accounts keeps asking for login** — run `cdx doctor --json` and inspect each Codex session's `codex_auth_file` and `codex_live_auth` checks. Codex sessions use isolated `CODEX_HOME` directories, but 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.
+- **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.

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/changelogs/CHANGELOGS_0_11_2.md

@@ -0,0 +1,27 @@
+# CDX Manager 0.11.2
+
+## Highlights
+
+- Improved Codex Business auth diagnostics without changing login or launch behavior.
+- Added stale-auth log warnings to help repair the affected profile only.
+- Documented the Business `account_id` ambiguity and the `cdx login <name>` repair path.
+
+## Changes
+
+### Codex Business auth diagnostics
+
+`cdx doctor` now reports shared Codex `tokens.account_id` values as workspace-level evidence on Business plans, not proof that two profiles are using the same user account. When recent `/status` transcript output exposes different observed users for profiles that share the same account id, doctor marks that as expected instead of a duplicate-user warning.
+
+Codex auth diagnostics now include a masked `account_id` and an observed account from recent logs when available. Raw tokens remain excluded from JSON output.
+
+### Stale auth hints
+
+`cdx doctor` scans recent Codex profile logs for common expired-auth markers such as `401`, `token_expired`, and `authentication token is expired`. When found, it emits `codex_stale_auth_logs` with a direct `cdx login <name>` recommendation for the affected isolated profile.
+
+## Validation
+
+- `npm run lint`
+- `npm test`
+- `logics-manager health`
+- `logics-manager lint --require-status`
+- `logics-manager audit --group-by-doc`

package/checksums/release-archives.json

@@ -136,6 +136,14 @@
     "v0.10.0": {
       "github_tarball_sha256": "20c473f4b17806d565c454ad4aa28758433665d8431251ebb937ab6a909e4adb",
       "github_zip_sha256": "b6a7be359d8dc2a11d8c77749878875419fabd7cd5a6951502dec09d7791e211"
+    },
+    "v0.11.0": {
+      "github_tarball_sha256": "bc42f83f20ba1c6ff81f824c382801457f93cf8cb166acbe952c12d009560a70",
+      "github_zip_sha256": "1c03b4f03f53c46d0a5ba580fc8ade7b26fa3cb1bb5f029f703681f136b9ac1f"
+    },
+    "v0.11.1": {
+      "github_tarball_sha256": "33ee5a76cd217007468ea620fa725644dfd62179585551b5703129c00a5094d5",
+      "github_zip_sha256": "8b53832ad2af109c22a898782bd36e1408356fc2bd0c3f99ca2ffb1262e2325b"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "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.2"
 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.2"
 
 # 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/health.py

@@ -3,11 +3,13 @@ import os
 import shutil
 import sys
 import tempfile
+from datetime import datetime, timezone
 from urllib.parse import quote, unquote
 
 from .cli_render import _pad_table, _style
 from .config import PROVIDER_CODEX
 from .provider_runtime import codex_auth_diagnostic
+from .status_source import _extract_account_identity
 
 
 def _encode(name):
@@ -73,6 +75,7 @@ def collect_health_report(service, base_dir, env=None, spawn_sync=None):
     issues.append(_check_cdx_home(base_dir))
     sessions = service["list_sessions"]()
     session_names = {session["name"] for session in sessions}
+    codex_diagnostics = []
     for session in sessions:
         name = session["name"]
         root = session.get("sessionRoot") or service["get_session_root"](name)
@@ -82,16 +85,19 @@ def collect_health_report(service, base_dir, env=None, spawn_sync=None):
         if not os.path.isfile(state_path):
             issues.append(_issue("FAIL", "missing_state", f"session {name} state file is missing", state_path, True))
         if session.get("provider") == PROVIDER_CODEX:
-            issues.extend(_codex_auth_issues(session, spawn_sync=spawn_sync, env=env))
+            diag = codex_auth_diagnostic(session, spawn_sync=spawn_sync, env_override=env)
+            diag["observed_account"] = _recent_codex_observed_account(diag.get("auth_home"))
+            codex_diagnostics.append((session, diag))
+            issues.extend(_codex_auth_issues(session, diag))
 
+    issues.extend(_codex_shared_account_id_issues(codex_diagnostics))
     issues.extend(_collect_profile_issues(base_dir, session_names))
     return {"base_dir": base_dir, "issues": issues, "summary": summarize_health(issues)}
 
 
-def _codex_auth_issues(session, spawn_sync=None, env=None):
+def _codex_auth_issues(session, diag):
     name = session["name"]
-    diag = codex_auth_diagnostic(session, spawn_sync=spawn_sync, env_override=env)
-    identity = diag.get("account_email") or "unknown account"
+    identity = diag.get("account_email") or diag.get("observed_account") or "unknown account"
     issues = [
         _issue(
             "OK" if diag.get("auth_json_exists") else "WARN",
@@ -103,6 +109,8 @@ def _codex_auth_issues(session, spawn_sync=None, env=None):
                 "auth_json_exists": diag.get("auth_json_exists"),
                 "local_tokens_present": diag.get("local_tokens_present"),
                 "account_email": diag.get("account_email"),
+                "observed_account": diag.get("observed_account"),
+                "account_id": _mask_identifier(diag.get("account_id")),
             },
         )
     ]
@@ -120,9 +128,126 @@ def _codex_auth_issues(session, spawn_sync=None, env=None):
             "live_error": diag.get("live_error"),
         },
     ))
+    stale_auth = _recent_codex_auth_error(diag.get("auth_home"))
+    if stale_auth:
+        issues.append(_issue(
+            "WARN",
+            "codex_stale_auth_logs",
+            f"session {name} recent Codex logs mention expired auth; run cdx login {name} if disconnects continue",
+            {
+                "session": name,
+                "auth_home": diag.get("auth_home"),
+                "source": stale_auth["source"],
+                "mtime": stale_auth["mtime"],
+                "markers": stale_auth["markers"],
+            },
+        ))
     return issues
 
 
+def _codex_shared_account_id_issues(codex_diagnostics):
+    by_account_id = {}
+    for session, diag in codex_diagnostics:
+        account_id = diag.get("account_id")
+        if account_id:
+            by_account_id.setdefault(account_id, []).append((session, diag))
+
+    issues = []
+    for account_id, rows in sorted(by_account_id.items()):
+        if len(rows) < 2:
+            continue
+        identities = sorted({
+            _identity_user_part(diag.get("account_email") or diag.get("observed_account"))
+            for _session, diag in rows
+            if _identity_user_part(diag.get("account_email") or diag.get("observed_account"))
+        })
+        sessions = [session["name"] for session, _diag in rows]
+        status = "OK" if len(identities) > 1 else "WARN"
+        message = (
+            "Codex profiles share a Business account_id but observed different users; account_id is not a user identity"
+            if status == "OK"
+            else "Codex profiles share account_id; on Business plans this may be a workspace id, not proof of duplicate user auth"
+        )
+        issues.append(_issue(
+            status,
+            "codex_shared_account_id",
+            message,
+            {
+                "sessions": sessions,
+                "account_id": _mask_identifier(account_id),
+                "observed_identities": identities,
+            },
+        ))
+    return issues
+
+
+def _identity_user_part(value):
+    if not value:
+        return None
+    return str(value).strip().lower().split()[0].split("(", 1)[0]
+
+
+def _mask_identifier(value):
+    if not value:
+        return None
+    text = str(value)
+    return text if len(text) <= 8 else f"{text[:6]}...{text[-4:]}"
+
+
+def _recent_codex_observed_account(auth_home):
+    for path in _recent_codex_log_paths(auth_home):
+        text = _read_tail(path)
+        account = _extract_account_identity(text)
+        if account:
+            return account
+    return None
+
+
+def _recent_codex_auth_error(auth_home):
+    markers = ("token_expired", "authentication token is expired", "http 401")
+    for path in _recent_codex_log_paths(auth_home):
+        text = _read_tail(path).lower()
+        found = [marker for marker in markers if marker in text]
+        if found:
+            try:
+                mtime = datetime.fromtimestamp(os.path.getmtime(path), timezone.utc).isoformat().replace("+00:00", "Z")
+            except OSError:
+                mtime = None
+            return {"source": path, "mtime": mtime, "markers": found}
+    return None
+
+
+def _recent_codex_log_paths(auth_home):
+    if not auth_home:
+        return []
+    candidates = []
+    for root in (os.path.join(auth_home, "log"), os.path.join(auth_home, "sessions")):
+        if not os.path.isdir(root):
+            continue
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [name for name in dirnames if name not in {"cache", "plugins", "skills", "sqlite"}]
+            for filename in filenames:
+                if filename.endswith((".log", ".jsonl")):
+                    path = os.path.join(dirpath, filename)
+                    try:
+                        stat = os.stat(path)
+                    except OSError:
+                        continue
+                    candidates.append((stat.st_mtime, path))
+    return [path for _mtime, path in sorted(candidates, reverse=True)[:16]]
+
+
+def _read_tail(path, max_bytes=128 * 1024):
+    try:
+        with open(path, "rb") as handle:
+            handle.seek(0, os.SEEK_END)
+            size = handle.tell()
+            handle.seek(max(0, size - max_bytes))
+            return handle.read().decode("utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
 def _check_cdx_home(base_dir):
     try:
         os.makedirs(base_dir, exist_ok=True)

package/src/provider_runtime.py

@@ -166,6 +166,19 @@ def _read_codex_account_email(auth_home):
     return None
 
 
+def _read_codex_account_id(auth_home):
+    try:
+        with open(os.path.join(auth_home, "auth.json"), encoding="utf-8") as handle:
+            auth = json.load(handle)
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
+        return None
+    tokens = auth.get("tokens") if isinstance(auth, dict) else {}
+    account_id = tokens.get("account_id") if isinstance(tokens, dict) else None
+    if not account_id:
+        return None
+    return str(account_id).strip() or None
+
+
 def codex_auth_diagnostic(session, spawn_sync=None, env_override=None):
     auth_home = _get_auth_home(session)
     auth_path = os.path.join(auth_home, "auth.json")
@@ -174,6 +187,7 @@ def codex_auth_diagnostic(session, spawn_sync=None, env_override=None):
         "auth_json_exists": os.path.isfile(auth_path),
         "local_tokens_present": _has_local_codex_auth(auth_home),
         "account_email": _read_codex_account_email(auth_home),
+        "account_id": _read_codex_account_id(auth_home),
         "live_status": "unknown",
         "live_error": None,
     }

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: