ccx-native 0.1.0 → 0.2.0

package/ccx/claude/usage_control.py

@@ -1,4 +1,4 @@
-"""Promptless Claude Code usage control protocol; no credential or transcript reads."""
+"""Promptless Claude Code usage and model control protocol; no credential reads."""
 
 from __future__ import annotations
 
@@ -22,18 +22,20 @@ _MAX_OUTPUT_BYTES = 2 * 1024 * 1024
 _MAX_LINE_BYTES = 1 * 1024 * 1024
 
 
-def request_usage(timeout: float = 8.0) -> dict:
-    """Return {kind, body?, raw?, error?} from one bounded get_usage exchange.
+def _control_exchange(requests: list[dict], timeout: float, cwd: str | None = None) -> dict:
+    """Send a list of requests through one bounded promptless child.
 
-    The native CLI owns auth. The only input consists of initialize/get_usage
-    control requests; no model prompt, hooks, MCP server or transcript scan.
+    Initialize replies are projected immediately: the full response can also
+    contain personal account data, which must never leave this transport.
     """
     timeout = max(0.1, float(timeout))
-    start = time.monotonic()
-    deadline = start + timeout
-    init_id, usage_id = uuid.uuid4().hex, uuid.uuid4().hex
+    deadline = time.monotonic() + timeout
+    ids = [(uuid.uuid4().hex, request) for request in requests]
+    target_id = ids[-1][0]
+    subtypes = {rid: request["subtype"] for rid, request in ids}
     child = None
-    reply = None
+    replies: dict[str, dict] = {}
+    seen_target = False
     invalid_line = None
     total_bytes = 0
     buffer = b""
@@ -41,17 +43,14 @@ def request_usage(timeout: float = 8.0) -> dict:
     try:
         child = subprocess.Popen(
             [CLAUDE_BIN, *_PROBE_ARGS], stdin=subprocess.PIPE,
-            stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+            stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, cwd=cwd,
         )
-        for rid, request in (
-            (init_id, {"subtype": "initialize"}),
-            (usage_id, {"subtype": "get_usage", "skip_behaviors": True}),
-        ):
+        for rid, request in ids:
             message = {"type": "control_request", "request_id": rid, "request": request}
             child.stdin.write((json.dumps(message, separators=(",", ":")) + "\n").encode())
         child.stdin.flush()
 
-        while time.monotonic() < deadline and reply is None and problem is None:
+        while time.monotonic() < deadline and not seen_target and problem is None:
             readable, _, _ = select.select(
                 [child.stdout], [], [], min(0.2, max(0, deadline - time.monotonic()))
             )
@@ -85,11 +84,31 @@ def request_usage(timeout: float = 8.0) -> dict:
                 response = message.get("response")
                 if not isinstance(response, dict):
                     continue
-                if response.get("request_id") == init_id and response.get("subtype") == "error":
+                rid = response.get("request_id")
+                if rid not in subtypes:
+                    continue
+                subtype = subtypes[rid]
+                if subtype == "initialize" and response.get("subtype") == "error":
                     problem = "Claude usage initialize control request failed"
                     break
-                if response.get("request_id") == usage_id:
-                    reply = message
+                if subtype == "initialize":
+                    body = response.get("response")
+                    # Do not retain the rest of initialize (notably 'account').
+                    safe_body = ({
+                        "models": body.get("models"),
+                        "claude_code_version": body.get("claude_code_version"),
+                    } if isinstance(body, dict) else None)
+                    message = {
+                        "type": "control_response",
+                        "response": {
+                            "request_id": rid,
+                            "subtype": response.get("subtype"),
+                            "response": safe_body,
+                        },
+                    }
+                replies[subtype] = message
+                if rid == target_id:
+                    seen_target = True
                     break
         # Always close stdin after the matching response, or on a bounded failure.
         child.stdin.close()
@@ -100,7 +119,7 @@ def request_usage(timeout: float = 8.0) -> dict:
         except subprocess.TimeoutExpired:
             problem = problem or "Claude usage control timed out"
             exit_code = None
-        if reply is None:
+        if not seen_target:
             if problem is None:
                 problem = "Claude usage control returned no matching response"
             if invalid_line is not None:
@@ -109,28 +128,7 @@ def request_usage(timeout: float = 8.0) -> dict:
             return {"kind": "error", "error": problem}
         if problem is not None or exit_code not in (0, None):
             return {"kind": "error", "error": problem or "Claude usage control exited unsuccessfully"}
-        response = reply["response"]
-        if response.get("subtype") == "error":
-            return {"kind": "error", "error": "Claude usage control response was an error"}
-        if response.get("subtype") != "success":
-            return {"kind": "unparsed", "raw": reply,
-                    "error": "Claude usage control returned an unknown response subtype"}
-        body = response.get("response")
-        if not isinstance(body, dict):
-            return {"kind": "unparsed", "raw": reply,
-                    "error": "Claude usage control returned an unknown JSON body"}
-        if body.get("rate_limits_available") is False and body.get("rate_limits") is None:
-            return {"kind": "unavailable", "error": "Claude plan rate limits unavailable"}
-        if body.get("rate_limits_available") is True and body.get("rate_limits") is None:
-            return {"kind": "held", "error": "Claude plan usage is held by the provider"}
-        rate_limits = body.get("rate_limits")
-        if isinstance(rate_limits, dict) and any(k in rate_limits for k in (
-            "five_hour", "seven_day", "limits", "model_scoped", "extra_usage",
-            "seven_day_opus", "seven_day_sonnet",
-        )):
-            return {"kind": "success", "body": rate_limits}
-        return {"kind": "unparsed", "raw": reply,
-                "error": "Claude usage control returned an unrecognized rate_limits field"}
+        return {"kind": "success", "responses": replies}
     except (OSError, ValueError, BrokenPipeError) as exc:
         return {"kind": "error", "error": f"Claude usage control unavailable: {type(exc).__name__}"}
     finally:
@@ -150,3 +148,57 @@ def request_usage(timeout: float = 8.0) -> dict:
                         child.wait(timeout=1.0)
             if child.stdout is not None:
                 child.stdout.close()
+
+
+def request_usage(timeout: float = 8.0) -> dict:
+    """Return {kind, body?, raw?, error?} from one bounded get_usage exchange.
+
+    The native CLI owns auth. The only input consists of initialize/get_usage
+    control requests; no model prompt, hooks, MCP server or transcript scan.
+    """
+    result = _control_exchange([
+        {"subtype": "initialize"},
+        {"subtype": "get_usage", "skip_behaviors": True},
+    ], timeout)
+    if result["kind"] != "success":
+        return result
+    reply = result["responses"]["get_usage"]
+    response = reply["response"]
+    if response.get("subtype") == "error":
+        return {"kind": "error", "error": "Claude usage control response was an error"}
+    if response.get("subtype") != "success":
+        return {"kind": "unparsed", "raw": reply,
+                "error": "Claude usage control returned an unknown response subtype"}
+    body = response.get("response")
+    if not isinstance(body, dict):
+        return {"kind": "unparsed", "raw": reply,
+                "error": "Claude usage control returned an unknown JSON body"}
+    if body.get("rate_limits_available") is False and body.get("rate_limits") is None:
+        return {"kind": "unavailable", "error": "Claude plan rate limits unavailable"}
+    if body.get("rate_limits_available") is True and body.get("rate_limits") is None:
+        return {"kind": "held", "error": "Claude plan usage is held by the provider"}
+    rate_limits = body.get("rate_limits")
+    if isinstance(rate_limits, dict) and any(k in rate_limits for k in (
+        "five_hour", "seven_day", "limits", "model_scoped", "extra_usage",
+        "seven_day_opus", "seven_day_sonnet",
+    )):
+        return {"kind": "success", "body": rate_limits}
+    return {"kind": "unparsed", "raw": reply,
+            "error": "Claude usage control returned an unrecognized rate_limits field"}
+
+
+def request_models(timeout: float = 8.0) -> dict:
+    """Return only Claude's model entries and version from initialize."""
+    # From home, so one project's settings can't shape the shared catalog.
+    result = _control_exchange([{"subtype": "initialize"}], timeout,
+                               cwd=os.path.expanduser("~"))
+    if result["kind"] != "success":
+        # Do not return raw stdout; initialize may include private account data.
+        return {"kind": "error", "error": result.get("error") or "Claude model probe failed"}
+    response = result["responses"]["initialize"]["response"]
+    if response.get("subtype") != "success":
+        return {"kind": "error", "error": "Claude model initialize failed"}
+    body = response.get("response")
+    if not isinstance(body, dict) or not isinstance(body.get("models"), list):
+        return {"kind": "error", "error": "Claude model initialize returned no models"}
+    return {"kind": "success", "body": body}

package/ccx/cli/commands/control.py

@@ -51,7 +51,7 @@ def cmd_stop(args):
         "cancelled": result["confirmed"] and result["outcome"] == "interrupted",
     }
     print(json.dumps(value) if getattr(args, "json", False)
-          else (f"{result['worker']['worker']}: stop confirmed; turn outcome unknown until Claude settles"
+          else (f"{result['worker']['worker']}: stop confirmed; the turn is no longer running, outcome unknown"
                 if result["confirmed"] and result["outcome"] == "unknown"
                 else f"{result['worker']['worker']}: stop {result['status']}; turn outcome {result['outcome']}"))
 

package/ccx/cli/commands/models.py

@@ -0,0 +1,53 @@
+"""Read-only model catalog CLI."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from ccx.constants import EXIT_UNAVAILABLE
+from ccx.models import read_models
+from ccx.types import ModelCatalog
+
+
+def _table(catalog: ModelCatalog) -> None:
+    label = catalog.engine.capitalize()
+    if catalog.engine_version:
+        label += f" {catalog.engine_version}"
+    print(f"{label} models ({catalog.source}):")
+    if catalog.note:
+        print(f"  {catalog.note}")
+    models = sorted(catalog.models, key=lambda entry: (not entry.default, not entry.alias))
+    if not models:
+        print("  No models available")
+        return
+    rows = [
+        (entry.id, entry.display_name,
+         entry.resolved if entry.resolved and entry.resolved != entry.id else "",
+         ", ".join(entry.efforts))
+        for entry in models
+    ]
+    headers = ("--model", "Display name", "Resolved", "Efforts")
+    widths = [max(len(row[i]) for row in [headers, *rows]) for i in range(3)]
+    for row in [headers, *rows]:
+        print("  " + "  ".join(
+            [*(row[i].ljust(widths[i]) for i in range(3)), row[3]]
+        ).rstrip())
+
+
+def cmd_models(args) -> None:
+    """Print one or both available model catalogs."""
+    catalogs = read_models(engine=args.engine, refresh=args.refresh)
+    if args.json:
+        print(json.dumps([catalog.as_dict() for catalog in catalogs], indent=2))
+    else:
+        for i, catalog in enumerate(catalogs):
+            if i:
+                print()
+            _table(catalog)
+    if args.refresh:
+        failed = [catalog for catalog in catalogs if catalog.source in ("stale", "builtin")]
+        if failed:
+            for catalog in failed:
+                sys.stderr.write(f"ccx models: {catalog.engine} refresh failed: {catalog.note}\n")
+            raise SystemExit(EXIT_UNAVAILABLE)

package/ccx/cli/commands/read.py

@@ -293,6 +293,11 @@ def cmd_logs(args):
             sys.stdout.write(client._claude.logs(owner.worker, jsonl=True))
             return
         if args.format == "rendered":
+            sys.stderr.write(
+                "[ccx] logs --format rendered is deprecated and will be removed; "
+                "read a conversation as text with `ccx history TARGET --view trace`, "
+                "or use the default JSON in programs\n"
+            )
             doc = client._claude.logs(owner.worker, tail=args.tail)
             json.dump(doc, sys.stdout, indent=2)
             sys.stdout.write("\n")
@@ -317,6 +322,57 @@ def cmd_logs(args):
         raise SystemExit(error.exit_code) from error
 
 
+def cmd_history(args):
+    """Print the named workers' past conversations as text, or search them.
+
+    Read-only: each worker's normalized document is read from its original
+    source (Codex from its local history database when it can be), projected
+    by ``ccx.ops.history`` and printed. A worker that can't be read is reported
+    on stderr while the others still print.
+    """
+    from ccx import constants
+    from ccx.ops import history as hist
+    from ccx.store.identity import IdentityError
+    from ccx.store.root import GenerationError, require_ccx_active
+    from ccx.workers import WorkerClient
+
+    try:
+        opts = hist.options(
+            view=args.view, turns=args.turns, grep=args.grep, cmd=args.command_regex,
+            errors=args.errors, role=args.role, since=args.since, until=args.until,
+            context=args.context, limit=args.limit, max_chars=args.max_chars,
+            full=args.full)
+    except InvalidRequest as error:
+        print(f"ccx history: {error}", file=sys.stderr)
+        raise SystemExit(error.exit_code) from None
+    store = require_ccx_active(constants.CCX_ROOT)
+    client = WorkerClient()
+    zone = hist.zone_name()
+    many = len(args.targets) > 1
+    hint = None
+    failed = 0
+    for target in args.targets:
+        try:
+            owner = store.resolve(target)
+            name = store.record(owner.worker).get("name")
+            doc = client.conversation(
+                owner.worker,
+                max_tool_result_bytes=None if opts.needs_full_results() else 4096,
+                _codex_history_db=True)
+            store.revalidate()
+        except (CcxError, GenerationError, IdentityError, OSError) as exc:
+            failed += 1
+            print(f"ccx history {target}: cannot read the conversation: {exc}", file=sys.stderr)
+            continue
+        hint = hist.render_history(hist.project(doc, name=name), opts, sys.stdout,
+                                   many=many, zone=zone) or hint
+        sys.stdout.flush()
+    if hint is not None:
+        print("\n" + hist.hint_line(hint))
+    if failed:
+        raise SystemExit(EXIT_UNAVAILABLE)
+
+
 class _ReportFailure(Exception):
     """One target that cannot be reported: message plus the CLI exit code."""
 
@@ -644,6 +700,26 @@ def _background_summary_line(summary: dict | None) -> str | None:
             f"subagent={kinds.get('subagent', 0)}")
 
 
+def _peek_window_enough(doc, args) -> bool:
+    """A recent window holds what this peek shows, or there is no older history.
+
+    Tools are counted on their own: the activity view also shows errors, but
+    the tool list and --tools-only show only tools, and both use --tail.
+    """
+    if not isinstance(doc, dict) or "peekHistoryWindow" not in doc:
+        return True
+    kinds = [item.get("kind") for turn in doc.get("turns") or []
+             for item in [*turn.get("input", []), *turn.get("output", [])]
+             if isinstance(item, dict)]
+    texts = "user-text" in kinds and "assistant-text" in kinds
+    tools = sum(kind in {"tool-call", "tool-result"} for kind in kinds) >= args.tail
+    if args.text_only:
+        return texts
+    if args.tools_only:
+        return tools
+    return texts and tools
+
+
 def _peek_conversation(args, store):
     """Project one original schema-5 snapshot for the CLI, without native writes."""
     from ccx.store.root import GenerationError
@@ -653,14 +729,22 @@ def _peek_conversation(args, store):
     try:
         owner = store.resolve(args.target)
         options = {}
+        # Peek shows only recent items, so it reads a recent tail. An explicit
+        # --since-turn keeps the complete history path for original turn numbers.
         if owner.engine == "codex" and args.since_turn is None:
-            # Only peek needs a recent tail. An explicit --since-turn keeps
-            # the complete history path for unambiguous original ordinals.
             options["_recent_codex_turns"] = min(64, max(12, args.tail * 2 + 4))
-        doc = WorkerClient().conversation(
-            owner.worker, max_tool_result_bytes=None if args.full else 4096,
-            **options,
-        )
+        elif args.since_turn is None:
+            # Claude prompts can each span many MB of tool work, so start from
+            # the last two and widen only until peek has everything it shows.
+            options["_recent_claude_turns"] = 2
+        while True:
+            doc = WorkerClient().conversation(
+                owner.worker, max_tool_result_bytes=None if args.full else 4096,
+                **options,
+            )
+            if "_recent_claude_turns" not in options or _peek_window_enough(doc, args):
+                break
+            options["_recent_claude_turns"] *= 4
         if (not isinstance(doc, dict) or doc.get("schemaVersion") != 5
                 or not isinstance(doc.get("worker"), dict)
                 or doc["worker"].get("handle") != owner.worker

package/ccx/cli/main.py

@@ -23,6 +23,7 @@ _USER_WORKER_FIELDS = {
     "vars": ("target",),
     "events": ("target",),
     "logs": ("target",),
+    "history": ("targets",),
     "wait": ("target",),
     "answer": ("target",),
     "approve": ("target",),
@@ -195,8 +196,8 @@ _AUTO_INIT_COMMANDS = frozenset({
     "new", "import", "fork", "resume", "send", "steer", "reconcile",
     "wait", "notify", "answer", "approve", "reject", "respond",
     "set", "compact", "stop", "kill", "attach", "shutdown", "untrust",
-    "vars", "list", "logs", "report", "context", "peek", "events",
-    "usage", "controller",
+    "vars", "list", "logs", "history", "report", "context", "peek", "events",
+    "usage", "models", "controller",
 })
 
 

package/ccx/cli/parser.py

@@ -8,9 +8,10 @@ import textwrap
 from ccx.cli.commands.control import cmd_attach, cmd_kill, cmd_shutdown, cmd_stop, cmd_untrust
 from ccx.cli.commands.create import cmd_fork, cmd_import, cmd_new, cmd_resume
 from ccx.cli.commands.read import (
-    cmd_context, cmd_events, cmd_list, cmd_logs, cmd_peek,
+    cmd_context, cmd_events, cmd_history, cmd_list, cmd_logs, cmd_peek,
     cmd_report, cmd_usage,
 )
+from ccx.cli.commands.models import cmd_models
 from ccx.cli.commands.turns import (
     cmd_answer, cmd_approve, cmd_compact, cmd_notify, cmd_reconcile, cmd_reject,
     cmd_respond, cmd_send, cmd_set, cmd_steer, cmd_vars, cmd_wait,
@@ -140,13 +141,71 @@ From Codex, run ccx outside the sandbox (or with full access): it starts
 processes and writes outside the workspace. Codex must be on PATH or
 CCX_CODEX_BIN must point to its executable."""
 
+HISTORY_DESCRIPTION = """\
+Read past conversations of the workers you name, or search them. Nothing is
+sent; it works on idle, busy and stopped workers. Reasoning is never shown.
+
+Each message is labelled: U a user message, U+ a user message sent while the
+turn ran (a steer), N[kind] a notification or event (bg, monitor, agent, cron,
+system, ccx, ...), / a slash command, ! an interrupt, A assistant text, A* the
+turn's final answer, A… the latest text of a turn still running, T a tool call.
+
+Every message has an address #TURN.N, the same numbers as `ccx logs` and
+`ccx peek --since-turn`; --turns TURN.N prints that message whole. A compaction
+is one line (══ #TURN.N compaction); its address prints the summary when one is
+stored (Codex encrypts its summaries).
+
+What you get:
+  no options             outline of the last 30 turns (10 per worker if several)
+  --since/--until        outline of the turns in that time range
+  --turns SPEC           those turns as chat (--turns 1- for all)
+  --role ROLES           recent turns as chat, showing only those roles
+  --grep/--cmd/--errors  one line per matching message, newest 20 per worker;
+                         add -C N (or --view) to read the matching turns instead
+
+Views (--view):
+  outline  one block per turn: prompt, start of the final answer, tool summary
+  chat     prompts and final answers, each cut to --max-chars
+  trace    prompts, all assistant text, and one line per tool call
+  map      the whole history in segments split at compactions and idle gaps
+           over 6 hours, one title each"""
+
+HISTORY_EPILOG = """\
+Roles (--role picks what is searched, and what chat and trace show; search
+default: user,assistant,notify,tool):
+  user       user messages, steers, slash commands, interrupts
+  notify     notifications and events
+  assistant  all assistant text; final: final answers only (A*, A…)
+  tool       tool calls, shown as commands; output: tool results
+  compact    compaction summaries (search only)
+Tool output is searched and shown only when output is in --role.
+
+--grep is a regular expression; all lowercase means case-insensitive. --cmd
+matches whole command names, in any case: `cd x && timeout 30 .venv/bin/python
+-m pytest | tail` runs cd, python, pytest and tail. --since/--until take
+2026-11-02, '11-02 14:00', 14:00 (today) or 90m/6h/2d (ago), in local time; a
+bare --until date includes that day.
+
+Examples:
+  ccx history W                                  recent turns
+  ccx history W --view map                       a long history at a glance
+  ccx history A B C --grep 'apple silicon' --role user
+  ccx history W --turns 184.0                    one message, whole
+  ccx history W --turns 180-186                  the exchange around it
+  ccx history A B C --turns -1                   each worker's last turn
+  ccx history W --grep 'deploy|rollback' -C 1    the turns about a topic
+  ccx history W --role notify                    recent notifications
+  ccx history W --cmd pytest --role tool,output  test runs and how each ended
+  ccx history A B --since '11-07 21:00' --until '11-07 22:00'"""
+
+
 COMMAND_GROUPS = (
     ("Create", ("new", "fork", "resume", "import")),
     ("Turns", ("send", "steer", "stop", "wait", "notify", "reconcile")),
     ("Input requests", ("answer", "approve", "reject", "respond")),
-    ("Inspect", ("list", "peek", "report", "logs", "context", "events", "vars")),
+    ("Inspect", ("list", "peek", "report", "history", "logs", "context", "events", "vars")),
     ("Manage", ("attach", "compact", "set", "kill", "shutdown")),
-    ("Account", ("usage",)),
+    ("Account", ("usage", "models")),
     ("Setup and automation", ("init", "skills", "untrust", "controller", "rpc")),
 )
 
@@ -872,7 +931,8 @@ def _add_inventory_parsers(sub) -> None:
         description=(
             "Needs a terminal. A stopped worker is revived; CCX commands remain "
             "available while attached. For both engines, Ctrl-Z detaches and "
-            "leaves the worker running. The CCX status "
+            "leaves the worker running. Several terminals can attach at once; "
+            "a Claude worker then uses the smallest one's size. The CCX status "
             "bar is shown unless --no-status. Codex runs its real native UI; "
             "/quit also exits. Codex may first show its own startup prompts. "
             "Model/permission changes made there do not "
@@ -923,10 +983,11 @@ def _add_inventory_parsers(sub) -> None:
         ),
     )
     pg.add_argument("target", help=_WORKER_QUERY_HELP)
-    pg.add_argument("--tail", type=int, default=None, help="Only the last N turns. Only those turns are read, so Claude numbers them from 1 and Codex leaves them unnumbered.")
+    pg.add_argument("--tail", type=int, default=None, help="Only the last N turns. Only those turns are read, so they are unnumbered unless they are the whole conversation.")
     pg.add_argument("--format", choices=("conversation", "rendered"), default="conversation",
-                    help="conversation (default) or rendered (Claude only: per-turn "
-                         "transcript with tool calls paired to their results).")
+                    help="conversation (default) or rendered (deprecated; Claude only: "
+                         "per-turn transcript with tool calls paired to their results). "
+                         "To read a conversation as text, use `ccx history`.")
     pg.add_argument("--max-tool-result-bytes", dest="max_tool_result_bytes", type=int,
                     default=4096,
                     help="Cut each tool result to N bytes (default 4096).")
@@ -936,6 +997,42 @@ def _add_inventory_parsers(sub) -> None:
                     help="Claude only: print Claude's raw JSONL transcript.")
     pg.set_defaults(func=cmd_logs)
 
+    ph = sub.add_parser(
+        "history",
+        help="Read or search workers' past conversations as text.",
+        description=HISTORY_DESCRIPTION,
+        epilog=HISTORY_EPILOG,
+        formatter_class=_HelpFormatter,
+    )
+    ph.add_argument("targets", nargs="+", metavar="target",
+                    help="One or more workers (find them with `ccx list`).")
+    ph.add_argument("--turns", metavar="SPEC",
+                    help="12, 10-14, 120-, -5 (the last five) or 184.0 (one message); "
+                         "comma-separated.")
+    ph.add_argument("--grep", metavar="REGEX",
+                    help="Messages matching REGEX in the searched roles.")
+    ph.add_argument("--cmd", dest="command_regex", metavar="REGEX",
+                    help="Tool calls running a command whose name matches REGEX.")
+    ph.add_argument("--errors", action="store_true", help="Failed tool calls only.")
+    ph.add_argument("--role", metavar="ROLES",
+                    help="Comma-separated roles to search and show; see below.")
+    ph.add_argument("--since", metavar="TIME", help="From this time; see below.")
+    ph.add_argument("--until", metavar="TIME",
+                    help="Before this time; a date includes that whole day.")
+    ph.add_argument("-C", "--context", type=int, metavar="N",
+                    help="Read the matching turns instead of hit lines, with N turns around each.")
+    ph.add_argument("--view", choices=("outline", "chat", "trace", "map"),
+                    help="How to show turns; see above.")
+    ph.add_argument("--limit", type=int, default=20, metavar="N",
+                    help="Hit lines per worker, newest (default 20).")
+    ph.add_argument("--max-chars", type=int, metavar="N",
+                    help="Cut each message to N characters (default 3000; "
+                         "one addressed message prints whole).")
+    ph.add_argument("--full", action="store_true",
+                    help="Don't cut messages, commands or tool output "
+                         "(hit lines stay short).")
+    ph.set_defaults(func=cmd_history)
+
     prep = sub.add_parser(
         "report",
         help="Print the last reply of one or more workers.",
@@ -1133,6 +1230,24 @@ def _add_control_parsers(sub) -> None:
 
 def _add_observability_parsers(sub) -> None:
     """Quota and session observation: usage, peek, events."""
+    pm = sub.add_parser(
+        "models",
+        help="List the models Claude and Codex offer.",
+        description=(
+            "Show the models each engine offers: the id to pass to --model, the "
+            "display name, the model a Claude alias points to now, and the efforts "
+            "it supports. Lists are kept for 24 hours; Claude's is fetched again "
+            "after a Claude Code update. If a list can't be fetched, the last one "
+            "is shown, marked stale."
+        ),
+    )
+    pm.add_argument("--engine", choices=("claude", "codex"),
+                    help="Only this engine (default: both).")
+    pm.add_argument("--json", action="store_true", help="Print the lists as JSON.")
+    pm.add_argument("--refresh", action="store_true",
+                    help="Fetch the lists now; exit 3 if one can't be fetched.")
+    pm.set_defaults(func=cmd_models)
+
     pu = sub.add_parser(
         "usage",
         help="Show your Claude or Codex account usage.",

package/ccx/client.py

@@ -82,15 +82,14 @@ from ccx.ops.semantics import (
     question_answer_map,
     question_answer_message,
 )
-from ccx.claude.transcript import (
-    render_transcript_json,
-)
+from ccx.claude.transcript import render_transcript
 from .types import (
     ClaudeContext,
     ClaudeTask,
     CompactOperationResult,
     Event,
     FiveHourReset,
+    ModelCatalog,
     Report,
     PendingInput,
     SemanticDeliveryResult,
@@ -1659,7 +1658,7 @@ class CcxClient:
                     with source[0].open_reader() as stream:
                         result = stream.read().decode("utf-8", "replace")
             else:
-                result = render_transcript_json(owner.worker, store=self._uuid_store)
+                result = render_transcript(owner.worker, store=self._uuid_store)
                 if result is None:
                     raise SessionNotFound(
                         f"transcript not found for {owner.worker}", short=owner.short,
@@ -1849,6 +1848,11 @@ class CcxClient:
                 f"subscribe: original source unavailable: {exc}"
             ) from exc
 
+    def models(self, *, refresh: bool = False) -> ModelCatalog:
+        """The models Claude Code offers, as ``ccx models --engine claude``."""
+        from ccx.models import read_models
+        return read_models(engine="claude", refresh=refresh)[0]
+
     def usage(self, *, cached: bool = False) -> Usage:
         """Live quota utilization (the signal usage caps enforce). With
         ``cached=True`` serve a recent cached value instead of forcing a fresh

package/ccx/codex/client.py

@@ -44,6 +44,7 @@ from ccx.constants import (
     COMPACT_WAIT_DEFAULT_S,
     DEFAULT_IDLE_TIMEOUT_S,
 )
+from ccx.types import ModelCatalog
 from ccx.errors import (
     DeliveryRejected,
     InvalidRequest,
@@ -713,6 +714,11 @@ class CodexClient:
         _worker, rec = self._owned_codex(target)
         return CodexContext.from_record(rec)
 
+    def models(self, *, refresh: bool = False) -> ModelCatalog:
+        """The models Codex offers, as ``ccx models --engine codex``."""
+        from ccx.models import read_models
+        return read_models(engine="codex", refresh=refresh)[0]
+
     def usage(
         self,
         *,

package/ccx/codex/daemon/daemon.py

@@ -780,7 +780,9 @@ class CodexDaemon:
         op = message.get("op")
         if op == "daemon-status":
             with self.lock:
-                workers = {
+                # A presence probe needs no worker states, and each takes
+                # that worker's lock, which a slow disk write can hold.
+                workers = None if message.get("workers") is False else {
                     short: worker.state()
                     for short, worker in self.workers.items()
                 }