cdx-manager 0.26.1 → 0.26.2

package/README.md

@@ -4,7 +4,7 @@
 
 <br clear="left"/>
 
-[![License](https://img.shields.io/badge/license-MIT-4C8BF5)](LICENSE) ![Version](https://img.shields.io/badge/version-v0.26.1-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.26.2-4C8BF5) ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)
 
 **The right AI coding account, when you need it.** CDX Manager keeps your Codex and Claude accounts in separate profiles, shows which ones have quota, and helps you pick the next usable session from your terminal.
 
@@ -246,41 +246,94 @@ for a fresh credential, and that cleanup works after disconnect and SIGTERM.
 
 ### Read an interactive conversation
 
-`cdx conversation <name> [--conversation ID] [--cursor CURSOR] [--limit N] --json`
+`cdx conversation <name> [--conversation ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json`
 returns a read-only JSON page for the profile's current conversation. An explicit
 conversation ID uses an exact transcript lookup and never falls back. When the
 profile's recorded ID has no transcript on this host (for example after a remote
-run on another host), or there is no recorded ID, the command uses the existing
-latest local transcript resolver under the profile's auth home. This fallback is
-best effort and does not rewrite the recorded ID. JSON `resolution_method` is
+run on another host), or there is no recorded ID, the command selects the latest
+local transcript for `--cwd PATH`, defaulting to the process working directory.
+Claude-compatible providers use `.claude/projects/<path-slug>`; Codex requires
+a matching `cwd` in the rollout's initial `session_meta` record. Missing or
+unreadable Codex metadata is excluded. `--since ISO` further restricts fallback
+to transcripts modified at or after the session start timestamp (for example
+`--since 2026-11-04T00:39:00Z`). Callers should pass a timestamp with a timezone.
+Without a candidate, JSON reports `status: "unavailable"` and
+`reason: "no_conversation_yet"`, including while a new session awaits folder trust.
+This fallback is best effort and does not rewrite the recorded ID. Exact ID
+lookups remain independent of these fallback constraints. JSON `resolution_method` is
 `conversation_id` for an exact match, `recency` for a local fallback, or `null`
-when no transcript is resolved.
+when no transcript is resolved. JSON `resolution_scope` records the canonical
+absolute `cwd` and supplied `since` timestamp for fallback attempts, including
+unavailable results; `since` is `null` when omitted. Exact lookups and unsupported
+providers report a `null` scope. A missing explicit ID still reports
+`transcript_not_found`.
 
 The normal cdx JSON envelope includes `status`, `reason`, `provider`, `session`,
 `entries`, `next_cursor`, and `has_more`. Each entry has exactly `role`
 (`user`, `assistant`, or `tool`), `text`, `tool_name`, `tool_summary`, `at`, and
-`id`. Missing values are `null`; tool text is empty. Entries follow file and
+`id`. Missing values are `null`; normal tool text is empty. Entries follow file and
 content-block order, with stable IDs for the same file position. Timestamps are
 provider timestamps when valid. Tool calls/results have a name and a short
 summary; arguments, results, attachments, and reasoning blocks are omitted.
-Result names are recovered from up to 100 recent calls, otherwise `tool`.
+Result names are recovered from recent calls, otherwise `tool`. The cache holds
+up to 100 names and is trimmed oldest first to 2 KiB of compact JSON when saved
+in a cursor. Existing version-1 cursors with larger caches remain readable.
 Common credential patterns and secret assignments in text are redacted without
 opening credential stores. Review conversation text before sharing: arbitrary
 unlabelled sensitive prose cannot be identified automatically.
 
 Pass `next_cursor` unchanged as `--cursor` to fetch the next page or poll for new
 entries. `--limit` bounds entries (default 100, range 1–1000). Reading seeks to
-the saved byte position rather than replaying history, and scans at most 8 MiB
-per call. A page may be empty while still returning a usable cursor. Poll on a
+the saved byte position rather than replaying history, and stops scanning after
+8 MiB per call, finishing the current record when it crosses that budget.
+A page may be empty while still returning a usable cursor. Poll on a
 timer: `has_more` means unread bytes, which can include an incomplete final line
 that will only become readable after the provider appends its newline.
 
+Start near the present with `cdx conversation work --tail 100 --json`.
+`--tail N` returns the last N normalized entries (1–1000) in chronological order.
+It reads backwards in 64 KiB blocks, retaining at most a 1 MiB record prefix;
+it does not replay the transcript from the beginning. Records that produce
+multiple entries can split across pages. The same redaction, tool summaries,
+oversized-record placeholders and file-position IDs apply. Recent tool names are
+recovered from a 64 KiB lookback (extended to 8 MiB when resolving a result in the selected window), with the usual `tool`
+fallback. Finding N entries can require scanning more bytes when records
+are oversized or contain no visible entries. Incomplete trailing records are
+excluded until their newline arrives.
+
+Tail and backward pages add `before_cursor`: pass it unchanged as
+`--before CURSOR --limit N` to load the preceding entries, also in chronological
+order. `before_cursor: null` means the beginning has been reached. You can also
+use `--before CURSOR --tail N`; `--tail` sets the count when both count options
+are present. `next_cursor` still works with `--cursor` to follow entries after
+the returned page, including messages appended after an initial tail read.
+`has_more` continues to describe unread bytes **after** that page; use
+`before_cursor` to decide whether older pages remain. `--cursor` cannot be
+combined with `--tail` or `--before`. Without either new option, the existing
+forward page contract is unchanged.
+
+Backward cursors retain the original file size, modification time and boundary
+anchors. Replacement, truncation or a detected in-place rewrite returns
+`reset_required`; appending new messages preserves backward pagination. As with
+forward cursors, transcripts must be append-only: bounded boundary checks cannot
+detect every arbitrary edit elsewhere in a file that also grows.
+
 Codex response items and Claude-compatible JSONL transcripts (Claude and
-Antigravity) are supported through the existing transcript resolver. Missing or
+Antigravity) are supported through the existing transcript resolver. Only
+`response_item` records from Codex and `user`/`assistant` records with `message`
+from Claude-compatible transcripts are read, including their tool blocks. All
+other record types are ignored, even when they repeat conversation content. Missing or
 unreadable files return `status: "unavailable"` with a reason. Ollama's terminal
 capture does not reliably identify message roles and returns
 `status: "unsupported"`, including when no capture exists. A transcript record
-larger than 1 MiB returns `unavailable`. A replaced/truncated file or invalid
+larger than 1 MiB is skipped with bounded reads through its newline. For an allowed conversation record with readable type and message metadata, it produces
+one entry containing `[élément trop volumineux ignoré]`, with a stable ID and a
+role recovered from structural metadata in the readable prefix, or `tool` when
+unknown. Records whose type or message cannot be established from the bounded
+prefix are ignored. Its body, images and attachments are never returned. The cursor advances
+past that record so later messages remain accessible. An oversized final record
+without a newline produces no entry yet and is retried on the next call.
+A replaced/truncated file or invalid
 cursor returns `reset_required`; discard the cursor and reload the conversation.
 Cursors are opaque, versioned, and bound to a provider and file. Treat transcripts
 as append-only; reset the client if a provider rewrites earlier history.

package/VERSION

@@ -1 +1 @@
-0.26.1
+0.26.2

package/changelogs/CHANGELOGS_0_26_2.md

@@ -0,0 +1,20 @@
+# CDX Manager 0.26.2
+
+## Fixes
+
+- Scope conversation recency fallback to `--cwd PATH` (the process working
+  directory by default), using Claude project folders or Codex `session_meta.cwd`.
+  Support `--since ISO` to exclude transcripts modified before session start.
+  Return `unavailable` / `no_conversation_yet` when no candidate matches instead
+  of showing another project. Add `resolution_scope` without changing
+  `resolution_method` or exact conversation ID lookup semantics.
+
+- Read only Claude-compatible `user` and `assistant` records with `message`,
+  preserving their tool calls and results. Ignore all other record types,
+  including Claude Code request blobs that repeat user prompts without dates.
+- Apply the same allowlist to oversized records; retain only `response_item`
+  records for Codex so event copies cannot appear as conversation entries.
+  Ignore oversized records when the bounded prefix cannot establish their type
+  and message metadata.
+- Cover the reported Claude Code 2.1.317 request-blob shape, dated messages,
+  tools, cursor pagination and ignored metadata for all structured providers.

package/changelogs/CHANGELOGS_UNRELEASED.md

@@ -1,5 +1,17 @@
 # Unreleased
 
+## Conversation tail pagination (planned for 0.26.2)
+
+- Add `cdx conversation --tail N` (1–1000), chronological backward pages via `before_cursor` and `--before`, and a compatible `next_cursor` for live polling. Read JSONL backwards in bounded 64 KiB blocks, preserve normalization, redaction, stable IDs and oversized-record skipping, and reject stale backward cursors.
+- Measure tail I/O on 6,000-entry Codex and Claude-compatible transcripts and cover backward traversal, content-block splits, append polling and incomplete/oversized records.
+
+## Read past oversized conversation records
+
+- Skip JSONL records larger than 1 MiB using bounded reads instead of returning `record_too_large`. Emit a short placeholder with a stable ID and the role from readable structural metadata, falling back to `tool`, then advance the cursor so subsequent messages remain accessible. Never return image or attachment bodies.
+- Retry oversized trailing records without a newline on the next poll. The 8 MiB page scan budget finishes the current record before returning.
+- Bound the cursor's recent tool-name cache to 2 KiB of compact JSON, evicting oldest entries while keeping version-1 cursors with up to 100 names readable.
+- Cover 20 MiB records in the middle, cursors immediately before them, incomplete oversized tails, bounded reads, stable IDs, conservative role detection and legacy cursor compatibility.
+
 ## Preserve interactive conversations across headless runs
 
 - Keep fresh Claude run identities in run records and history without changing the profile's interactive conversation. Skip interactive Codex identity observation when recording headless run history, including detached, remote and continued runs.

package/checksums/release-archives.json

@@ -804,6 +804,17 @@
         "x86_64-pc-windows-msvc": "24ba2a8ed13de1bdc0401661a51c105c2c7ed186f3b17a871cd721ac8adf4916",
         "x86_64-unknown-linux-musl": "200c8ab9465625784a32ae326d923bca97b5f9616809c43cb5dc73e0e5d9ca17"
       }
+    },
+    "v0.26.1": {
+      "github_tarball_sha256": "b1ccc629c8697354dc5c8e1b892a94a9668061ef6667711af2bd62816e3bdff7",
+      "github_zip_sha256": "5ba11ac492690967f7c076b32c6e3e13dd183b7c097c706ff16e3df61364bee9",
+      "tray_assets": {
+        "aarch64-apple-darwin": "d570430988a271c87403e176f5689115ca6c214990a13831c7d1ed69b7943353",
+        "aarch64-unknown-linux-musl": "1b8acda432cff9d58fc3aaaac5d03f684ae4887f4976821ccecc383c79d6bc98",
+        "x86_64-apple-darwin": "b51111f3c6f747671f9416f8f7ed544a5a98318121694c33440b6b54782c1080",
+        "x86_64-pc-windows-msvc": "07cf6f66d58320494833107cf369b66cdf171649c8128d6463028a9aa7058494",
+        "x86_64-unknown-linux-musl": "e18869d50747b1eb7924005554e11154f04a27363b8b3148f7ae0a1042d6ca7a"
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdx-manager",
-  "version": "0.26.1",
+  "version": "0.26.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.26.1"
+version = "0.26.2"
 description = "Terminal session manager for Codex and Claude accounts."
 readme = "README.md"
 requires-python = ">=3.9.2"

package/src/cli.py

@@ -272,7 +272,7 @@ def _print_help(use_color=False):
         f"  {_style('cdx stats [name] [--since 7d|today|DATE] [--from DATE] [--to DATE] [--by session|project|model] [--json]', '36', use_color)}",
         f"  {_style('cdx last [--json]', '36', use_color)}",
         f"  {_style('cdx resume <name> [--project PATH] [--conversation <id>] [--json]', '36', use_color)}",
-        f"  {_style('cdx conversation <name> [--conversation ID] [--cursor CURSOR] [--limit N] --json', '36', use_color)}",
+        f"  {_style('cdx conversation <name> [--conversation ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json', '36', use_color)}",
         f"  {_style('cdx can-resume <name> [--conversation <id>] [--json]', '36', use_color)}",
         f"  {_style('cdx rescue [<session>] [--to <target>] [--yes] [--dry-run] [--json]', '36', use_color)}",
         f"  {_style('cdx retro [--limit N] [--json]', '36', use_color)}",

package/src/commands/conversation.py

@@ -6,13 +6,17 @@ from ..conversation import read_conversation
 from ..errors import CdxError
 from ..provider_runtime import _get_auth_home
 
-CONVERSATION_USAGE = "Usage: cdx conversation <name> [--conversation ID] [--cursor CURSOR] [--limit N] --json"
+CONVERSATION_USAGE = "Usage: cdx conversation <name> [--conversation ID] [--cwd PATH] [--since ISO] [--cursor CURSOR | --tail N | --before CURSOR] [--limit N] --json"
 
 
 def handle_conversation(rest, ctx):
     parsed = _parse_flag_args(rest, {
         "--json": {"key": "json", "type": "bool", "default": False},
         "--conversation": {"key": "conversation", "type": "str"},
+        "--cwd": {"key": "cwd", "type": "str"},
+        "--since": {"key": "since", "type": "str"},
+        "--tail": {"key": "tail", "type": "str"},
+        "--before": {"key": "before", "type": "str"},
         "--cursor": {"key": "cursor", "type": "str"},
         "--limit": {"key": "limit", "type": "str", "default": "100"},
     }, CONVERSATION_USAGE, positionals_key="names", max_positionals=1)
@@ -23,12 +27,14 @@ def handle_conversation(rest, ctx):
         raise CdxError(f"Unknown session: {parsed['names'][0]}")
     try:
         limit = int(parsed["limit"])
+        tail = int(parsed["tail"]) if parsed["tail"] is not None else None
     except ValueError:
         raise CdxError(CONVERSATION_USAGE) from None
     page = read_conversation(
         session["provider"], _get_auth_home(session),
         conversation_id=parsed["conversation"] or (session.get("conversation") or {}).get("id"),
-        cursor=parsed["cursor"], limit=limit, fallback_to_recency=not parsed["conversation"],
+        cwd=parsed["cwd"], started_at=parsed["since"],
+        cursor=parsed["cursor"], limit=limit, tail=tail, before=parsed["before"], fallback_to_recency=not parsed["conversation"],
     )
     _write_json(ctx, _json_success("conversation", "Conversation page loaded.", session=session["name"], **page))
     return 0

package/src/conversation.py

@@ -13,6 +13,7 @@ from .interactive_usage import conversation_transcript, resolve_transcript
 
 MAX_LINE_BYTES = 1024 * 1024
 MAX_PAGE_BYTES = 8 * 1024 * 1024
+MAX_CURSOR_NAMES_BYTES = 2048
 REDACTED = "[REDACTED]"
 
 
@@ -47,18 +48,54 @@ def _tool_name(message, names, result=False):
     return name
 
 
+def _conversation_record(provider, kind):
+    # Provider bookkeeping can carry the same text as real conversation records.
+    return kind == "response_item" if provider == "codex" else kind in ("user", "assistant")
+
+
+_CLAUDE_HARNESS = re.compile(
+    r"\s*(?:<(?P<tag>task-notification|local-command-stdout|local-command-stderr|command-name|command-message|command-args|system-reminder)>"
+    r"(?:(?!</(?P=tag)>).)*</(?P=tag)>\s*)+", re.S,
+)
+_CLAUDE_MID_TURN_START = "The user sent a new message while you were working:\n"
+_CLAUDE_MID_TURN_END = re.compile(
+    r"\n+This is how Claude Code surfaces messages the user sends mid-turn[^\n]*"
+    r"Address the message above as you continue this turn\.\s*\Z"
+)
+
+
+def _claude_user_content(content):
+    """Remove complete harness wrappers, preserving ordinary prose and images."""
+    blocks = [{"type": "text", "text": content}] if isinstance(content, str) else content
+    if not isinstance(blocks, list):
+        return content
+    blocks = [dict(block) if isinstance(block, dict) else block for block in blocks]
+    texts = [block for block in blocks if isinstance(block, dict)
+             and block.get("type") == "text" and isinstance(block.get("text"), str)]
+    # Require both anchored boundaries; a quoted sentence alone is user content.
+    if texts and texts[0]["text"].startswith(_CLAUDE_MID_TURN_START):
+        end = _CLAUDE_MID_TURN_END.search(texts[-1]["text"])
+        if end:
+            texts[-1]["text"] = texts[-1]["text"][:end.start()]
+            texts[0]["text"] = texts[0]["text"][len(_CLAUDE_MID_TURN_START):].strip("\n")
+    return [block for block in blocks if not (
+        isinstance(block, dict) and block.get("type") == "text"
+        and isinstance(block.get("text"), str)
+        and (not block["text"].strip() or _CLAUDE_HARNESS.fullmatch(block["text"]))
+    )]
+
+
 def _entries(provider, record, names):
     if not isinstance(record, dict):
         return []
+    if not _conversation_record(provider, record.get("type")):
+        return []
     stamp = record.get("timestamp")
     try:
         datetime.fromisoformat(stamp.replace("Z", "+00:00"))
     except (AttributeError, TypeError, ValueError):
         stamp = None
     if provider == "codex":
-        # event_msg repeats response_item messages; consume only canonical items.
-        if record.get("type") != "response_item":
-            return []
         message = record.get("payload")
     else:
         message = record.get("message")
@@ -78,6 +115,8 @@ def _entries(provider, record, names):
     if role == "tool":
         return [_entry("tool", name=_tool_name(message, names, True), summary="Result recorded", at=stamp)]
     content = message.get("content")
+    if provider == "claude" and role == "user":
+        content = _claude_user_content(content)
     if isinstance(content, str):
         return [_entry(role, content, at=stamp)]
     if not isinstance(content, list):
@@ -92,6 +131,9 @@ def _entries(provider, record, names):
         elif kind in ("tool_use", "tool_result"):
             name = _tool_name(block, names, kind == "tool_result")
             entries.append(_entry("tool", name=name, summary="Call recorded" if kind == "tool_use" else "Result recorded", at=stamp))
+    if provider == "claude" and role == "user" and not any(e["role"] == "user" for e in entries):
+        if any(isinstance(block, dict) and block.get("type") == "image" for block in content):
+            entries.append(_entry("user", at=stamp))
     return entries
 
 
@@ -100,21 +142,238 @@ def _anchor(handle, offset):
     return hashlib.sha256(handle.read(min(offset, 128))).hexdigest()
 
 
+def _field_start(prefix, field, start=0):
+    """Find an object field before any incomplete value in a bounded prefix."""
+    decoder = json.JSONDecoder()
+    whitespace = re.compile(r"\s*")
+    try:
+        start = whitespace.match(prefix, start).end()
+        if prefix[start] != "{":
+            return None
+        start += 1
+        while True:
+            start = whitespace.match(prefix, start).end()
+            key, end = decoder.raw_decode(prefix, start)
+            if not isinstance(key, str):
+                return None
+            end = whitespace.match(prefix, end).end()
+            if prefix[end] != ":":
+                return None
+            start = whitespace.match(prefix, end + 1).end()
+            if key == field:
+                return start
+            _, end = decoder.raw_decode(prefix, start)
+            end = whitespace.match(prefix, end).end()
+            if prefix[end] != ",":
+                return None
+            start = end + 1
+    except (ValueError, IndexError, RecursionError):
+        return None
+
+
+def _oversized_entry(provider, prefix):
+    prefix = prefix.decode("utf-8", errors="replace")
+    kind = _field_start(prefix, "type")
+    try:
+        value, _ = json.JSONDecoder().raw_decode(prefix, kind) if kind is not None else (None, 0)
+    except (ValueError, RecursionError):
+        value = None
+    if not _conversation_record(provider, value):
+        return None
+    message = _field_start(prefix, "payload" if provider == "codex" else "message")
+    if message is None or prefix[message:message + 1] != "{":
+        return None
+    role = _field_start(prefix, "role", message)
+    if role is None and provider != "codex":
+        role = _field_start(prefix, "type")
+    try:
+        value, _ = json.JSONDecoder().raw_decode(prefix, role) if role is not None else (None, 0)
+    except (ValueError, RecursionError):
+        value = None
+    return _entry(value if value in ("user", "assistant", "tool") else "tool",
+                  "[élément trop volumineux ignoré]")
+
+
+REVERSE_BLOCK_BYTES = 64 * 1024
+
+
+def _encode_cursor(handle, identity, offset, index, names):
+    names = dict(names)
+    while len(json.dumps(names, separators=(",", ":")).encode()) > MAX_CURSOR_NAMES_BYTES:
+        names.pop(next(iter(names)))
+    state = {"v": 1, "file": identity, "offset": offset, "index": index,
+             "anchor": _anchor(handle, offset), "names": names}
+    return base64.urlsafe_b64encode(json.dumps(state, separators=(",", ":")).encode()).decode()
+
+
+def _reverse_records(handle, end):
+    """Yield line positions and bounded prefixes, including an incomplete tail."""
+    position, line_end, length, prefix = end, end, 0, b""
+    while position:
+        start = max(0, position - REVERSE_BLOCK_BYTES)
+        handle.seek(start)
+        block = handle.read(position - start)
+        right = len(block)
+        while right:
+            newline = block.rfind(b"\n", 0, right)
+            left = newline + 1
+            part = block[left:right]
+            length += len(part)
+            prefix = (part + prefix)[:MAX_LINE_BYTES + 1]
+            if newline < 0:
+                break
+            if length:
+                yield start + left, line_end, prefix, length
+            line_end = start + left
+            length, prefix, right = 1, b"\n", newline
+        position = start
+    if length:
+        yield 0, line_end, prefix, length
+
+
+def _record_entries(provider, prefix, length, names):
+    if length > MAX_LINE_BYTES:
+        entry = _oversized_entry(provider, prefix)
+        return [entry] if entry is not None else []
+    try:
+        return _entries(provider, json.loads(prefix), names)
+    except (ValueError, UnicodeError, RecursionError):
+        return []
+
+
+class _NameLookups(dict):
+    def __init__(self):
+        super().__init__()
+        self.missing = set()
+
+    def get(self, key, default=None):
+        if key not in self:
+            self.missing.add(key)
+        return super().get(key, default)
+
+
+def _read_tail(handle, stat, identity, provider, page, count, before):
+    end, stop_index = stat.st_size, None
+    snapshot = {"size": stat.st_size, "mtime": stat.st_mtime_ns,
+                "anchor": _anchor(handle, stat.st_size)}
+    if before is not None:
+        try:
+            if not isinstance(before, str) or len(before) > 4096:
+                raise ValueError
+            state = json.loads(base64.urlsafe_b64decode(before.encode("ascii")))
+            end, stop_index = state["offset"], state["index"]
+            snapshot = state["snapshot"]
+            size = snapshot["size"]
+            if (state["v"] != 2 or state["file"] != identity or state["direction"] != "before"
+                    or type(end) is not int or type(stop_index) is not int
+                    or type(size) is not int or not 0 <= end <= size <= stat.st_size
+                    or not 0 <= stop_index <= MAX_LINE_BYTES
+                    or state["anchor"] != _anchor(handle, end)
+                    or snapshot["anchor"] != _anchor(handle, size)
+                    or (size == stat.st_size and snapshot["mtime"] != stat.st_mtime_ns)):
+                raise ValueError
+        except (ValueError, TypeError, KeyError, AttributeError, UnicodeError):
+            return {**page, "status": "reset_required", "reason": "invalid_or_stale_cursor"}
+    # Include the boundary record when a page split its content blocks.
+    boundary_end = end
+    if stop_index:
+        handle.seek(end)
+        line = handle.readline(MAX_LINE_BYTES + 1)
+        if not line.endswith(b"\n") or len(line) > MAX_LINE_BYTES:
+            return {**page, "status": "reset_required", "reason": "invalid_or_stale_cursor"}
+        boundary_end = end + len(line)
+    selected, remaining, names = [], count, {}
+    earliest = (end, stop_index or 0)
+    forward_end = (end, stop_index or 0)
+    lookback_start = None
+    missing_names = set()
+    for start, record_end, prefix, length in _reverse_records(handle, boundary_end):
+        if not prefix.endswith(b"\n") and length <= MAX_LINE_BYTES:
+            # The first reverse record may be an unfinished provider write.
+            forward_end = (start, 0)
+            continue
+        if length > MAX_LINE_BYTES:
+            handle.seek(record_end - 1)
+            if handle.read(1) != b"\n":
+                forward_end = (start, 0)
+                continue
+        local_names = _NameLookups()
+        entries = _record_entries(provider, prefix, length, local_names)
+        if start == end and stop_index and stop_index >= len(entries):
+            return {**page, "status": "reset_required", "reason": "invalid_or_stale_cursor"}
+        if remaining:
+            upper = stop_index if start == end and stop_index is not None else len(entries)
+            lower = max(0, upper - remaining)
+            if upper > lower:
+                selected.append((start, prefix, length, lower, upper))
+                missing_names.update(local_names.missing)
+                missing_names.difference_update(local_names)
+                remaining -= upper - lower
+                earliest = (start, lower)
+                if len(selected) == 1:
+                    forward_end = (start, upper) if upper < len(entries) else (record_end, 0)
+            if not remaining:
+                lookback_start = start
+        else:
+            # Recover recent call names before normalizing the selected window.
+            for key, name in local_names.items():
+                names.setdefault(key, name)
+            missing_names.difference_update(local_names)
+            budget = MAX_PAGE_BYTES if missing_names else REVERSE_BLOCK_BYTES
+            if len(names) >= 100 or lookback_start - start >= budget:
+                break
+    if remaining:
+        earliest = (0, 0)
+    names = dict(reversed(list(names.items())))
+    for start, prefix, length, lower, upper in reversed(selected):
+        entries = _record_entries(provider, prefix, length, names)
+        for index in range(lower, upper):
+            entry = entries[index]
+            entry["id"] = f"{identity[:16]}:{start}:{index}"
+            page["entries"].append(entry)
+    offset, index = forward_end
+    page["next_cursor"] = _encode_cursor(handle, identity, offset, index, names)
+    page["has_more"] = offset < stat.st_size
+    offset, index = earliest
+    page["before_cursor"] = None
+    if offset or index:
+        state = {"v": 2, "direction": "before", "file": identity, "offset": offset,
+                 "index": index, "anchor": _anchor(handle, offset), "snapshot": snapshot}
+        page["before_cursor"] = base64.urlsafe_b64encode(json.dumps(state, separators=(",", ":")).encode()).decode()
+    return page
+
+
 def read_conversation(provider, auth_home=None, *, conversation_id=None, started_at=None,
-                      terminal_transcript=None, cursor=None, limit=100, fallback_to_recency=False):
+                      terminal_transcript=None, cursor=None, limit=100, fallback_to_recency=False, tail=None, before=None, cwd=None):
     """Return a JSON-serializable page; pass next_cursor back unchanged to poll.
 
     Entries follow file/block order. Cursors bind a byte offset and block index
     to the resolved file; reset_required means discard the old cursor and page
     again from the beginning. Incomplete trailing lines are retried next time.
+    tail selects the latest entries; before selects entries preceding an opaque
+    backward cursor. Both return before_cursor as well as a forward next_cursor.
     Only implicit session identities may opt into fallback_to_recency.
+    Recency is restricted to cwd (the process directory by default), and to
+    transcripts modified at or after started_at when supplied.
     Tool bodies and reasoning blocks are never returned. Ollama PTY captures
     cannot reliably distinguish roles and are explicitly unsupported.
     """
     if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 1000:
         raise CdxError("Conversation limit must be an integer between 1 and 1000.")
+    if tail is not None and (type(tail) is not int or not 1 <= tail <= 1000):
+        raise CdxError("Conversation tail must be an integer between 1 and 1000.")
+    if cursor is not None and (tail is not None or before is not None):
+        raise CdxError("Conversation --cursor cannot be combined with --tail or --before.")
+    if started_at is not None:
+        try:
+            datetime.fromisoformat(started_at.replace("Z", "+00:00"))
+        except (ValueError, AttributeError, TypeError):
+            raise CdxError("Conversation --since must be an ISO timestamp.") from None
+    scope = {"cwd": os.path.realpath(os.path.expanduser(cwd or os.getcwd())), "since": started_at}
     page = {"status": "ok", "reason": None, "provider": provider, "entries": [], "next_cursor": None, "has_more": False,
-            "resolution_method": None}
+            "resolution_method": None, "resolution_scope": None}
+    if tail is not None or before is not None:
+        page["before_cursor"] = None
     if provider not in PROVIDERS or provider == "ollama":
         return {**page, "status": "unsupported", "reason": "no_structured_transcript_reader"}
     # An explicit conversation must never fall back to an unrelated recent file.
@@ -123,15 +382,20 @@ def read_conversation(provider, auth_home=None, *, conversation_id=None, started
         if path:
             page["resolution_method"] = "conversation_id"
         elif fallback_to_recency:
-            path, page["resolution_method"] = resolve_transcript(provider, auth_home)
+            page["resolution_scope"] = scope
+            path, page["resolution_method"] = resolve_transcript(provider, auth_home, started_at, cwd=scope["cwd"])
     else:
-        path, page["resolution_method"] = resolve_transcript(provider, auth_home, started_at, terminal_transcript=terminal_transcript)
+        page["resolution_scope"] = scope
+        path, page["resolution_method"] = resolve_transcript(provider, auth_home, started_at, terminal_transcript=terminal_transcript, cwd=scope["cwd"])
     if not path:
-        return {**page, "status": "unavailable", "reason": "transcript_not_found"}
+        reason = "no_conversation_yet" if page["resolution_scope"] is not None else "transcript_not_found"
+        return {**page, "status": "unavailable", "reason": reason}
     try:
         with open(path, "rb") as handle:
             stat = os.fstat(handle.fileno())
             identity = hashlib.sha256(f"{provider}:{os.path.realpath(path)}:{stat.st_dev}:{stat.st_ino}".encode()).hexdigest()
+            if tail is not None or before is not None:
+                return _read_tail(handle, stat, identity, provider, page, tail if tail is not None else limit, before)
             offset, index, names = 0, 0, {}
             if cursor is not None:
                 try:
@@ -158,14 +422,22 @@ def read_conversation(provider, auth_home=None, *, conversation_id=None, started
                 start = handle.tell()
                 line = handle.readline(MAX_LINE_BYTES + 1)
                 if len(line) > MAX_LINE_BYTES:
-                    return {**page, "status": "unavailable", "reason": "record_too_large", "entries": []}
-                if not line or not line.endswith(b"\n"):
-                    break
-                scanned += len(line)
-                try:
-                    entries = _entries(provider, json.loads(line), names)
-                except (ValueError, UnicodeError):
-                    entries = []
+                    entry = _oversized_entry(provider, line)
+                    # Finish this record even beyond the page scan budget. Never
+                    # retain its body, and retry from start if its newline is pending.
+                    while line and not line.endswith(b"\n"):
+                        line = handle.readline(MAX_LINE_BYTES + 1)
+                    if not line:
+                        break
+                    entries = [entry] if entry is not None else []
+                else:
+                    if not line or not line.endswith(b"\n"):
+                        break
+                    try:
+                        entries = _entries(provider, json.loads(line), names)
+                    except (ValueError, UnicodeError):
+                        entries = []
+                scanned += handle.tell() - start
                 for block_index in range(index, len(entries)):
                     entry = entries[block_index]
                     entry["id"] = f"{identity[:16]}:{start}:{block_index}"
@@ -180,8 +452,7 @@ def read_conversation(provider, auth_home=None, *, conversation_id=None, started
                     break
                 offset, index = handle.tell(), 0
             page["has_more"] = offset < stat.st_size
-            state = {"v": 1, "file": identity, "offset": offset, "index": index, "anchor": _anchor(handle, offset), "names": names}
-            page["next_cursor"] = base64.urlsafe_b64encode(json.dumps(state, separators=(",", ":")).encode()).decode()
+            page["next_cursor"] = _encode_cursor(handle, identity, offset, index, names)
             return page
     except OSError:
         return {**page, "status": "unavailable", "reason": "transcript_unreadable", "entries": []}

package/src/interactive_usage.py

@@ -14,6 +14,7 @@ import re
 import time
 
 from .run_usage import claude_usage_dedup_key, normalize_usage
+from .shared_memory import claude_project_name
 from .status_source import _normalize_terminal_transcript
 
 # Readers stream JSONL line-by-line.  A 16 MiB cap excluded ordinary long
@@ -84,7 +85,7 @@ def extract_interactive_usage(provider, auth_home, started_at=None, conversation
 
 
 def resolve_transcript(provider, auth_home, started_at=None, conversation_id=None,
-                       terminal_transcript=None):
+                       terminal_transcript=None, cwd=None):
     """The transcript belonging to this session, and how confidently."""
     if provider == "ollama":
         # No provider-native transcript exists to resolve. The run's own PTY
@@ -108,7 +109,7 @@ def resolve_transcript(provider, auth_home, started_at=None, conversation_id=Non
         # a Codex rollout lives under the session's own auth home, so the
         # newest one touched during this run is this session's current
         # conversation, not somebody else's file.
-    path = _latest_transcript(provider, auth_home, started_at)
+    path = _latest_transcript(provider, auth_home, started_at, cwd=cwd)
     return path, (MATCH_RECENCY if path else None)
 
 
@@ -166,10 +167,25 @@ def _codex_rollout_for(auth_home, conversation_id):
 _READERS = {}
 
 
-def _latest_transcript(provider, auth_home, started_at):
+def _codex_matches_cwd(path, cwd):
+    """Fail closed when the bounded session metadata cannot identify a project."""
+    try:
+        with open(path, encoding="utf-8") as handle:
+            record = json.loads(handle.readline(64 * 1024))
+        recorded = record["payload"]["cwd"] if record["type"] == "session_meta" else None
+        return isinstance(recorded, str) and os.path.isabs(recorded) and os.path.realpath(recorded) == cwd
+    except (OSError, ValueError, KeyError, TypeError, RecursionError):
+        return False
+
+
+def _latest_transcript(provider, auth_home, started_at, cwd=None):
     if not auth_home:
         return None
     root = os.path.join(auth_home, "sessions") if provider == "codex" else os.path.join(auth_home, ".claude", "projects")
+    if cwd is not None:
+        cwd = os.path.realpath(cwd)
+        if provider != "codex":
+            root = os.path.join(root, claude_project_name(cwd))
     if not os.path.isdir(root):
         return None
     cutoff = _timestamp(started_at)
@@ -181,9 +197,11 @@ def _latest_transcript(provider, auth_home, started_at):
             # reached". Returning a partial answer here is what made a wrong
             # attribution indistinguishable from a real measurement.
             return None
-        if provider == "claude":
+        if provider == "claude" or cwd is not None:
             subdirs[:] = [name for name in subdirs if name != "subagents"]
         for name in names:
+            if time.monotonic() >= deadline:
+                return None
             if not name.endswith(".jsonl"):
                 continue
             path = os.path.join(directory, name)
@@ -192,6 +210,8 @@ def _latest_transcript(provider, auth_home, started_at):
             except OSError:
                 continue
             if cutoff is None or modified >= cutoff:
+                if cwd is not None and provider == "codex" and not _codex_matches_cwd(path, cwd):
+                    continue
                 candidates.append((modified, path))
                 if len(candidates) > MAX_TRANSCRIPT_CANDIDATES:
                     return None