davinci-resolve-mcp 2.95.3 → 2.97.0

package/install.py

@@ -3,7 +3,7 @@
 DaVinci Resolve MCP Server — Universal Installer
 
 Supports: macOS, Windows, Linux
-Configures: Claude Desktop, Claude Code, Cursor, VS Code (Copilot),
+Configures: Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code (Copilot),
             Windsurf, Cline, Roo Code, Zed, Continue, OpenCode, and manual setup.
 
 Usage:
@@ -18,6 +18,7 @@ import json
 import math
 import os
 import platform
+import re
 import shutil
 import subprocess
 import sys
@@ -36,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.95.3"
+VERSION = "2.97.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -318,6 +319,16 @@ def xdg_config():
     """Linux XDG_CONFIG_HOME or default."""
     return Path(os.environ.get("XDG_CONFIG_HOME", home() / ".config"))
 
+def codex_config():
+    """OpenAI Codex CLI config path (issue #39).
+
+    Codex keeps everything under ``$CODEX_HOME`` (default ``~/.codex``) and its
+    config is TOML, not JSON -- which is why the JSON-only installer skipped it
+    and users found no ``davinci-resolve`` entry after a successful install.
+    ``scripts/doctor.py`` already probes this exact path.
+    """
+    return Path(os.environ.get("CODEX_HOME", home() / ".codex")).expanduser() / "config.toml"
+
 def vscode_global_storage():
     """VS Code global storage path per platform."""
     if is_mac():
@@ -434,6 +445,16 @@ MCP_CLIENTS = [
         "config_key": "mcp",
         "notes": "AI coding agent (uses its own type/enabled/command-array format)",
     },
+    {
+        "id": "codex",
+        "name": "Codex CLI",
+        # Codex reads $CODEX_HOME/config.toml (default ~/.codex/config.toml) and
+        # keys MCP servers under [mcp_servers.<name>]. TOML, not JSON (issue #39).
+        "get_path": codex_config,
+        "config_key": "mcp_servers",
+        "format": "toml",
+        "notes": "OpenAI's CLI agent (TOML config)",
+    },
 ]
 
 CLIENT_IDS = [c["id"] for c in MCP_CLIENTS]
@@ -523,6 +544,126 @@ def build_opencode_entry(python_path, server_path, api_path, lib_path, system=SY
     }
 
 
+def _toml_basic_string(value):
+    """Quote a value as a TOML basic string, escaping what TOML requires.
+
+    Windows paths carry backslashes, which are escape characters inside a TOML
+    basic string -- an unescaped ``C:\\Users\\...`` would either change meaning or
+    make the whole config unparseable, taking every other MCP server down with it.
+    """
+    out = []
+    for ch in str(value):
+        if ch == "\\":
+            out.append("\\\\")
+        elif ch == '"':
+            out.append('\\"')
+        elif ch == "\n":
+            out.append("\\n")
+        elif ch == "\r":
+            out.append("\\r")
+        elif ch == "\t":
+            out.append("\\t")
+        elif ord(ch) < 0x20 or ord(ch) == 0x7F:
+            out.append("\\u%04X" % ord(ch))
+        else:
+            out.append(ch)
+    return '"' + "".join(out) + '"'
+
+
+CODEX_TABLE_HEADER = "[mcp_servers.davinci-resolve]"
+
+# A line that opens a new TOML table/array-of-tables: `[foo]`, `[foo.bar]`,
+# `[[foo]]`, optionally quoted, optionally trailed by a comment. Deliberately
+# stricter than "starts with [" so a line inside a multi-line array value is not
+# mistaken for the end of our table.
+_TOML_TABLE_LINE = re.compile(r"""^\s*\[\[?\s*[A-Za-z0-9_."'\- ]+\s*\]\]?\s*(#.*)?$""")
+
+# `[mcp_servers.davinci-resolve]` in any of TOML's equivalent spellings.
+_CODEX_TABLE_LINE = re.compile(
+    r"""^\s*\[\s*(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*\.\s*"""
+    r"""(?:davinci-resolve|"davinci-resolve"|'davinci-resolve')\s*\]\s*(#.*)?$"""
+)
+
+# Inline spellings we can read but must not try to rewrite line-by-line:
+#   mcp_servers.davinci-resolve = { ... }        (dotted key at top level)
+#   davinci-resolve = { ... }                    (key inside [mcp_servers])
+#   mcp_servers = { "davinci-resolve" = ... }    (inline table at top level)
+_CODEX_DOTTED_KEY = re.compile(
+    r"""^\s*(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*\.\s*"""
+    r"""(?:davinci-resolve|"davinci-resolve"|'davinci-resolve')\s*="""
+)
+_CODEX_BARE_KEY = re.compile(r"""^\s*(?:davinci-resolve|"davinci-resolve"|'davinci-resolve')\s*=""")
+_MCP_SERVERS_INLINE = re.compile(r"""^\s*(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*=""")
+_MCP_SERVERS_TABLE = re.compile(
+    r"""^\s*\[\s*(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*\]\s*(#.*)?$"""
+)
+
+# A sub-table of ours: `[mcp_servers.davinci-resolve.env]`,
+# `[mcp_servers.davinci-resolve.tools.timeline]`, and so on. Hand-written Codex
+# configs use these for per-tool approval modes, so they must survive a rewrite.
+_CODEX_CHILD_TABLE = re.compile(
+    r"""^\s*\[\[?\s*(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*\.\s*"""
+    r"""(?:davinci-resolve|"davinci-resolve"|'davinci-resolve')\s*\.\s*"""
+    r"""[A-Za-z0-9_."'\- ]+\s*\]\]?\s*(#.*)?$"""
+)
+_CODEX_ENV_TABLE = re.compile(
+    r"""^\s*\[\s*(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*\.\s*"""
+    r"""(?:davinci-resolve|"davinci-resolve"|'davinci-resolve')\s*\.\s*"""
+    r"""(?:env|"env"|'env')\s*\]\s*(#.*)?$"""
+)
+
+
+def build_codex_entry(python_path, server_path, api_path, lib_path, system=SYSTEM, python_home=None):
+    """Build the Codex server entry as data, before it is rendered to TOML."""
+    return {
+        "command": str(python_path),
+        "args": [str(server_path)],
+        "env": build_server_env(
+            python_path, api_path, lib_path, system=system, python_home=python_home
+        ),
+    }
+
+
+def render_codex_table(entry, env_as_subtable=False):
+    """Render a Codex entry as a ``[mcp_servers.davinci-resolve]`` table.
+
+    ``env`` goes in an inline table by default -- the shape ``codex mcp add``
+    writes. When the config being edited already spells env out as an
+    ``[mcp_servers.davinci-resolve.env]`` sub-table, pass ``env_as_subtable`` so
+    the rewrite keeps that shape: TOML forbids defining ``env`` both ways, and a
+    file with both is rejected in full.
+    """
+    args = ", ".join(_toml_basic_string(arg) for arg in entry["args"])
+    lines = [
+        CODEX_TABLE_HEADER,
+        f"command = {_toml_basic_string(entry['command'])}",
+        f"args = [{args}]",
+    ]
+    env = entry.get("env") or {}
+    if env and not env_as_subtable:
+        inner = ", ".join(f"{key} = {_toml_basic_string(value)}" for key, value in env.items())
+        lines.append("env = { " + inner + " }")
+    return "\n".join(lines) + "\n"
+
+
+def render_codex_env_table(env):
+    """Render the ``[mcp_servers.davinci-resolve.env]`` sub-table form."""
+    lines = [CODEX_TABLE_HEADER[:-1] + ".env]"]
+    lines += [f"{key} = {_toml_basic_string(value)}" for key, value in env.items()]
+    return "\n".join(lines) + "\n"
+
+
+def build_codex_block(python_path, server_path, api_path, lib_path, system=SYSTEM, python_home=None):
+    """Render the Codex CLI ``[mcp_servers.davinci-resolve]`` table (issue #39).
+
+    Codex's config is TOML, so this returns text rather than a dict.
+    """
+    entry = build_codex_entry(
+        python_path, server_path, api_path, lib_path, system=system, python_home=python_home
+    )
+    return render_codex_table(entry)
+
+
 def build_entry_for_client(client, python_path, server_path, api_path, lib_path, system=SYSTEM, python_home=None):
     """Return the server entry shaped for a specific client's config schema."""
     builders = {
@@ -542,6 +683,233 @@ class ConfigParseError(Exception):
     """
 
 
+_CODEX_MANAGED_KEY = re.compile(
+    r"""^\s*(?:command|"command"|'command'|args|"args"|'args'|env|"env"|'env')\s*="""
+)
+
+
+def _toml_open_delimiters(line):
+    """Net count of unclosed ``[``/``{`` on a line, ignoring quoted text."""
+    depth = 0
+    quote = None
+    escape = False
+    for ch in line:
+        if quote:
+            if escape:
+                escape = False
+            elif ch == "\\" and quote == '"':
+                escape = True
+            elif ch == quote:
+                quote = None
+            continue
+        if ch in "\"'":
+            quote = ch
+        elif ch in "[{":
+            depth += 1
+        elif ch in "]}":
+            depth -= 1
+        elif ch == "#":
+            break
+    return depth
+
+
+def _drop_managed_codex_keys(direct_lines):
+    """Return the table's own lines minus the command/args/env we regenerate.
+
+    Anything else in the table is the user's -- Codex's per-server knobs
+    (``startup_timeout_sec``, ``tool_timeout_sec``), comments, blank lines -- and
+    an installer has no business dropping it during an update.
+    """
+    kept = []
+    i = 0
+    while i < len(direct_lines):
+        line = direct_lines[i]
+        if not _CODEX_MANAGED_KEY.match(line):
+            kept.append(line)
+            i += 1
+            continue
+        # Skip the assignment, including a value spread over several lines.
+        depth = _toml_open_delimiters(line)
+        i += 1
+        while i < len(direct_lines) and depth > 0:
+            depth += _toml_open_delimiters(direct_lines[i])
+            i += 1
+    return kept
+
+
+def merge_codex_toml(existing_text, entry):
+    """Splice a Codex server ``entry`` into an existing config, preserving the rest.
+
+    This is a text-level merge on purpose: Python has no TOML writer in the
+    standard library, and a parse-and-rewrite would silently strip the user's
+    comments and formatting. An existing ``[mcp_servers.davinci-resolve]`` table
+    has its ``command``/``args``/``env`` replaced in place; otherwise the table is
+    appended.
+
+    Sub-tables of that entry survive untouched -- hand-written Codex configs put
+    per-tool approval modes in ``[mcp_servers.davinci-resolve.tools.<tool>]``, and
+    an installer that dropped them would quietly widen what the agent may do
+    without asking. An ``[mcp_servers.davinci-resolve.env]`` sub-table is
+    regenerated in place rather than replaced with an inline ``env``, since TOML
+    rejects a file that spells the same key both ways.
+
+    Raises :class:`ConfigParseError` when the server is defined in an inline form
+    this splice cannot safely rewrite -- appending anyway would produce a
+    duplicate key and make Codex reject the entire file.
+    """
+    lines = existing_text.splitlines()
+
+    in_mcp_servers_table = False
+    for line in lines:
+        if _CODEX_DOTTED_KEY.match(line):
+            raise ConfigParseError(
+                "davinci-resolve is already defined as a dotted key (mcp_servers.davinci-resolve)"
+            )
+        if _MCP_SERVERS_INLINE.match(line):
+            # TOML forbids extending an inline table, so no table header we
+            # append could attach to this mcp_servers definition.
+            raise ConfigParseError(
+                "mcp_servers is defined as an inline table, which cannot be extended"
+            )
+        if _MCP_SERVERS_TABLE.match(line):
+            in_mcp_servers_table = True
+            continue
+        if _TOML_TABLE_LINE.match(line):
+            in_mcp_servers_table = False
+            continue
+        if in_mcp_servers_table and _CODEX_BARE_KEY.match(line):
+            raise ConfigParseError(
+                "davinci-resolve is already defined as an inline key under [mcp_servers]"
+            )
+
+    start = next((i for i, line in enumerate(lines) if _CODEX_TABLE_LINE.match(line)), None)
+
+    if start is None:
+        prefix = existing_text
+        if prefix and not prefix.endswith("\n"):
+            prefix += "\n"
+        if prefix.strip():
+            prefix += "\n"
+        return prefix + render_codex_table(entry)
+
+    # Our region runs to the next table that is NOT one of our sub-tables.
+    end = len(lines)
+    for i in range(start + 1, len(lines)):
+        if _TOML_TABLE_LINE.match(lines[i]) and not _CODEX_CHILD_TABLE.match(lines[i]):
+            end = i
+            break
+
+    region = lines[start + 1:end]
+    first_child = next(
+        (i for i, line in enumerate(region) if _CODEX_CHILD_TABLE.match(line)), None
+    )
+    direct = region if first_child is None else region[:first_child]
+    children = [] if first_child is None else region[first_child:]
+
+    env_child = next((i for i, line in enumerate(children) if _CODEX_ENV_TABLE.match(line)), None)
+
+    rebuilt = render_codex_table(entry, env_as_subtable=env_child is not None).rstrip("\n").split("\n")
+    # Everything in the table that is not command/args/env stays: Codex's own
+    # per-server knobs (startup_timeout_sec, tool_timeout_sec, ...) plus the
+    # user's comments and blank lines.
+    rebuilt += _drop_managed_codex_keys(direct)
+
+    if env_child is not None:
+        env_end = len(children)
+        for i in range(env_child + 1, len(children)):
+            if _CODEX_CHILD_TABLE.match(children[i]):
+                env_end = i
+                break
+        env_tail = []
+        for line in reversed(children[env_child + 1:env_end]):
+            if line.strip():
+                break
+            env_tail.append("")
+        children = (
+            children[:env_child]
+            + render_codex_env_table(entry.get("env") or {}).rstrip("\n").split("\n")
+            + env_tail
+            + children[env_end:]
+        )
+
+    merged = lines[:start] + rebuilt + children + lines[end:]
+    return "\n".join(merged) + "\n"
+
+
+def write_codex_config(config_path, entry, dry_run=False):
+    """Write/merge the Codex TOML config. Returns (success, message)."""
+    config_path = Path(config_path)
+
+    try:
+        existing_text = config_path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        existing_text = ""
+    except (OSError, UnicodeDecodeError) as exc:
+        return False, (
+            f"{config_path} could not be read ({exc}). Refusing to overwrite it — "
+            f"add the entry manually (run with --manual)."
+        )
+
+    # If this interpreter can parse TOML, refuse to touch a file that is already
+    # broken: same policy as the JSON clients (issue #71) — never rewrite a config
+    # we cannot understand.
+    parse_toml = getattr(_toml_loader(), "loads", None)
+    if parse_toml and existing_text.strip():
+        try:
+            parse_toml(existing_text)
+        except Exception as exc:
+            return False, (
+                f"{config_path} exists but is not valid TOML ({exc}). Refusing to "
+                f"overwrite to avoid data loss. Add the "
+                f'"{CODEX_TABLE_HEADER}" entry manually (run with --manual).'
+            )
+
+    try:
+        merged = merge_codex_toml(existing_text, entry)
+    except ConfigParseError as exc:
+        return False, (
+            f"{config_path}: {exc}. Refusing to edit it — update that entry "
+            f"manually (run with --manual)."
+        )
+
+    if parse_toml:
+        try:
+            parse_toml(merged)
+        except Exception as exc:  # pragma: no cover - guard against a bad splice
+            return False, (
+                f"Merged Codex config would not parse ({exc}); left {config_path} "
+                f"untouched. Add the entry manually (run with --manual)."
+            )
+
+    if dry_run:
+        return True, f"Would write to {config_path}:\n{render_codex_table(entry)}"
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    if config_path.exists():
+        shutil.copy2(config_path, config_path.with_suffix(config_path.suffix + ".backup"))
+    config_path.write_text(merged, encoding="utf-8")
+    return True, str(config_path)
+
+
+def _toml_loader():
+    """Return a TOML reader module, or None on interpreters without one.
+
+    ``tomllib`` is stdlib from Python 3.11; the project floor is 3.10, so the
+    validation it enables is a bonus, not a requirement.
+    """
+    try:
+        import tomllib
+
+        return tomllib
+    except ImportError:
+        try:
+            import tomli
+
+            return tomli
+        except ImportError:
+            return None
+
+
 def _strip_jsonc(text):
     """Best-effort strip of // and /* */ comments and trailing commas.
 
@@ -676,6 +1044,12 @@ def write_client_config(client, python_path, server_path, api_path, lib_path, dr
 
     config_key = client["config_key"]
 
+    # Codex keeps its config in TOML, so it takes a text splice rather than a
+    # JSON merge (issue #39).
+    if client.get("format") == "toml":
+        entry = build_codex_entry(python_path, server_path, api_path, lib_path)
+        return write_codex_config(config_path, entry, dry_run=dry_run)
+
     # Build the server entry (some clients use a non-standard schema)
     server_entry = build_entry_for_client(client, python_path, server_path, api_path, lib_path)
 
@@ -746,8 +1120,9 @@ def generate_manual_config(python_path, server_path, api_path, lib_path):
     }}, indent=2)
     zed_fmt = json.dumps({"context_servers": {"davinci-resolve": zed_entry}}, indent=2)
     opencode_fmt = json.dumps({"mcp": {"davinci-resolve": opencode_entry}}, indent=2)
+    codex_fmt = build_codex_block(python_path, server_path, api_path, lib_path).rstrip("\n")
 
-    return standard, vscode_fmt, zed_fmt, opencode_fmt
+    return standard, vscode_fmt, zed_fmt, opencode_fmt, codex_fmt
 
 # ─── Virtual Environment ─────────────────────────────────────────────────────
 
@@ -1668,7 +2043,7 @@ def main():
 
     # Show manual config
     if show_manual:
-        standard, vscode_fmt, zed_fmt, opencode_fmt = generate_manual_config(
+        standard, vscode_fmt, zed_fmt, opencode_fmt, codex_fmt = generate_manual_config(
             python_path, server_path, api_path, lib_path
         )
         env_preview = build_server_env(python_path, api_path, lib_path)
@@ -1690,6 +2065,10 @@ def main():
         print()
         for line in opencode_fmt.split("\n"):
             print(f"    {line}")
+        print(f"\n  {cyan('Codex CLI format')} (TOML — add to ~/.codex/config.toml):")
+        print()
+        for line in codex_fmt.split("\n"):
+            print(f"    {line}")
         print(f"\n  {cyan('JetBrains IDEs')} (IntelliJ, WebStorm, PyCharm, etc.):")
         print(f"    Settings → Tools → AI Assistant → Model Context Protocol (MCP)")
         print(f"    Add server with command: {python_path} {server_path}")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.95.3",
+  "version": "2.97.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/resolve-advanced/server/aaf_probe.py

@@ -147,6 +147,109 @@ def _find_source_clip(segment, depth=0):
     return None
 
 
+def _hop_referenced_clip(mob, ref_clip):
+    """The next SourceClip down the mob chain — through the slot the REFERENCE
+    names, resolved AT the reference's offset. Returns (clip, position_adjust)
+    or None; callers accumulating physical position must add `position_adjust`
+    after adding the reference's own `start`.
+
+    🚨 A SourceClip carries `slot_id`: which slot of the referenced mob it
+    means. A GROUP CLIP (Avid multicam) is an unnamed CompositionMob with one
+    slot per camera, and hopping through the first slot returns CAMERA 1's
+    chain regardless of which camera the editor selected. Measured on a real
+    turnover (CS031, 2026-08-13): ~24 cuts linked a same-day SIBLING camera or
+    take — A015C017 built where the editor cut A082C105 — because both the
+    name chase and the source-position chase took the first-slot shortcut.
+    The wrong name is only the visible half: srcTcFrame accumulated down the
+    wrong camera's chain, so the build placed frames of the wrong source and
+    called them proven.
+
+    🚨 And the slot is only half the address. A group slot's segment can be a
+    SEQUENCE — the camera's whole tape timeline, one component per recording
+    with filler between (measured on KBP R2, 2026-08-14: A-cam slot =
+    [A008C001, filler, A008C002, filler, A009C001]; the Selector's SourceClip
+    entered it at start=123456, inside A008C002, while the first-clip shortcut
+    reported A008C001 with a source TC ~6.8s early — the reference burn-in
+    proved the picture was A008C002 @ 16:34:56:10). The reference's `start` is
+    a position ON that sequence: resolve the covered component, and return the
+    component's own sequence offset as a NEGATIVE adjust so the accumulated
+    position becomes (ref.start − component_offset) + covered_clip.start.
+
+    Falls back to the first-slot scan only when slot_id is absent or names a
+    slot the mob does not have — the pre-fix behavior, kept for tape-style
+    single-slot mobs where it was always right.
+    """
+    slots = getattr(mob, "slots", None) or []
+    sid = getattr(ref_clip, "slot_id", None)
+
+    def resolve_at_offset(segment):
+        """(clip, adjust) for this slot's content at the reference's offset."""
+        if segment is None:
+            return None
+        if type(segment).__name__ == "Sequence":
+            try:
+                offset = int(getattr(ref_clip, "start", 0) or 0)
+            except Exception:
+                offset = 0
+            # 🚨 Two offset conventions live in one structure, and only the
+            # sequence's SHAPE tells them apart — measured against FOUR
+            # independent reference burn-ins (2026-08-14):
+            #   KICK wrapper [Filler 1,  SC 118 @1 ] start=42 → truth 42−0
+            #   KICK wrapper [Filler 21, SC 150 @21] start=43 → truth 43−20
+            #   KBP group A  [SC, Filler, SC, …]     start big → truth raw
+            #   KBP group B  [Filler, SC, Filler, …] start big → truth raw
+            # A consolidate SUBCLIP WRAPPER (exactly one non-filler component,
+            # head filler in front) measures offsets from ONE FRAME INTO the
+            # head filler: shift = rawOffset − 1. A GROUP/tape sequence
+            # (multiple non-filler components) uses raw coordinates, head
+            # filler or not. This is also why the first-clip shortcut mostly
+            # worked: wrapper head fillers are usually 1 frame, making its
+            # error zero — until a 21-frame filler made it +20. The burn-in is
+            # the arbiter here, not the AAF spec — Avid writes what Avid
+            # writes. Interior fillers DO count: real dark space on a group's
+            # tape timeline.
+            comps = getattr(segment, "components", None) or []
+            non_filler = sum(1 for c in comps if type(c).__name__ != "Filler")
+            pad = (
+                1
+                if comps and type(comps[0]).__name__ == "Filler" and non_filler == 1
+                else 0
+            )
+            pos = 0
+            for comp in comps:
+                ln = _length(comp) or 0
+                eff = pos - pad
+                if eff <= offset < eff + ln:
+                    found = _find_source_clip(comp)
+                    # A filler here means this angle is dark at the offset —
+                    # no source to name; let the caller fall back or stop.
+                    return (found, -eff) if found is not None else None
+                pos += ln
+            # Offset past the sequence end — a malformed reference; the old
+            # first-clip answer is the least-wrong fallback, with no adjust.
+        found = _find_source_clip(segment)
+        return (found, 0) if found is not None else None
+
+    if sid is not None:
+        for slot in slots:
+            try:
+                if getattr(slot, "slot_id", None) == sid:
+                    resolved = resolve_at_offset(getattr(slot, "segment", None))
+                    if resolved is not None:
+                        return resolved
+                    break  # the named slot has no SourceClip at the offset — fall back
+            except Exception:
+                continue
+    for slot in slots:
+        try:
+            resolved = resolve_at_offset(getattr(slot, "segment", None))
+        except Exception:
+            continue
+        if resolved is not None:
+            return resolved
+    return None
+
+
 def _source_name(clip):
     """Best-effort human name for a SourceClip: the nearest NAMED mob it references.
 
@@ -176,14 +279,13 @@ def _source_name(clip):
         name = _usable_name(mob)
         if name:
             return name
-        nxt = None
-        for slot in getattr(mob, "slots", None) or []:
-            nxt = _find_source_clip(getattr(slot, "segment", None))
-            if nxt is not None:
-                break
-        if nxt is None:
+        # Honor the reference's slot_id — group clips have one slot per camera
+        # and the first-slot shortcut returns the wrong member (see
+        # _hop_referenced_clip).
+        hop = _hop_referenced_clip(mob, current)
+        if hop is None:
             break
-        current = nxt
+        current = hop[0]
     # No named mob anywhere in the chain — fall back to the clip's own name.
     return _usable_name(clip) or "UNKNOWN"
 
@@ -276,14 +378,15 @@ def _chase_source_position(clip):
             tc = _mob_timecode(mob)
             if tc is not None:
                 timecode = (tc[0], tc[1], tc[2], position)
-        nxt = None
-        for slot in getattr(mob, "slots", None) or []:
-            nxt = _find_source_clip(getattr(slot, "segment", None))
-            if nxt is not None:
-                break
-        if nxt is None:
+        # Same slot_id discipline as _source_name: the position/timecode chain
+        # must descend the SELECTED camera of a group clip, or srcTcFrame is
+        # the right frame of the WRONG source. The hop's adjust re-bases a
+        # sequence-slot reference onto the covered component (KBP R2 class).
+        hop = _hop_referenced_clip(mob, current)
+        if hop is None:
             break
-        current = nxt
+        position += hop[1]
+        current = hop[0]
     return position, timecode
 
 

package/resolve-advanced/server/tools/project_read.mjs

@@ -29,9 +29,17 @@ const timelineClipsSchema = z.object({ ...dbTarget, timeline: z.string().describ
 // Sm2TiTrack.Sequence (NOT Sm2Sequence_id, which is empty); the sequence carries
 // Sm2Timeline_id. Type: 0=video, 1=audio. The grade Body (DRX-format 0x81+zstd) is
 // reached via Sm2TiItem.pLmVerTable → LmVersion(HasCorrection='1').Body.
+// 🚨 mediaStart (Sm2TiItem.MediaStartTime) is the MEDIA FILE's start time in
+// seconds — NOT the item's in-point. Reading it as the in-point produced two
+// phantom conform bugs in a row (CS031 retractions). The in-point is the "In"
+// column: file-relative source frames, calibrated frame-EXACT against a real
+// turnover's AAF ground truth (A005C004 run: 36069/8863/8919/12804, through-
+// edit continuity intact). Emitted as sourceIn.
 const TIMELINE_CLIPS_SQL = `
  SELECT i.Name AS name, t.Type AS trackType, i.Start AS start, i.Duration AS duration,
- i.MediaReelNumber AS reel, i.MediaStartTime AS mediaStart, i.Sm2TiTrack_id AS trackId,
+ i.MediaReelNumber AS reel, i.MediaStartTime AS mediaStart, i."In" AS sourceIn,
+ i.MediaFilePath AS mediaPath,
+ i.Sm2TiTrack_id AS trackId,
  lower(hex(v.Body)) AS gradeBody
  FROM Sm2TiItem i
  JOIN Sm2TiTrack t ON i.Sm2TiTrack_id = t.Sm2TiTrack_id
@@ -73,6 +81,28 @@ function count(db, t) {
 
 /** Read a timeline's clips from a Project.db (read-only). Shared by the
  * timeline_clips action + the color_trace tool. trackType: 'video'|'audio'|'all'. */
+/**
+ * Sm2TiItem."In" — the item's file-relative source in-point — arrives in TWO
+ * encodings in one 'character varying' column (both measured on Resolve
+ * 19.1.3 disk DBs, same show):
+ *   - a plain decimal string: '48', '36069' (older/edited rows)
+ *   - a 16-hex-char little-endian DOUBLE of frames/1000: '000000bb7493a83f'
+ *     = 0.048 → 48 (freshly-appended rows)
+ * Calibrated against AAF ground truth on both encodings. Anything else is
+ * null — an unreadable in-point must read as absent, not as 0.
+ */
+function decodeItemIn(v) {
+  if (v == null || v === '') return null;
+  // Two shapes measured on Resolve 19.1.3 disk DBs (same show, different
+  // projects): a plain decimal ('48', '36069'), and a pipe-joined composite
+  // ('48|000000bb7493a83f') whose FIRST field is the frame count — the hex
+  // tail is a packed double with its own (unpinned) meaning and is ignored.
+  // The pipe in the value is also why a naive `sqlite3` CLI dump appears to
+  // grow an extra column. Anything else reads as ABSENT, never as 0.
+  const head = String(v).split('|', 1)[0];
+  return /^-?\d+(\.\d+)?$/.test(head) ? Number(head) : null;
+}
+
 export function readTimelineClips(dbPath, timeline, trackType = 'all', includeGrade = false) {
   const db = openGuarded(dbPath, { writable: false });
   try {
@@ -81,7 +111,10 @@ export function readTimelineClips(dbPath, timeline, trackType = 'all', includeGr
     else if (trackType === 'audio') rows = rows.filter((r) => r.trackType !== 0);
     rows.sort((a, b) => a.trackType - b.trackType || Number(a.start) - Number(b.start));
     // grade Body is large + only needed for ColorTrace — strip it by default to avoid bloat.
-    if (!includeGrade) for (const r of rows) delete r.gradeBody;
+    for (const r of rows) {
+      if (!includeGrade) delete r.gradeBody;
+      r.sourceIn = decodeItemIn(r.sourceIn);
+    }
     return rows;
   } finally {
     db.close();