codex-statusline 0.1.0__py3-none-any.whl

codex_statusline-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: codex-statusline
+Version: 0.1.0
+Summary: A tmux statusline for OpenAI Codex CLI: context usage, 5h and weekly quota, and session tokens at a glance. Local-only.
+Author: Zimo Xu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Moviw/codex-statusline
+Project-URL: Issues, https://github.com/Moviw/codex-statusline/issues
+Project-URL: Changelog, https://github.com/Moviw/codex-statusline/blob/main/CHANGELOG.md
+Keywords: codex,codex-cli,openai,statusline,tmux,quota,tokens,terminal
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# codex-statusline
+
+**See your Codex context and quota at a glance.**
+
+[![tests](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml/badge.svg)](https://github.com/Moviw/codex-statusline/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/codex-statusline)](https://pypi.org/project/codex-statusline/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+English | [简体中文](README.zh-CN.md)
+
+A status bar for [OpenAI Codex CLI](https://github.com/openai/codex). It shows context used, 5-hour and weekly quota left with reset times, and session tokens. You keep running `codex` exactly as before.
+
+![codex-statusline demo](docs/preview.svg)
+
+```text
+CTX USED ███░░░░░ 35% | 5h ████████░░ 78% 5:41pm | week ████░░░░░░ 39% Fri 3:41pm | tok 1.2M
+```
+
+## Why
+
+- **No more `/status` interruptions.** Quota and context sit in view while you work.
+- **Local only.** Never reads `auth.json`, never calls a quota API, never makes extra model calls.
+- **Zero new habits.** Keep typing `codex`. `codex exec`, pipes, and scripts pass straight through to the official binary.
+- **Honest numbers.** Unknown shows as `--` and stale quota shows as `refresh`. A missing value is never passed off as 0% or 100%.
+- **Fits any width.** Segments collapse, then drop, as the terminal narrows.
+
+## Install
+
+Requires macOS or Linux, [tmux](https://github.com/tmux/tmux), and Codex CLI ≥ 0.159.0. Bash, Zsh, and Fish are all detected automatically.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Moviw/codex-statusline/main/install.sh | sh
+```
+
+The script installs [uv](https://docs.astral.sh/uv/) if needed (uv also fetches Python 3.11+ for you), installs the tool, then shows you the exact shell/hook diff and asks before writing anything.
+
+Prefer to do it yourself:
+
+```sh
+uv tool install codex-statusline    # or: pipx install codex-statusline
+codex-statusline install            # add --dry-run to only preview the diff
+```
+
+Then **open a new terminal** and run `codex`. The first time, Codex asks you to review a hook: confirm it is `codex-statusline binding`.
+
+Missing tmux? `brew install tmux` or `sudo apt install tmux`.
+
+## Usage
+
+```sh
+codex                     # same as always, now with a status bar
+codex resume --last
+codex exec 'task'         # non-interactive: passed straight through, no bar
+
+codex-statusline doctor   # check versions and dependencies
+codex-statusline preview --demo --width 80   # try it without launching Codex
+codex-statusline uninstall
+```
+
+Uninstall removes only what this tool added and still matches exactly. If you edited its block, it stops instead of overwriting. Backups live in `~/.local/share/codex-statusline/`.
+
+## Configuration
+
+Optional. Create `~/.config/codex-statusline/config.toml`:
+
+```toml
+segments = ["ctx", "5h", "week", "tokens"]  # pick and reorder
+theme = "dark"     # dark | light
+ascii = false      # true for terminals without block glyphs
+warn_at = 20       # quota remaining % that turns yellow
+crit_at = 5        # quota remaining % that turns red
+```
+
+Invalid values are reported and fall back to defaults.
+
+## How it works
+
+`codex` becomes a small shell function that starts the official CLI inside a private tmux session and draws the bar at the bottom. Data comes from two places only: the terminal title Codex already emits (model, context, thread id), and the rollout log of *this* session, which a SessionStart hook pins by exact path. The official binary is not replaced or patched, and your tmux config is not touched. Details: [docs/architecture.md](docs/architecture.md).
+
+## FAQ
+
+**How do I scroll or copy?** It runs inside tmux: press `Ctrl-B` then `[` to scroll and copy. The mouse wheel may behave differently from bare Codex.
+
+**Windows?** Not supported (tmux).
+
+**Is this official?** No. It is a third-party tool built on a version-sensitive integration.

codex_statusline-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+codex_statusline-0.1.0.dist-info/licenses/LICENSE,sha256=jzDgwLLFaXpRdL0dDiuJXjpjU-sUFu0t25vl4H71_7s,1064
+src/__init__.py,sha256=xB7hmFE2OX3Czlv6TtZvK5KrXEykajXgc3pVxVdvTKc,87
+src/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+src/cli.py,sha256=VXeVQAQXDiJMQr44kYYWbtMyuEx9uz6BIibDGRJOjI8,4246
+src/data.py,sha256=cKkSnPqGgC2XmhxxbDpDb7qMDeATboS3lbkTEcWe5KQ,10603
+src/entry.py,sha256=SLB21OlZwY9MN6TTTr-DzAvpgcGQhyNT42bqexeLWUk,286
+src/hook.py,sha256=NAab4kB2PoL5CsxGqpVmJCxN6hlPFZftnoAyVtkVPwA,2503
+src/launcher.py,sha256=A8mCMsx3I4FvCbKlJrFw56Sveo4OFYPYKrfgO9vbRSU,12606
+src/manage.py,sha256=xPWoQWKh9m21ak0sgZ3YyReCRs0erzqNuue9ktCSDEc,11285
+src/render.py,sha256=hhFQS33q4yxXrOBkMytKk5fYVa5p3RQt9V758zv_fzg,10443
+codex_statusline-0.1.0.dist-info/METADATA,sha256=qNc-OUl2icktQe5VU8AHtzRnLJlnw41lHyk7vCyiiGs,4804
+codex_statusline-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+codex_statusline-0.1.0.dist-info/entry_points.txt,sha256=YocAJa23XIYJYNCNs2DaG2ggb1PiyjqQaz1DjrF9Q04,50
+codex_statusline-0.1.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+codex_statusline-0.1.0.dist-info/RECORD,,

codex_statusline-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

codex_statusline-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-statusline = src.cli:main

codex_statusline-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zimo Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_statusline-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/__init__.py

@@ -0,0 +1,3 @@
+"""A local-only tmux status area for the official Codex CLI."""
+
+__version__ = "0.1.0"

src/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

src/cli.py

@@ -0,0 +1,120 @@
+import argparse
+import json
+import os
+import shutil
+import sys
+import time
+from pathlib import Path
+
+from . import __version__
+
+
+def main():
+    args = sys.argv[1:]
+    from .launcher import child, launch, official, raw, version
+
+    if args and args[0] in ("launch", "raw"):
+        try:
+            return (launch if args[0] == "launch" else raw)(args[1:])
+        except KeyboardInterrupt:
+            return 130
+    if args and args[0] == "_child":
+        return child(args[1])
+    if args and args[0] == "hook":
+        from .hook import record
+
+        record()
+        return 0
+    parser = argparse.ArgumentParser(
+        description="Third-party local tmux statusline for the official Codex CLI."
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="action", required=True)
+    for name in ("install", "uninstall"):
+        s = sub.add_parser(name)
+        s.add_argument(
+            "--shell",
+            choices=["auto", "bash", "zsh", "fish", "both", "all"],
+            default="auto",
+            help="default: all supported shells found on PATH",
+        )
+        s.add_argument("--home", default=str(Path.home()), help="target home (for isolated tests)")
+        s.add_argument(
+            "--yes",
+            action="store_true",
+            help="approve printed diff without interactive prompt",
+        )
+        s.add_argument("--dry-run", action="store_true")
+    sub.add_parser("doctor")
+    p = sub.add_parser("preview")
+    p.add_argument("--width", type=int, default=120)
+    p.add_argument("--theme", choices=["dark", "light"])
+    p.add_argument("--ascii", action="store_true")
+    p.add_argument("--tmux", action="store_true", help="emit tmux style syntax, not ANSI")
+    p.add_argument("--demo", action="store_true", help="show explicitly synthetic example data")
+    ns = parser.parse_args(args)
+    try:
+        if ns.action in ("install", "uninstall"):
+            from .manage import installation
+
+            return installation(ns, ns.action == "uninstall")
+        if ns.action == "doctor":
+            path = official()
+            data = {
+                "python": sys.version.split()[0],
+                "codex": path,
+                "codex_version": ".".join(map(str, version(path))),
+                "tmux": shutil.which("tmux"),
+                "shell": os.environ.get("SHELL"),
+                "tested_codex": "0.159.0",
+                "credentials_read": False,
+            }
+            print(json.dumps(data, indent=2))
+            return 0 if data["tmux"] and version(path) >= (0, 159, 0) else 1
+        if ns.action == "preview":
+            from .render import load_config, render
+
+            cfg = load_config()
+            now = time.time()
+            state = {
+                "model": "Codex",
+                "cwd": os.getcwd(),
+                "context_used": None,
+                "quotas": {},
+            }
+            if ns.demo:
+                state.update(
+                    model="DEMO GPT-6",
+                    context_used=35,
+                    cwd="~/project",
+                    branch="main",
+                    tokens=1_234_567,
+                    quotas={
+                        "5h": {
+                            "remaining": 78,
+                            "reset_at": now + 7200,
+                            "observed_at": now,
+                        },
+                        "weekly": {
+                            "remaining": 39,
+                            "reset_at": now + 172800,
+                            "observed_at": now,
+                        },
+                    },
+                )
+            print(
+                render(
+                    state,
+                    ns.width,
+                    theme=ns.theme or cfg["theme"],
+                    ascii_only=ns.ascii or cfg["ascii"],
+                    tmux=ns.tmux,
+                    segments=cfg["segments"],
+                    warn_at=cfg["warn_at"],
+                    crit_at=cfg["crit_at"],
+                )
+            )
+            return 0
+    except (OSError, ValueError, RuntimeError, KeyError) as error:
+        print(f"codex-statusline: {error}", file=sys.stderr)
+        return 1

src/data.py

@@ -0,0 +1,269 @@
+"""Bounded parsers for Codex native title and explicitly selected session logs.
+
+This module deliberately does not discover log files.  Callers must provide the
+path for the session they already bound to the UI.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+_SESSION_HINT = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{5}\.\.\.$"
+)
+_FULL_SESSION = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+_CONTEXT = re.compile(r"^Context ([0-9]+(?:\.[0-9]+)?)% used$")
+_MAX_READ_BYTES = 1024 * 1024
+
+
+def parse_title(title: str) -> dict[str, Any]:
+    """Parse Codex's native ``[model, context-used, thread-id]`` title.
+
+    The emitted thread ID is a UUID shortened to its first 29 characters and
+    ``...``.  A full UUID is also accepted for environments that render it
+    without truncation.  A two-field ``model | session`` title is a valid
+    context-less variant; its context is returned as ``None``.  Malformed or
+    ambiguous titles raise ``ValueError`` rather than guessing.
+    """
+    if not isinstance(title, str):
+        raise TypeError("title must be a string")
+    parts = [part.strip() for part in title.split("|")]
+    if len(parts) not in (2, 3) or not parts[0]:
+        raise ValueError("not a supported Codex status title")
+
+    session_hint = re.sub(
+        r" [\u2800-\u28ff]$", "", parts[-1]
+    )  # native thread-title progress spinner
+    if not (_SESSION_HINT.fullmatch(session_hint) or _FULL_SESSION.fullmatch(session_hint)):
+        raise ValueError("title does not end in a recognizable thread ID")
+
+    context_used: float | None = None
+    if len(parts) == 3:
+        match = _CONTEXT.fullmatch(parts[1])
+        if match:
+            parsed_context = float(match.group(1))
+            if math.isfinite(parsed_context) and 0.0 <= parsed_context <= 100.0:
+                context_used = parsed_context
+        elif parts[1] not in ("Context unknown", ""):
+            raise ValueError("unrecognized context field")
+
+    return {
+        "model": parts[0],
+        "context_used": context_used,
+        "session_hint": session_hint,
+    }
+
+
+def _timestamp(value: Any) -> float | None:
+    """Convert supported event timestamps to Unix seconds without guessing."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        number = float(value)
+        return number if math.isfinite(number) else None
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        try:
+            number = float(text)
+        except ValueError:
+            try:
+                parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+            except ValueError:
+                return None
+            if parsed.tzinfo is None:
+                parsed = parsed.replace(tzinfo=UTC)
+            return parsed.timestamp()
+        return number if math.isfinite(number) else None
+    return None
+
+
+def _empty_quotas() -> dict[str, dict[str, float | None]]:
+    return {
+        "5h": {"remaining": None, "reset_at": None, "observed_at": None},
+        "weekly": {"remaining": None, "reset_at": None, "observed_at": None},
+    }
+
+
+class LogReader:
+    """Incrementally read quota metadata from one caller-selected JSONL file.
+
+    Each update reads at most 1 MiB.  Only complete JSONL records are parsed;
+    an incomplete tail is held up to 1 MiB, then discarded through its newline.
+    State is reset on path changes, file rotation, or truncation. Persistent
+    state is quota metadata only; bounded transient input can include arbitrary
+    JSON fields while parsed, but content is not copied into reader state/results.
+    """
+
+    def __init__(self) -> None:
+        self._path: str | None = None
+        self._identity: tuple[int, int] | None = None
+        self._offset = 0
+        self._partial = b""
+        self._discard_until_newline = False
+        self._probe = b""
+        self._quotas = _empty_quotas()
+        self._tokens: float | None = None
+
+    def _reset(self, path: str) -> None:
+        self._path = path
+        self._identity = None
+        self._offset = 0
+        self._partial = b""
+        self._discard_until_newline = False
+        self._probe = b""
+        self._quotas = _empty_quotas()
+        self._tokens = None
+
+    def _consume_line(self, line: bytes) -> None:
+        try:
+            event = json.loads(line)
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return
+        if not isinstance(event, dict) or event.get("type") != "event_msg":
+            return
+        observed_at = _timestamp(event.get("timestamp"))
+        if observed_at is None:
+            return
+        payload = event.get("payload")
+        if not isinstance(payload, dict) or payload.get("type") != "token_count":
+            return
+        info = payload.get("info")
+        total = info.get("total_token_usage") if isinstance(info, dict) else None
+        tokens = total.get("total_tokens") if isinstance(total, dict) else None
+        if (
+            isinstance(tokens, (int, float))
+            and not isinstance(tokens, bool)
+            and math.isfinite(tokens)
+            and tokens >= 0
+        ):
+            self._tokens = float(tokens)
+        # Native versions may keep rate_limits inside info; quota-only events
+        # can instead carry rate_limits directly on payload (even if info is null).
+        rate_limits = info.get("rate_limits") if isinstance(info, dict) else None
+        if not isinstance(rate_limits, dict):
+            rate_limits = payload.get("rate_limits")
+        if not isinstance(rate_limits, dict):
+            return
+
+        for key, label, expected_window in (
+            ("primary", "5h", 300),
+            ("secondary", "weekly", 10080),
+        ):
+            quota = rate_limits.get(key)
+            if not isinstance(quota, dict) or quota.get("window_minutes") != expected_window:
+                continue
+            used = quota.get("used_percent")
+            if isinstance(used, bool) or not isinstance(used, (int, float)):
+                continue
+            used = float(used)
+            if not math.isfinite(used):
+                continue
+            prior = self._quotas[label]
+            if prior["observed_at"] is not None and observed_at < float(prior["observed_at"]):
+                continue
+            reset_at = _timestamp(quota.get("resets_at"))
+            self._quotas[label] = {
+                "remaining": max(0.0, min(100.0, 100.0 - used)),
+                "reset_at": reset_at,
+                "observed_at": observed_at,
+            }
+
+    def _consume_bytes(self, data: bytes) -> None:
+        if self._discard_until_newline:
+            newline = data.find(b"\n")
+            if newline < 0:
+                return
+            self._discard_until_newline = False
+            data = data[newline + 1 :]
+        data = self._partial + data
+        lines = data.split(b"\n")
+        tail = lines.pop()  # last record is parsed only once terminated
+        for line in lines:
+            if line:
+                self._consume_line(line)
+        if len(tail) >= _MAX_READ_BYTES:
+            self._partial = b""
+            self._discard_until_newline = True
+        else:
+            self._partial = tail
+
+    def update(self, path: str) -> dict[str, Any]:
+        """Read newly appended quota/token events from exactly ``path``."""
+        if not isinstance(path, str) or not path:
+            raise ValueError("path must be a non-empty string")
+        if self._path != path:
+            self._reset(path)
+
+        try:
+            stat = os.stat(path)
+            identity = (stat.st_dev, stat.st_ino)
+            skip_partial_record = False
+            overwritten = False
+            if (
+                identity == self._identity
+                and self._identity is not None
+                and self._probe
+                and stat.st_size >= self._offset
+            ):
+                with open(path, "rb") as probe_stream:
+                    probe_stream.seek(self._offset - len(self._probe))
+                    overwritten = probe_stream.read(len(self._probe)) != self._probe
+            if identity != self._identity or stat.st_size < self._offset or overwritten:
+                self._identity = identity
+                self._offset = 0
+                self._partial = b""
+                self._discard_until_newline = False
+                self._probe = b""
+                self._quotas = _empty_quotas()
+                self._tokens = None
+                if stat.st_size > _MAX_READ_BYTES:
+                    # Start at a bounded tail boundary, discarding its possibly
+                    # incomplete first line.  Current quota events remain
+                    # available without reading an arbitrarily large history.
+                    self._offset = stat.st_size - _MAX_READ_BYTES
+                    skip_partial_record = True
+            with open(path, "rb") as stream:
+                stream.seek(self._offset)
+                chunk = stream.read(_MAX_READ_BYTES)
+                self._offset = stream.tell()
+            if chunk:
+                self._probe = chunk[-64:]
+            if skip_partial_record:
+                # Initial tail read: do not interpret a fragment cut from the
+                # front of a JSON record.
+                newline = chunk.find(b"\n")
+                if newline < 0:
+                    self._partial = b""
+                    self._discard_until_newline = True
+                else:
+                    chunk = chunk[newline + 1 :]
+                self._consume_bytes(chunk)
+            else:
+                self._consume_bytes(chunk)
+        except FileNotFoundError:
+            # A missing bound file has no metadata yet.  Retain the selected
+            # path, but a later appearance will be picked up by identity reset.
+            self._identity = None
+            self._offset = 0
+            self._partial = b""
+            self._discard_until_newline = False
+            self._probe = b""
+            self._quotas = _empty_quotas()
+            self._tokens = None
+        except OSError:
+            # Avoid exporting filesystem details or turning transient I/O into
+            # fabricated quota data; previously observed metadata remains.
+            pass
+        return {
+            "quotas": {name: dict(value) for name, value in self._quotas.items()},
+            "tokens": self._tokens,
+        }

src/entry.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""Absolute script entry for shell functions, hooks and private tmux panes."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from src.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/hook.py

@@ -0,0 +1,75 @@
+"""Silent SessionStart metadata recorder; no credentials or conversation copies."""
+
+import fcntl
+import json
+import os
+import stat
+import sys
+import tempfile
+import time
+import uuid
+from pathlib import Path
+
+
+def atomic_json(path, data):
+    fd, temp = tempfile.mkstemp(prefix=".write-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w") as stream:
+            json.dump(data, stream)
+        os.replace(temp, path)
+    finally:
+        if os.path.exists(temp):
+            os.unlink(temp)
+
+
+def record():
+    directory = os.environ.get("CODEX_STATUSLINE_STATE")
+    launch = os.environ.get("CODEX_STATUSLINE_LAUNCH")
+    if not directory or not launch:
+        return  # Do not even read stdin for ordinary Codex sessions.
+    try:
+        uuid.UUID(launch)
+        root = Path(directory)
+        info = root.lstat()
+        if (
+            not root.is_absolute()
+            or not stat.S_ISDIR(info.st_mode)
+            or info.st_uid != os.getuid()
+            or info.st_mode & 0o077
+        ):
+            return
+        config = json.loads((root / "launch.json").read_text())
+        if config["launch_id"] != launch:
+            return
+        raw = sys.stdin.buffer.read(65537)
+        if len(raw) > 65536:
+            return
+        event = json.loads(raw)
+        if event.get("hook_event_name") != "SessionStart":
+            return
+        sid = str(uuid.UUID(event["session_id"]))
+        transcript = event.get("transcript_path")
+        if not isinstance(transcript, str) or not Path(transcript).is_absolute():
+            return
+        binding = {k: event.get(k) for k in ("cwd", "model", "source")}
+        binding.update(
+            session_id=sid,
+            transcript_path=transcript,
+            launch_id=launch,
+            recorded_at=time.time(),
+        )
+        # Keep exact bindings for switching back to a still-open thread. Never scan logs.
+        with (root / "lock").open("a") as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX)
+            try:
+                bindings = json.loads((root / "bindings.json").read_text())
+            except (OSError, ValueError):
+                bindings = {}
+            bindings[sid] = binding
+            if len(bindings) > 64:
+                bindings = dict(
+                    sorted(bindings.items(), key=lambda item: item[1]["recorded_at"])[-64:]
+                )
+            atomic_json(root / "bindings.json", bindings)
+    except (OSError, ValueError, TypeError, KeyError, AttributeError):
+        return