cdx-manager 0.7.8 → 0.9.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.7.8-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.8.0-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.**
 
@@ -42,6 +42,7 @@ One command to launch any session. Zero auth juggling.
 - **Persistent launch settings.** Pin per-session power, permission, and fast-mode preferences once; `cdx` reapplies them on every launch until you unset them.
 - **Launch history.** Inspect recent launches with provider, result, duration, working directory, launch settings, and transcript path.
 - **Update prompts.** Periodic update checks surface `cdx update` directly in the `cdx`, `cdx status`, and launch output when a newer release is available. When `logics-manager` is installed, `cdx` can also suggest `logics-manager self-update`.
+- **Logics viewer shortcut.** `cdx view` opens the Logics browser/focus viewer through `logics-manager view` when the companion CLI is installed; `cdx view --json` reports availability and update diagnostics without opening the viewer.
 - **Shared handoff context.** Keep a per-workspace Markdown context, or build one from a source session transcript, and install it into another assistant session before switching providers or accounts.
 - **Passive status resolution.** Codex status is read from the local Codex app-server rate-limit API when available, with legacy transcript/history parsing kept as a fallback.
 - **Session transcript capture.** Every launch is recorded to a local log file via `script`, giving you a full terminal transcript for each session.
@@ -136,7 +137,7 @@ For a specific version:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AlexAgo83/cdx-manager/main/install.sh -o install.sh
-CDX_VERSION=v0.7.8 sh install.sh
+CDX_VERSION=v0.8.0 sh install.sh
 ```
 
 From source:
@@ -189,6 +190,13 @@ Security note:
 - 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.
 
+Release maintainer note:
+
+- Before publishing npm or PyPI packages, run `npm run release:validate`.
+- The release tag must match `package.json`, `pyproject.toml`, `src/cli.py`, and `VERSION`.
+- `checksums/release-archives.json` must include the matching `vX.Y.Z` entry with both `github_tarball_sha256` and `github_zip_sha256`.
+- Use `python3 scripts/update_release_checksums.py --tag vX.Y.Z` after the GitHub tag archives exist, commit the checksum update to `main`, then publish the GitHub release only after `npm run release:validate`, `npm run lint`, and `npm test` pass.
+
 ### Environment
 
 By default, `cdx` stores all data under `~/.cdx/`. Override with:
@@ -344,6 +352,7 @@ cdx history --summary --from 2026-05-01 --to 2026-05-28
 | `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 view [--json]` | Open the Logics browser/focus viewer by delegating to `logics-manager view`; JSON mode reports diagnostics without launching it |
 | `cdx update [--check] [--yes] [--json] [--version TAG]` | Update cdx-manager using the installer that matches how it was installed |
 | `cdx ready [--refresh] [--json]` | Schedule an OS notification for the next cooling-down assistant that becomes ready, then return immediately |
 | `cdx notify <name> --at-reset [--poll seconds] [--once] [--schedule] [--refresh] [--json]` | Wait for a session reset time or schedule an OS wake-up notification when due |
@@ -387,6 +396,7 @@ Commands with machine-readable output:
 - `cdx last --json`
 - `cdx doctor --json`
 - `cdx repair --json`
+- `cdx view --json`
 - `cdx update --json`
 - `cdx ready --json`
 - `cdx notify ... --json`
@@ -500,7 +510,8 @@ Notes:
 
 - `npm test`: run the Python test suite
 - `npm run test:py`: run the Python unit tests through the portable launcher
-- `npm run lint`: check the Node launcher and byte-compile the Python sources and tests
+- `npm run lint`: check project guidance, the Node launcher, and byte-compile the Python sources, scripts, and tests
+- `npm run release:validate`: verify version alignment and required GitHub release archive checksum metadata before publication
 - `npm run link`: link `cdx` globally for local development (`npm link`)
 - `npm run unlink`: remove the global link
 

package/changelogs/CHANGELOGS_0_7_8.md

@@ -5,6 +5,7 @@ Release date: 2026-06-08
 ## Launch Guidance
 
 - Added update guidance for `logics-manager` so `cdx` can surface a newer companion CLI version alongside the existing `cdx-manager` update notice.
+- Added `cdx view` as a thin shortcut for `logics-manager view`, plus `cdx view --json` diagnostics for companion availability and update suggestions.
 - Added RTK launch preference handling so noisy assistant shell commands can be wrapped with `rtk` when the session setting asks for filtered command output.
 - Extended provider launch metadata and health checks so companion tool hints appear without making `logics-manager` or RTK hard runtime dependencies.
 
@@ -16,9 +17,20 @@ Release date: 2026-06-08
 
 - Updated package metadata, CLI version output, README badge, pinned installer example, and release changelog to `v0.7.8`.
 
+## Release Governance
+
+- Added `npm run release:validate` as the required pre-publication gate for version alignment and GitHub archive checksum metadata.
+- The npm and PyPI publication workflows now run the checksum/version gate before registry upload.
+- Release prep now requires generating `checksums/release-archives.json` entries for the matching `vX.Y.Z` tag before publication.
+
+## Maintainability
+
+- Extracted the `cdx view` command domain into a dedicated module while keeping the existing CLI routing and JSON diagnostics unchanged.
+
 ## Validation and Regression Evidence
 
 - `npm run lint`
+- `npm run release:validate`
 - `npm test`
 - `python -m unittest discover -s test -p 'test_*_py.py'`
 - `python3 -m logics_manager lint --require-status`

package/changelogs/CHANGELOGS_0_8_0.md

@@ -0,0 +1,39 @@
+# Changelog (`0.7.8 -> 0.8.0`)
+
+Release date: 2026-06-08
+
+## Release Governance
+
+- Added a pre-publication release checksum gate that validates version alignment across `package.json`, `pyproject.toml`, `src/cli.py`, and `VERSION`.
+- Publication workflows now require matching GitHub archive checksum metadata before npm or PyPI upload.
+- Documented the release ordering for version bump, tag/archive checksum generation, checksum commit, and publication.
+
+## Logics Workflow
+
+- Versioned `LOGICS.md` as normal project guidance instead of treating it as an ignored local artifact.
+- Added project documentation validation to ensure core Logics command families stay documented.
+- Added `cdx view` as a thin shortcut for `logics-manager view`.
+- Added `cdx view --json` diagnostics for companion availability, delegated command details, failure reason, and update suggestions.
+
+## Maintainability
+
+- Extracted the `cdx view` command domain into `src/cli_view.py` while keeping `src/cli_commands.py` as a compatibility facade for handler routing.
+
+## Release Metadata
+
+- Updated package metadata, CLI version output, README badge, pinned installer example, and release changelog to `v0.8.0`.
+
+## Validation and Regression Evidence
+
+- `python -m py_compile bin/cdx src/*.py test/test_*_py.py`
+- `python -m unittest discover -s test -p 'test_*_py.py'`
+- `npm pack --dry-run`
+- `npm run lint`
+- `npm test`
+- `logics-manager lint --require-status`
+- `logics-manager audit`
+- `git diff --check`
+- `node bin/cdx.js --version`
+- `python3 bin/cdx --version`
+- `python -m build`
+- `python -m twine check dist/*`

package/changelogs/CHANGELOGS_0_9_0.md

@@ -0,0 +1,14 @@
+# CDX Manager 0.9.0
+
+## Highlights
+
+- Adds an observable assistant run registry for CDX sessions.
+- Generates the Logics corpus for assistant-run observability so follow-up work can be tracked from requests through closeout.
+- Closes the observable run registry workflow chain after validation.
+
+## Validation
+
+- `npm run prepublishOnly`
+- `npm pack --dry-run`
+- `logics-manager lint --require-status`
+- `logics-manager audit --legacy-cutoff-version 1.1.0 --group-by-doc`

package/checksums/release-archives.json

@@ -56,6 +56,14 @@
     "v0.7.6": {
       "github_tarball_sha256": "cf6390c2071c710edd7c55d89fd75914e1d94ae5a62330d6fe15029484f88c13",
       "github_zip_sha256": "f58be3078daaa9523053dab7b59d681dfb359d5f2a94276aa46000dd7f1360ed"
+    },
+    "v0.7.8": {
+      "github_tarball_sha256": "8afa0c1f0293a973973158d249aaa627d3aede785cd5a36941be067633580e2a",
+      "github_zip_sha256": "207e000dc1192d12324616cc4671f42cf07c22e2eb895556117b681ab5a6ab93"
+    },
+    "v0.8.0": {
+      "github_tarball_sha256": "62cd461f9e22636bb85d801e21209b1762859b6662623e74c01fd40c107ea29a",
+      "github_zip_sha256": "4674c8b61110f52b99c76312e9962202a2e8fc6928327f8927781f45eeaa980f"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.7.8",
+  "version": "0.9.0",
   "description": "Terminal session manager for Codex and Claude accounts.",
   "license": "MIT",
   "author": "Alexandre Agostini",
@@ -44,8 +44,9 @@
   "scripts": {
     "test": "npm run test:py",
     "test:py": "node bin/python-runner.js -m unittest discover -s test -p test_*_py.py",
-    "lint": "node --check bin/cdx.js && node --check bin/python-runner.js && node bin/python-runner.js -m py_compile bin/cdx src/*.py test/test_*_py.py",
-    "prepublishOnly": "npm run lint && npm test",
+    "lint": "node --check bin/cdx.js && node --check bin/python-runner.js && node bin/python-runner.js scripts/verify_project_docs.py && node bin/python-runner.js -m py_compile bin/cdx src/*.py scripts/*.py test/test_*_py.py",
+    "release:validate": "node bin/python-runner.js scripts/verify_release_checksums.py",
+    "prepublishOnly": "npm run release:validate && npm run lint && npm test",
     "link": "npm link",
     "unlink": "npm unlink -g cdx-manager"
   }

package/pyproject.toml

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

package/src/cli.py

@@ -31,12 +31,16 @@ from .cli_commands import (
     handle_repair,
     handle_rename,
     handle_run,
+    handle_run_report,
+    handle_run_status,
+    handle_runs,
     handle_select,
     handle_stats,
     handle_status,
     handle_set,
     handle_unset,
     handle_update,
+    handle_view,
 )
 from .cli_render import (
     _format_sessions,
@@ -60,7 +64,7 @@ from .status_view import (
 )
 from .update_check import check_for_update, check_logics_manager_for_update
 
-VERSION = "0.7.8"
+VERSION = "0.9.0"
 
 
 # ---------------------------------------------------------------------------
@@ -80,6 +84,9 @@ def _print_help(use_color=False):
         f"  {_style('cdx next [--json] [--refresh]', '36', use_color)}",
         f"  {_style('cdx select --provider PROVIDER [--min-reasoning-effort low|medium|high] [--min-power low|medium|high] [--require-ready] [--refresh] --json', '36', use_color)}",
         f"  {_style('cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--reasoning-effort low|medium|high] [--power low|medium|high] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json', '36', use_color)}",
+        f"  {_style('cdx runs [--limit N] --json', '36', use_color)}",
+        f"  {_style('cdx run-status <run_id> --json', '36', use_color)}",
+        f"  {_style('cdx run-report <run_id> --json', '36', use_color)}",
         f"  {_style('cdx context show|path|init|edit|clear|set [text...] [--json]', '36', use_color)}",
         f"  {_style('cdx config <name> [--json]', '36', use_color)}",
         f"  {_style('cdx configs [--json]', '36', use_color)}",
@@ -104,6 +111,7 @@ def _print_help(use_color=False):
         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 view [--json]', '36', use_color)}",
         f"  {_style('cdx update [--check] [--yes] [--json] [--version TAG]', '36', use_color)}",
         f"  {_style('cdx ready [--refresh] [--json]', '36', use_color)}",
         f"  {_style('cdx notify <name> --at-reset [--schedule] [--refresh] [--json]', '36', use_color)}",
@@ -275,7 +283,7 @@ def main(argv, options=None):
         "version": VERSION,
         "cwd": options.get("cwd") or os.getcwd(),
         "update_notices": _get_update_notices(service, env, options) if command not in (
-            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "update", "ready", "notify", "next", "context", "config", "configs", "set", "unset", "power", "perm", "fast", "model", "history", "stats", "handoff", "login", "logout", "disable", "enable", "export", "import", "select", "run", "help", "version"
+            "add", "cp", "ren", "rename", "mv", "rmv", "clean", "doctor", "repair", "view", "update", "ready", "notify", "next", "context", "config", "configs", "set", "unset", "power", "perm", "fast", "model", "history", "stats", "handoff", "login", "logout", "disable", "enable", "export", "import", "select", "run", "help", "version"
         ) else None,
         "use_color": use_color,
     }
@@ -313,6 +321,9 @@ def main(argv, options=None):
     if command == "repair":
         return handle_repair(rest, ctx)
 
+    if command == "view":
+        return handle_view(rest, ctx)
+
     if command == "update":
         return handle_update(rest, ctx)
 
@@ -366,6 +377,15 @@ def main(argv, options=None):
     if command == "run":
         return handle_run(rest, ctx)
 
+    if command == "runs":
+        return handle_runs(rest, ctx)
+
+    if command == "run-status":
+        return handle_run_status(rest, ctx)
+
+    if command == "run-report":
+        return handle_run_report(rest, ctx)
+
     if command == "login":
         return handle_login(rest, ctx)
 

package/src/cli_commands.py

@@ -21,6 +21,7 @@ from .context_store import (
 )
 from .errors import CdxError
 from .health import collect_health_report, format_health_report
+from .cli_view import handle_view
 from .notify import (
     format_notify_event,
     format_scheduled_notification,
@@ -32,6 +33,7 @@ from .notify import (
 )
 from .provider_runtime import (
     _ensure_session_authentication,
+    _headless_artifact_paths,
     _list_launch_transcript_paths,
     _normalize_reasoning_effort,
     _probe_provider_auth,
@@ -40,6 +42,7 @@ from .provider_runtime import (
 )
 from .repair import format_repair_report, repair_health
 from .backup_bundle import read_bundle_meta
+from .run_registry import RunRegistry, build_code_review_report
 from .run_usage import extract_run_usage
 from .run_command import read_run_prompt, run_cdx_error_code, run_result_payload
 from .status_view import _format_status_detail, _format_status_rows, format_priority_instruction, recommend_priority_rows
@@ -65,7 +68,10 @@ STATS_USAGE = "Usage: cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--
 LAST_USAGE = "Usage: cdx last [--json]"
 SELECT_USAGE = "Usage: cdx select --provider PROVIDER [--min-reasoning-effort low|medium|high] [--min-power low|medium|high] [--require-ready] [--refresh] --json"
 NEXT_USAGE = "Usage: cdx next [--json] [--refresh]"
-RUN_USAGE = "Usage: cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--reasoning-effort low|medium|high] [--power low|medium|high] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json"
+RUN_USAGE = "Usage: cdx run [session] --cwd PATH (--prompt-file PATH|--prompt TEXT) [--provider PROVIDER] [--model MODEL] [--kind assistant|code-review] [--reasoning-effort low|medium|high] [--power low|medium|high] [--permission review|default|auto|full|workspace-write|read-only|danger-full-access] [--timeout-seconds N] --json"
+RUNS_USAGE = "Usage: cdx runs [--limit N] --json"
+RUN_STATUS_USAGE = "Usage: cdx run-status <run_id> --json"
+RUN_REPORT_USAGE = "Usage: cdx run-report <run_id> --json"
 API_SCHEMA_VERSION = 1
 HANDOFF_TRANSCRIPT_CHARS = 120000
 HANDOFF_NATIVE_TRANSCRIPT_CANDIDATES = 64
@@ -694,6 +700,7 @@ def _parse_run_args(args):
         "--prompt": {"key": "prompt", "type": "str", "default": None},
         "--provider": {"key": "provider", "type": "str", "default": None, "transform": lambda value: _parse_provider_filter(value, RUN_USAGE)},
         "--model": {"key": "model", "type": "str", "default": None},
+        "--kind": {"key": "kind", "type": "str", "default": "assistant"},
         "--reasoning-effort": {"key": "reasoning_effort", "type": "str", "default": None},
         "--power": {"key": "power", "type": "str", "default": None},
         "--permission": {"key": "permission", "type": "str", "default": None, "transform": _normalize_run_permission},
@@ -711,6 +718,8 @@ def _parse_run_args(args):
         raise CdxError(RUN_USAGE)
     if bool(parsed["prompt_file"]) == bool(parsed["prompt"]):
         raise CdxError(RUN_USAGE)
+    if parsed["kind"] not in ("assistant", "code-review"):
+        raise CdxError(RUN_USAGE)
     effort = _normalize_reasoning_effort(
         reasoning_effort=parsed["reasoning_effort"],
         power=parsed["power"],
@@ -722,6 +731,7 @@ def _parse_run_args(args):
         "cwd": parsed["cwd"],
         "prompt_file": parsed["prompt_file"],
         "prompt": parsed["prompt"],
+        "kind": parsed["kind"],
         "model": parsed["model"],
         "permission": parsed["permission"],
         "timeout_seconds": parsed["timeout_seconds"],
@@ -1337,7 +1347,65 @@ def handle_next(rest, ctx):
     return 0
 
 
+def _parse_runs_args(rest):
+    return _parse_flag_args(rest, {
+        "--limit": {"key": "limit", "type": "str", "default": 20, "transform": _parse_positive_int},
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, RUNS_USAGE, max_positionals=0)
+
+
+def _parse_run_id_json_args(rest, usage):
+    parsed = _parse_flag_args(rest, {
+        "--json": {"key": "json", "type": "bool", "default": False},
+    }, usage, positionals_key="ids", max_positionals=1)
+    if not parsed["json"] or len(parsed["ids"]) != 1:
+        raise CdxError(usage)
+    return {"run_id": parsed["ids"][0], "json": True}
+
+
+def _run_registry(ctx):
+    return RunRegistry(ctx["service"]["base_dir"])
+
+
+def handle_runs(rest, ctx):
+    parsed = _parse_runs_args(rest)
+    if not parsed["json"]:
+        raise CdxError(RUNS_USAGE)
+    runs = _run_registry(ctx).list(limit=parsed["limit"])
+    _write_json(ctx, _json_success("runs", "Runs loaded.", runs=runs))
+    return 0
+
+
+def handle_run_status(rest, ctx):
+    parsed = _parse_run_id_json_args(rest, RUN_STATUS_USAGE)
+    run = _run_registry(ctx).get(parsed["run_id"])
+    if not run:
+        _write_json(ctx, _json_failure("run-status", "run_not_found", f"Unknown run: {parsed['run_id']}"))
+        return 1
+    _write_json(ctx, _json_success("run-status", "Run loaded.", run=run))
+    return 0
+
+
+def handle_run_report(rest, ctx):
+    parsed = _parse_run_id_json_args(rest, RUN_REPORT_USAGE)
+    run = _run_registry(ctx).get(parsed["run_id"])
+    if not run:
+        _write_json(ctx, _json_failure("run-report", "run_not_found", f"Unknown run: {parsed['run_id']}"))
+        return 1
+    _write_json(ctx, _json_success("run-report", "Run report loaded.", report={
+        "run": run,
+        "final_payload": run.get("final_payload"),
+        "task_report": run.get("task_report"),
+        "artifacts": run.get("artifacts") or {},
+        "usage": run.get("usage"),
+        "error": run.get("error"),
+    }))
+    return 0
+
+
 def handle_run(rest, ctx):
+    registry = None
+    run_id = None
     try:
         parsed = _parse_run_args(rest)
         session = None
@@ -1396,6 +1464,22 @@ def handle_run(rest, ctx):
             signal_emitter=ctx.get("signal_emitter"),
             trust_local_credentials=False,
         )
+        registry = _run_registry(ctx)
+        artifacts = _headless_artifact_paths(run_session)
+        run_id = artifacts["run_id"]
+        registry.start(
+            run_id,
+            kind=parsed.get("kind"),
+            session=run_session.get("name"),
+            provider=run_session.get("provider"),
+            model=parsed.get("model") or ((run_session.get("launch") or {}).get("model")),
+            cwd=cwd,
+            artifacts={
+                "transcript_path": artifacts.get("transcript_path"),
+                "stdout_path": artifacts.get("stdout_path"),
+                "stderr_path": artifacts.get("stderr_path"),
+            },
+        )
         run_info = _run_headless_provider_command(
             run_session,
             cwd=cwd,
@@ -1403,29 +1487,32 @@ def handle_run(rest, ctx):
             initial_prompt=prompt,
             timeout_seconds=parsed.get("timeout_seconds"),
             spawn=ctx.get("spawn_headless") or ctx.get("spawn"),
+            run_id=run_id,
         )
         usage = extract_run_usage(run_session.get("provider"), run_info.get("stdout_path"))
         run_info = {**run_info, "usage": usage}
         ok = run_info.get("returncode") == 0
         if ok:
+            final_payload = run_result_payload(API_SCHEMA_VERSION, True, parsed, run_session, run_info=run_info)
+            task_report = build_code_review_report(run_id, final_payload) if parsed.get("kind") == "code-review" else None
+            registry.finish(
+                run_id,
+                status="succeeded",
+                final_payload=final_payload,
+                run_info=run_info,
+                task_report=task_report,
+            )
             ctx["service"]["record_launch_history"](session["name"], {
                 "status": "success",
                 "cwd": cwd,
                 "exit_code": 0,
                 **run_info,
             })
-            _write_json(ctx, run_result_payload(API_SCHEMA_VERSION, True, parsed, run_session, run_info=run_info))
+            _write_json(ctx, final_payload)
             return 0
         message = "Provider process timed out." if run_info.get("timed_out") else "Provider process exited with a non-zero status."
         error = CdxError(message, run_info.get("returncode") or 1)
-        ctx["service"]["record_launch_history"](session["name"], {
-            "status": "failed",
-            "cwd": cwd,
-            "error": str(error),
-            "exit_code": error.exit_code,
-            **run_info,
-        })
-        _write_json(ctx, run_result_payload(
+        final_payload = run_result_payload(
             API_SCHEMA_VERSION,
             False,
             parsed,
@@ -1434,11 +1521,27 @@ def handle_run(rest, ctx):
             error=error,
             error_source="provider",
             error_code="provider_timeout" if run_info.get("timed_out") else "provider_failed",
-        ))
+        )
+        registry.finish(
+            run_id,
+            status="timed_out" if run_info.get("timed_out") else "failed",
+            final_payload=final_payload,
+            run_info=run_info,
+            error=final_payload.get("error"),
+            task_report=build_code_review_report(run_id, final_payload) if parsed.get("kind") == "code-review" else None,
+        )
+        ctx["service"]["record_launch_history"](session["name"], {
+            "status": "failed",
+            "cwd": cwd,
+            "error": str(error),
+            "exit_code": error.exit_code,
+            **run_info,
+        })
+        _write_json(ctx, final_payload)
         return error.exit_code or 1
     except CdxError as error:
         run_info = getattr(error, "run_info", None)
-        _write_json(ctx, run_result_payload(
+        final_payload = run_result_payload(
             API_SCHEMA_VERSION,
             False,
             locals().get("parsed", {}) or {},
@@ -1447,7 +1550,16 @@ def handle_run(rest, ctx):
             error=error,
             error_source="cdx",
             error_code=run_cdx_error_code(error),
-        ))
+        )
+        if registry and run_id:
+            registry.finish(
+                run_id,
+                status="failed",
+                final_payload=final_payload,
+                run_info=run_info,
+                error=final_payload.get("error"),
+            )
+        _write_json(ctx, final_payload)
         return error.exit_code
 
 

package/src/cli_view.py

@@ -0,0 +1,104 @@
+import json
+
+from .cli_render import _warn
+from .errors import CdxError
+from .logics_view import (
+    LOGICS_MANAGER_INSTALL_HINT,
+    build_viewer_diagnostics,
+    missing_logics_manager_failure,
+    resolve_logics_manager,
+    run_logics_viewer,
+)
+from .update_check import check_logics_manager_for_update
+
+
+VIEW_USAGE = "Usage: cdx view [--json]"
+API_SCHEMA_VERSION = 1
+
+
+def _json_success(action, message, warnings=None, **extra):
+    payload = {
+        "schema_version": API_SCHEMA_VERSION,
+        "ok": True,
+        "action": action,
+        "message": message,
+        "warnings": warnings or [],
+    }
+    payload.update(extra)
+    return payload
+
+
+def _write_json(ctx, payload):
+    ctx["out"](f"{json.dumps(payload, indent=2)}\n")
+
+
+def _update_notice_warnings(notices):
+    warnings = []
+    for notice in notices or []:
+        if not notice:
+            continue
+        tool = notice.get("tool") or "logics-manager"
+        current = notice.get("current_version")
+        command = notice.get("update_command")
+        message = f"Update available: {tool} {notice['latest_version']}"
+        if current:
+            message = f"{message} (current {current})"
+        if command:
+            message = f"{message}. Run: {command}"
+        warnings.append({
+            "code": f"{tool.replace('-', '_')}_update_available",
+            "message": message,
+            "tool": tool,
+            "latest_version": notice["latest_version"],
+            "current_version": current,
+            "update_command": command,
+            "url": notice.get("url"),
+        })
+    return warnings
+
+
+def _logics_manager_update_notice(ctx, env):
+    checker = ctx["options"].get("checkLogicsManagerForUpdate") or check_logics_manager_for_update
+    return checker(
+        ctx["service"]["base_dir"],
+        env=env,
+        now_fn=ctx["options"].get("now"),
+        runner=ctx["options"].get("runLogicsVersionCheck"),
+    )
+
+
+def handle_view(rest, ctx):
+    json_flag = "--json" in rest
+    unknown = [arg for arg in rest if arg != "--json"]
+    if unknown:
+        raise CdxError(VIEW_USAGE)
+
+    env = ctx.get("env")
+    cwd = ctx.get("cwd")
+    executable = resolve_logics_manager(env=env)
+    update_notice = _logics_manager_update_notice(ctx, env) if executable else None
+    failure = None if executable else missing_logics_manager_failure()
+    diagnostics = build_viewer_diagnostics(executable, cwd, update_notice=update_notice, failure=failure)
+    warnings = _update_notice_warnings([update_notice])
+
+    if json_flag:
+        _write_json(ctx, _json_success("view", "Collected Logics viewer diagnostics", warnings=warnings, viewer=diagnostics))
+        return 0
+
+    if not executable:
+        raise CdxError(f"logics-manager is required for cdx view. {LOGICS_MANAGER_INSTALL_HINT}")
+
+    for warning in warnings:
+        ctx["out"](f"{_warn(warning['message'], ctx['use_color'])}\n")
+
+    try:
+        result = run_logics_viewer(executable, cwd, env=env, runner=ctx.get("spawn_sync"))
+    except FileNotFoundError as error:
+        raise CdxError(f"logics-manager is required for cdx view. {LOGICS_MANAGER_INSTALL_HINT}") from error
+    except KeyboardInterrupt:
+        ctx["out"]("\n")
+        return 130
+    returncode = getattr(result, "returncode", 0)
+    if returncode not in (0, None):
+        raise CdxError("logics-manager view failed.", exit_code=returncode)
+    return 0

package/src/logics_view.py

@@ -0,0 +1,37 @@
+import shutil
+import subprocess
+
+
+LOGICS_MANAGER_INSTALL_HINT = "Install or update it with: npm install -g @grifhinz/logics-manager"
+
+
+def resolve_logics_manager(env=None):
+    env = env or {}
+    return shutil.which("logics-manager", path=env.get("PATH", ""))
+
+
+def build_viewer_diagnostics(executable, cwd, update_notice=None, failure=None):
+    command = [executable or "logics-manager", "view"]
+    return {
+        "available": bool(executable),
+        "executable": executable,
+        "command": command,
+        "cwd": cwd,
+        "update": update_notice,
+        "failure": failure,
+    }
+
+
+def missing_logics_manager_failure():
+    return {
+        "code": "logics_manager_missing",
+        "message": f"logics-manager is required for cdx view. {LOGICS_MANAGER_INSTALL_HINT}",
+    }
+
+
+def run_logics_viewer(executable, cwd, env=None, runner=None):
+    runner = runner or subprocess.run
+    argv = [executable, "view"]
+    if runner is subprocess.run:
+        return subprocess.run(argv, cwd=cwd, env=env)
+    return runner(argv, cwd=cwd, env=env)

package/src/run_registry.py

@@ -0,0 +1,195 @@
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+
+
+def utc_now_iso():
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def registry_path(base_dir):
+    return os.path.join(base_dir, "runs.json")
+
+
+def _read_registry(path):
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except FileNotFoundError:
+        return {"schema_version": 1, "runs": []}
+    if not isinstance(data, dict):
+        return {"schema_version": 1, "runs": []}
+    runs = data.get("runs")
+    if not isinstance(runs, list):
+        runs = []
+    return {"schema_version": int(data.get("schema_version") or 1), "runs": [run for run in runs if isinstance(run, dict)]}
+
+
+def _write_registry(path, data):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    fd, temp_path = tempfile.mkstemp(prefix=".runs-", suffix=".json", dir=os.path.dirname(path))
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.replace(temp_path, path)
+    finally:
+        try:
+            os.unlink(temp_path)
+        except FileNotFoundError:
+            pass
+
+
+def _is_pid_alive(pid):
+    if not pid:
+        return False
+    try:
+        os.kill(int(pid), 0)
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def _refresh_stale_runs(data):
+    now = utc_now_iso()
+    changed = False
+    for run in data["runs"]:
+        if run.get("status") != "running":
+            continue
+        pid = run.get("pid")
+        if pid and _is_pid_alive(pid):
+            continue
+        run["status"] = "stale"
+        run["ended_at"] = now
+        run["error"] = {"code": "stale_process", "message": "Run was marked running but no live provider process was found."}
+        changed = True
+    return changed
+
+
+def _base_record(run_id, *, kind, session, provider, model, cwd, artifacts=None):
+    return {
+        "run_id": run_id,
+        "kind": kind or "assistant",
+        "status": "running",
+        "session": session,
+        "provider": provider,
+        "model": model,
+        "cwd": os.path.abspath(cwd),
+        "pid": None,
+        "started_at": utc_now_iso(),
+        "ended_at": None,
+        "duration_seconds": None,
+        "exit_code": None,
+        "usage": None,
+        "artifacts": dict(artifacts or {}),
+        "error": None,
+        "task_report": None,
+        "final_payload": None,
+    }
+
+
+class RunRegistry:
+    def __init__(self, base_dir):
+        self.path = registry_path(base_dir)
+
+    def start(self, run_id, *, kind, session, provider, model, cwd, artifacts=None):
+        data = _read_registry(self.path)
+        data["runs"] = [run for run in data["runs"] if run.get("run_id") != run_id]
+        record = _base_record(run_id, kind=kind, session=session, provider=provider, model=model, cwd=cwd, artifacts=artifacts)
+        data["runs"].insert(0, record)
+        _write_registry(self.path, data)
+        return record
+
+    def finish(self, run_id, *, status, final_payload=None, run_info=None, error=None, task_report=None):
+        data = _read_registry(self.path)
+        now = utc_now_iso()
+        for run in data["runs"]:
+            if run.get("run_id") != run_id:
+                continue
+            run["status"] = status
+            run["ended_at"] = now
+            if run.get("started_at"):
+                try:
+                    start = datetime.fromisoformat(str(run["started_at"]).replace("Z", "+00:00"))
+                    end = datetime.fromisoformat(now.replace("Z", "+00:00"))
+                    run["duration_seconds"] = (end - start).total_seconds()
+                except ValueError:
+                    run["duration_seconds"] = None
+            if run_info:
+                run["pid"] = run_info.get("pid")
+                run["exit_code"] = run_info.get("returncode")
+                run["artifacts"] = {
+                    **(run.get("artifacts") or {}),
+                    "transcript_path": run_info.get("transcript_path"),
+                    "stdout_path": run_info.get("stdout_path"),
+                    "stderr_path": run_info.get("stderr_path"),
+                }
+            if final_payload:
+                run["usage"] = final_payload.get("usage")
+                run["final_payload"] = final_payload
+            if error:
+                run["error"] = error
+            if task_report:
+                run["task_report"] = task_report
+            _write_registry(self.path, data)
+            return run
+        return None
+
+    def list(self, limit=20):
+        data = _read_registry(self.path)
+        changed = _refresh_stale_runs(data)
+        if changed:
+            _write_registry(self.path, data)
+        return data["runs"][: max(0, int(limit or 20))]
+
+    def get(self, run_id):
+        data = _read_registry(self.path)
+        changed = _refresh_stale_runs(data)
+        if changed:
+            _write_registry(self.path, data)
+        for run in data["runs"]:
+            if run.get("run_id") == run_id:
+                return run
+        return None
+
+
+def read_text_file(path, limit=120000):
+    if not path:
+        return ""
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            return handle.read(limit)
+    except OSError:
+        return ""
+
+
+def build_code_review_report(run_id, final_payload):
+    stdout = read_text_file(final_payload.get("stdout_path") if final_payload else None)
+    parsed = None
+    try:
+        candidate = json.loads(stdout or "{}")
+        if isinstance(candidate, dict):
+            parsed = candidate
+    except json.JSONDecodeError:
+        parsed = None
+    findings = parsed.get("findings") if parsed else []
+    if not isinstance(findings, list):
+        findings = []
+    summary = parsed.get("summary") if parsed else None
+    next_steps = parsed.get("next_steps") if parsed else None
+    if not isinstance(next_steps, list):
+        next_steps = []
+    return {
+        "schema_version": 1,
+        "kind": "code-review",
+        "run_id": run_id,
+        "summary": summary or "Code review completed. Structured findings were not emitted by the provider.",
+        "findings": [finding for finding in findings if isinstance(finding, dict)],
+        "next_steps": [str(step) for step in next_steps],
+        "artifacts": {
+            "transcript_path": final_payload.get("transcript_path") if final_payload else None,
+            "stdout_path": final_payload.get("stdout_path") if final_payload else None,
+            "stderr_path": final_payload.get("stderr_path") if final_payload else None,
+        },
+    }

package/src/session_service.py

@@ -56,6 +56,7 @@ RESERVED_SESSION_NAMES = {
     "status",
     "unset",
     "update",
+    "view",
     "version",
     "--help",
     "-h",