cdx-manager 0.3.4 → 0.4.0

package/README.md

@@ -1,12 +1,15 @@
 # CDX Manager
 
+[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.4.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.**
 
 If you use AI coding tools at scale ; multiple accounts, multiple providers : you know the friction: re-authenticating, losing context, juggling environment variables. `cdx` removes all of that.
 
 One command to launch any session. Zero auth juggling.
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.3.4-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
+<img width="213" height="227" alt="image" src="https://github.com/user-attachments/assets/f15f449c-d23e-47fe-a455-17c7386f9be2" />
+<img width="645" height="129" alt="image" src="https://github.com/user-attachments/assets/34bcb395-f832-4da6-9247-3e5022e75e56" />
 
 ---
 
@@ -99,19 +102,24 @@ npm install -g cdx-manager
 With the standalone PowerShell installer:
 
 ```powershell
-irm https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.ps1 | iex
+Invoke-WebRequest https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.ps1 -OutFile install.ps1
+# Optional: set CDX_SHA256 before running if you have a trusted checksum
+powershell -ExecutionPolicy Bypass -File .\install.ps1
 ```
 
 With the standalone GitHub installer:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
+# Optional: set CDX_SHA256 before running if you have a trusted checksum
+sh install.sh
 ```
 
 For a specific version:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh | CDX_VERSION=v0.3.4 sh
+curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
+CDX_VERSION=v0.4.0 sh install.sh
 ```
 
 From source:
@@ -150,6 +158,13 @@ Alternatively, for a non-symlinked global source install:
 npm install -g .
 ```
 
+Security note:
+
+- The standalone installers try to resolve official release checksums from `checksums/release-archives.json`.
+- You can still override verification explicitly through `CDX_SHA256`.
+- Prefer `npm`, `pipx`, or `uv` when you want registry-backed install flows.
+- If you use the standalone script, download it first, inspect it, and prefer a release with an official checksum entry.
+
 ### Environment
 
 By default, `cdx` stores all data under `~/.cdx/`. Override with:
@@ -220,11 +235,13 @@ cdx status
 | `cdx logout <name> [--json]` | Log out of a session |
 | `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 notify <name> --at-reset [--poll seconds] [--once]` | Wait for a session reset time and send a desktop notification when due |
-| `cdx notify --next-ready [--poll seconds] [--once]` | 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 keeps the same row-array shape and writes live Claude refresh warnings to stderr |
+| `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 |
 | `cdx status --small [--refresh]` / `cdx status -s [--refresh]` | Show compact token usage table without provider, blocking quota, credits, and updated columns |
 | `cdx status <name> [--json] [--refresh]` | Show detailed usage breakdown for one session |
 | `cdx --help` | Show usage |
@@ -246,6 +263,8 @@ Commands with machine-readable output:
 - `cdx ren ... --json`
 - `cdx rmv ... --json`
 - `cdx clean ... --json`
+- `cdx export ... --json`
+- `cdx import ... --json`
 - `cdx login ... --json`
 - `cdx logout ... --json`
 - `cdx doctor --json`
@@ -256,6 +275,7 @@ Success payloads follow a shared envelope:
 
 ```json
 {
+  "schema_version": 1,
   "ok": true,
   "action": "add",
   "message": "Created session work (codex)",
@@ -270,6 +290,7 @@ Errors use a shared stderr JSON envelope whenever `--json` is present:
 
 ```json
 {
+  "schema_version": 1,
   "ok": false,
   "error": {
     "code": "invalid_usage",
@@ -279,10 +300,39 @@ Errors use a shared stderr JSON envelope whenever `--json` is present:
 }
 ```
 
+`status --json` and similar commands also use the same envelope and place non-fatal issues in `warnings` instead of mixing plain-text diagnostics into `stderr`.
+
 This makes `cdx-manager` usable from editor plugins, scripts, and desktop apps without scraping human-readable terminal output.
 
 ---
 
+## Backup And Restore
+
+You can move sessions between machines with portable bundles:
+
+```bash
+cdx export backup.cdx
+cdx import backup.cdx
+```
+
+To migrate auth and avoid logging in again, include auth data in an encrypted bundle:
+
+```bash
+export CDX_BUNDLE_PASSPHRASE='choose-a-strong-passphrase'
+cdx export backup-auth.cdx --include-auth --passphrase-env CDX_BUNDLE_PASSPHRASE
+cdx import backup-auth.cdx --passphrase-env CDX_BUNDLE_PASSPHRASE
+```
+
+Notes:
+
+- `--include-auth` is encrypted and requires a passphrase.
+- Without `--passphrase-env`, `cdx` prompts in an interactive terminal.
+- `--sessions work,perso` exports or imports only a subset.
+- `--force` allows overwriting existing destination sessions during import or replacing an existing bundle file during export.
+- Auth bundles contain credentials. Treat them like secrets and delete them after transfer.
+
+---
+
 ## Available Scripts
 
 - `npm test`: run the Python test suite
@@ -321,6 +371,7 @@ src/
   cli.py                # Top-level command router
   cli_commands.py       # Command handlers and argument handling
   cli_render.py         # Terminal formatting, tables, colors, and errors
+  backup_bundle.py      # Portable session bundle encoding/decoding + auth encryption
   status_view.py        # Status table/detail rendering and priority ranking
   provider_runtime.py   # Provider launch/auth commands, transcripts, signals
   claude_refresh.py     # Claude usage refresh orchestration

package/changelogs/CHANGELOGS_0_4_0.md

@@ -0,0 +1,36 @@
+# CHANGELOGS_0_4_0
+
+Release date: 2026-04-16
+
+## CDX Manager 0.4.0
+
+CDX Manager 0.4.0 adds portable session backup and restore, surfaces cached release-update notices inside the CLI, and tightens Codex status isolation across multiple accounts.
+
+### Portable session bundles
+
+- Added `cdx export <file>` and `cdx import <file>` for moving sessions between machines.
+- Added optional encrypted auth export with `--include-auth` and interactive or environment-driven passphrase handling.
+- Added subset export/import support with `--sessions`.
+- Preserved per-session state alongside session records so imported environments keep their local metadata.
+- Added bundle schema validation and integrity checks during import.
+
+### Update awareness and installer hardening
+
+- Added cached GitHub release checks so the CLI can warn when a newer `cdx-manager` release is available without hitting the network on every command.
+- Surfaced update notices in interactive output and structured JSON warnings.
+- Hardened the standalone install scripts to consume official release-archive checksums when available.
+- Documented the checksum-backed installer flow and backup/restore usage in the README.
+
+### Status isolation fix
+
+- Fixed Codex status parsing so boxed blank lines in TUI transcripts no longer drop the `Account:` context line.
+- Restored account-aware status selection when multiple sessions contain similar `/status` blocks.
+- Added regression coverage for mixed-account transcript selection and bundle export/import flows.
+
+### Validation
+
+```bash
+npm run lint
+npm test
+python3 -m build --no-isolation
+```

package/checksums/release-archives.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "releases": {
+    "v0.3.4": {
+      "github_tarball_sha256": "8e8111d6ec41b819fc0249800f175b5741cd11b1439c7e88a3feec770774b12d",
+      "github_zip_sha256": "e0bd79f731d86b83787e99b8f2220c8c5fbaa3d7507ebc52823aa5b8d11f0666"
+    }
+  }
+}

package/install.ps1

@@ -1,11 +1,16 @@
 param(
     [string]$Version = $env:CDX_VERSION,
-    [string]$Prefix = $env:CDX_PREFIX
+    [string]$Prefix = $env:CDX_PREFIX,
+    [string]$Sha256 = $env:CDX_SHA256,
+    [string]$ChecksumsUrl = $env:CDX_CHECKSUMS_URL
 )
 
 $ErrorActionPreference = "Stop"
 
 $repo = "AlexAgo83/cdx-manager"
+if (-not $ChecksumsUrl) {
+    $ChecksumsUrl = "https://raw.githubusercontent.com/$repo/main/checksums/release-archives.json"
+}
 
 function Require-Command {
     param([string]$Name)
@@ -44,6 +49,21 @@ New-Item -ItemType Directory -Force -Path $tmpRoot, $extractRoot, $binDir, $inst
 
 try {
     Invoke-WebRequest -Uri $archiveUrl -OutFile $archivePath
+    if (-not $Sha256) {
+        try {
+            $checksums = Invoke-RestMethod -Uri $ChecksumsUrl
+            $Sha256 = $checksums.releases.$tag.github_zip_sha256
+        } catch {
+        }
+    }
+    if ($Sha256) {
+        $actualSha256 = (Get-FileHash -Algorithm SHA256 -Path $archivePath).Hash.ToLowerInvariant()
+        if ($actualSha256 -ne $Sha256.ToLowerInvariant()) {
+            throw "cdx install: checksum mismatch for $tag`nexpected: $Sha256`nactual:   $actualSha256"
+        }
+    } else {
+        Write-Warning "No official checksum available for $tag; continuing without verification."
+    }
     Expand-Archive -Path $archivePath -DestinationPath $extractRoot -Force
 
     $sourceDir = Get-ChildItem -Path $extractRoot -Directory | Select-Object -First 1

package/install.sh

@@ -6,6 +6,7 @@ VERSION="${CDX_VERSION:-}"
 PREFIX="${PREFIX:-$HOME/.local}"
 BIN_DIR="${BIN_DIR:-$PREFIX/bin}"
 INSTALL_ROOT="${CDX_INSTALL_ROOT:-$PREFIX/share/cdx-manager}"
+CHECKSUMS_URL="${CDX_CHECKSUMS_URL:-https://raw.githubusercontent.com/$REPO/main/checksums/release-archives.json}"
 
 need() {
   if ! command -v "$1" >/dev/null 2>&1; then
@@ -18,6 +19,38 @@ need curl
 need tar
 need python3
 
+sha256_file() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+    return
+  fi
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | awk '{print $1}'
+    return
+  fi
+  echo "cdx install: missing checksum tool (sha256sum or shasum)" >&2
+  exit 1
+}
+
+resolve_expected_sha256() {
+  curl -fsSL "$CHECKSUMS_URL" |
+    python3 - "$1" <<'PY'
+import json
+import sys
+
+tag = sys.argv[1]
+try:
+    payload = json.load(sys.stdin)
+except Exception:
+    raise SystemExit(1)
+
+release = (payload.get("releases") or {}).get(tag) or {}
+value = release.get("github_tarball_sha256")
+if value:
+    print(value)
+PY
+}
+
 if [ -z "$VERSION" ]; then
   VERSION="$(
     curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" |
@@ -38,6 +71,24 @@ trap cleanup EXIT INT TERM
 
 ARCHIVE_URL="https://github.com/$REPO/archive/refs/tags/$TAG.tar.gz"
 curl -fsSL "$ARCHIVE_URL" -o "$TMP_DIR/cdx-manager.tar.gz"
+
+EXPECTED_SHA256="${CDX_SHA256:-}"
+if [ -z "$EXPECTED_SHA256" ]; then
+  EXPECTED_SHA256="$(resolve_expected_sha256 "$TAG" 2>/dev/null || true)"
+fi
+
+if [ -n "$EXPECTED_SHA256" ]; then
+  ACTUAL_SHA256="$(sha256_file "$TMP_DIR/cdx-manager.tar.gz")"
+  if [ "$ACTUAL_SHA256" != "$EXPECTED_SHA256" ]; then
+    echo "cdx install: checksum mismatch for $TAG" >&2
+    echo "expected: $EXPECTED_SHA256" >&2
+    echo "actual:   $ACTUAL_SHA256" >&2
+    exit 1
+  fi
+else
+  echo "cdx install: warning: no official checksum available for $TAG; continuing without verification" >&2
+fi
+
 tar -xzf "$TMP_DIR/cdx-manager.tar.gz" -C "$TMP_DIR"
 
 SRC_DIR="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -25,6 +25,7 @@
   },
   "files": [
     "bin",
+    "checksums",
     "changelogs",
     "src",
     "install.sh",

package/pyproject.toml

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

package/src/backup_bundle.py

@@ -0,0 +1,134 @@
+import base64
+import hashlib
+import hmac
+import json
+import os
+from datetime import datetime, timezone
+
+from .errors import CdxError
+
+
+BUNDLE_SCHEMA_VERSION = 1
+_SALT_BYTES = 16
+_NONCE_BYTES = 16
+_SCRYPT_N = 2 ** 14
+_SCRYPT_R = 8
+_SCRYPT_P = 1
+_PBKDF2_ITERATIONS = 200000
+
+
+def _now_iso():
+    return datetime.now(timezone.utc).astimezone().isoformat()
+
+
+def _b64_encode(data):
+    return base64.b64encode(data).decode("ascii")
+
+
+def _b64_decode(data):
+    try:
+        return base64.b64decode(data.encode("ascii"))
+    except (AttributeError, ValueError, UnicodeEncodeError) as error:
+        raise CdxError("Bundle contains invalid base64 data.") from error
+
+
+def read_bundle_meta(data):
+    try:
+        wrapper = json.loads(data.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise CdxError("Invalid bundle format.") from error
+
+    if wrapper.get("schema_version") != BUNDLE_SCHEMA_VERSION:
+        raise CdxError("Unsupported bundle schema version.")
+    return wrapper
+
+
+def _derive_keys(passphrase, salt):
+    if not passphrase:
+        raise CdxError("A non-empty passphrase is required for bundles that include auth data.")
+    if isinstance(passphrase, str):
+        passphrase = passphrase.encode("utf-8")
+    if hasattr(hashlib, "scrypt"):
+        key_material = hashlib.scrypt(
+            passphrase,
+            salt=salt,
+            n=_SCRYPT_N,
+            r=_SCRYPT_R,
+            p=_SCRYPT_P,
+            dklen=64,
+        )
+    else:
+        key_material = hashlib.pbkdf2_hmac(
+            "sha256",
+            passphrase,
+            salt,
+            _PBKDF2_ITERATIONS,
+            dklen=64,
+        )
+    return key_material[:32], key_material[32:]
+
+
+def _xor_keystream(data, key, nonce):
+    output = bytearray()
+    counter = 0
+    while len(output) < len(data):
+        block = hashlib.sha256(key + nonce + counter.to_bytes(8, "big")).digest()
+        output.extend(block)
+        counter += 1
+    return bytes(a ^ b for a, b in zip(data, output[:len(data)]))
+
+
+def encode_bundle(payload, include_auth=False, passphrase=None):
+    payload_bytes = json.dumps(payload, indent=2, sort_keys=True).encode("utf-8")
+    wrapper = {
+        "schema_version": BUNDLE_SCHEMA_VERSION,
+        "bundle_version": 1,
+        "created_at": _now_iso(),
+        "include_auth": bool(include_auth),
+        "encrypted": bool(include_auth),
+        "session_names": [item["name"] for item in payload.get("sessions", [])],
+    }
+    if include_auth:
+        salt = os.urandom(_SALT_BYTES)
+        nonce = os.urandom(_NONCE_BYTES)
+        enc_key, mac_key = _derive_keys(passphrase, salt)
+        ciphertext = _xor_keystream(payload_bytes, enc_key, nonce)
+        mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+        wrapper.update({
+            "salt": _b64_encode(salt),
+            "nonce": _b64_encode(nonce),
+            "hmac_sha256": _b64_encode(mac),
+            "payload": _b64_encode(ciphertext),
+        })
+    else:
+        wrapper["payload"] = _b64_encode(payload_bytes)
+    return json.dumps(wrapper, indent=2).encode("utf-8")
+
+
+def decode_bundle(data, passphrase=None):
+    wrapper = read_bundle_meta(data)
+
+    encrypted = bool(wrapper.get("encrypted"))
+    payload_b64 = wrapper.get("payload")
+    if not isinstance(payload_b64, str):
+        raise CdxError("Bundle payload is missing.")
+
+    if encrypted:
+        salt = _b64_decode(wrapper.get("salt", ""))
+        nonce = _b64_decode(wrapper.get("nonce", ""))
+        expected_mac = _b64_decode(wrapper.get("hmac_sha256", ""))
+        ciphertext = _b64_decode(payload_b64)
+        enc_key, mac_key = _derive_keys(passphrase, salt)
+        actual_mac = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+        if not hmac.compare_digest(actual_mac, expected_mac):
+            raise CdxError("Invalid bundle passphrase or corrupted bundle.")
+        payload_bytes = _xor_keystream(ciphertext, enc_key, nonce)
+    else:
+        payload_bytes = _b64_decode(payload_b64)
+
+    try:
+        payload = json.loads(payload_bytes.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise CdxError("Bundle payload is corrupt.") from error
+
+    return {"meta": wrapper, "payload": payload}

package/src/cli.py

@@ -5,11 +5,14 @@ import os
 import sys
 
 from .cli_commands import (
+    API_SCHEMA_VERSION,
     STATUS_USAGE,
     handle_add,
     handle_clean,
     handle_copy,
     handle_doctor,
+    handle_export,
+    handle_import,
     handle_launch,
     handle_login,
     handle_logout,
@@ -39,8 +42,9 @@ from .status_view import (
     _format_status_detail,
     _format_status_rows,
 )
+from .update_check import check_for_update
 
-VERSION = "0.3.4"
+VERSION = "0.4.0"
 
 
 # ---------------------------------------------------------------------------
@@ -64,6 +68,8 @@ def _print_help(use_color=False):
         f"  {_style('cdx logout <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 notify <name> --at-reset [--json]', '36', use_color)}",
@@ -96,6 +102,7 @@ def format_json_error(error):
     elif "requires an interactive terminal" in message or "requires confirmation" in message:
         code = "interactive_terminal_required"
     return json.dumps({
+        "schema_version": API_SCHEMA_VERSION,
         "ok": False,
         "error": {
             "code": code,
@@ -105,6 +112,35 @@ def format_json_error(error):
     }, indent=2)
 
 
+def _get_update_notice(service, env, options):
+    checker = options.get("checkForUpdate") or check_for_update
+    return checker(
+        service["base_dir"],
+        VERSION,
+        env=env,
+        now_fn=options.get("now"),
+    )
+
+
+def _update_warning_payload(notice):
+    if not notice:
+        return []
+    message = f"Update available: cdx-manager {notice['latest_version']} (current {VERSION})"
+    return [{
+        "code": "update_available",
+        "message": message,
+        "latest_version": notice["latest_version"],
+        "url": notice.get("url"),
+    }]
+
+
+def _update_warning_text(notice):
+    if not notice:
+        return None
+    suffix = f" {notice['url']}" if notice.get("url") else ""
+    return f"Update available: cdx-manager {notice['latest_version']} (current {VERSION}).{suffix}"
+
+
 # ---------------------------------------------------------------------------
 # main()
 # ---------------------------------------------------------------------------
@@ -145,11 +181,15 @@ def main(argv, options=None):
 
     if argv == ["--json"]:
         rows = service["format_list_rows"]()
-        out(f"{json.dumps(_list_json_payload(rows), indent=2)}\n")
+        notice = _get_update_notice(service, env, options)
+        out(f"{json.dumps(_list_json_payload(rows, notice=notice), indent=2)}\n")
         return 0
 
     if not argv:
+        notice = _get_update_notice(service, env, options)
         out(f"{_format_sessions(service, use_color=use_color)}\n")
+        if notice:
+            out(f"{_style(_update_warning_text(notice), '33', use_color)}\n")
         return 0
 
     command, *rest = argv
@@ -165,6 +205,9 @@ def main(argv, options=None):
         "spawn": spawn,
         "spawn_sync": spawn_sync,
         "stdin_is_tty": stdin_is_tty,
+        "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"
+        ) else None,
         "use_color": use_color,
     }
 
@@ -183,6 +226,12 @@ def main(argv, options=None):
     if command == "clean":
         return handle_clean(rest, ctx)
 
+    if command == "export":
+        return handle_export(rest, ctx)
+
+    if command == "import":
+        return handle_import(rest, ctx)
+
     if command == "doctor":
         return handle_doctor(rest, ctx)
 
@@ -215,12 +264,13 @@ def main(argv, options=None):
     raise CdxError(f"Unknown command: {command}. Use cdx --help.")
 
 
-def _list_json_payload(rows):
+def _list_json_payload(rows, notice=None):
     return {
+        "schema_version": API_SCHEMA_VERSION,
         "ok": True,
         "action": "list",
         "message": "Listed known sessions",
-        "warnings": [],
+        "warnings": _update_warning_payload(notice),
         "sessions": rows,
     }