davinci-resolve-mcp 2.73.0 → 2.73.2

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.73.2
+
+Two honesty fixes in the conform path, both found by running a real 83-minute
+Avid AAF turnover end to end. Neither adds tool surface; `detect_missing_media`
+gains two additive response fields.
+
+### Fixed
+
+- **`detect_missing_media` counted an unknown item as a present one.** A timeline
+  item with no media pool item has no file path and no offline marker, so it fell
+  through to `present` — absence of information reported as presence. An AAF
+  imported with `importSourceClips=false` yields 882 such items, and the probe
+  answered `present_count: 882, missing_count: 0` while every one of them returned
+  `None` from `GetMediaPoolItem()`. The payload contradicted itself: the diagnosis
+  already said `unique_media_pool_item_count: 0`.
+
+  Those items now report under `unlinked` / `unlinked_count` and never inflate
+  `present_count`. They are deliberately **not** folded into `missing`: those rows
+  drive relink plans keyed on `media_pool_item_id`, and there is no pool item here
+  to relink. When a timeline is entirely unlinked the diagnosis says so, instead of
+  "No offline media detected" — technically true and completely misleading.
+
+- **The "Resolve created no timeline" remediation named the wrong fix.** It advised
+  converting the file to FCP7 XML / FCPXML. The far more common cause is that
+  `importSourceClips` defaults to `True`, so Resolve tries to pull in the sequence's
+  source clips and fails the entire import when those paths do not resolve — the
+  normal state of a turnover, whose paths belong to the offline editor.
+  `import_source_clips=false` lands the timeline offline and now leads the
+  remediation. Note `sourceClipsPath` does not rescue it: Resolve matches source
+  clips by the filenames recorded in the sequence, so an AAF referencing Avid MXF
+  finds nothing in a folder of differently-named finishing media.
+
+## What's New in v2.73.1
+
+Packaging fix. The npm package shipped the AAF reader's Node half without its
+Python half, so offline AAF preview could never have worked from an npm install.
+
+### Fixed
+
+- **`aaf_probe.py` was missing from the published npm package.** The `files`
+  allowlist was written in v2.58.0 as `resolve-advanced/server/**/*.mjs`, and
+  when `aaf_probe.py` landed in v2.59.0 the allowlist was not extended. `aaf.mjs`
+  shipped and shelled out to a file that did not exist on disk, so every
+  `parse_interchange` / `list_sequences` call against a `.aaf` failed for
+  npm-installed users. Repository clones were unaffected, which is why it
+  survived a year of releases unnoticed.
+
+  The failure was at least loud rather than a fake parse — but its remediation
+  was actively misleading. The probe exited 2 (`can't open file …aaf_probe.py`),
+  which fell through to the generic branch and appended "Install the offline AAF
+  reader (`pip install pyaaf2`)". Installing pyaaf2 cannot fix a file that was
+  never packaged, so the message sent anyone who hit it down a dead end.
+
+  This means the v2.73.0 multi-layer AAF fix did not reach npm users at all;
+  2.73.1 is what actually delivers it.
+
 ## What's New in v2.73.0
 
 The offline AAF reader could not read a multi-layer Avid timeline, and said so

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.73.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.73.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)

package/install.py

@@ -36,7 +36,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.73.0"
+VERSION = "2.73.2"
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.73.0",
+  "version": "2.73.2",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",
@@ -37,6 +37,7 @@
     "bin/",
     "src/**/*.py",
     "resolve-advanced/server/**/*.mjs",
+    "resolve-advanced/server/**/*.py",
     "resolve-advanced/vendor/**",
     "resolve-advanced/package.json",
     "resolve-advanced/README.md",

package/resolve-advanced/server/aaf_probe.py

@@ -0,0 +1,457 @@
+#!/usr/bin/env python3
+"""
+aaf_probe — offline AAF (.aaf) reader for the editorial `parse_interchange` /
+`list_sequences` picker+preview.
+
+AAF is a binary Structured-Storage container; there is no pure-JS reader worth
+trusting, so the Node server shells out to this helper, which uses the pure-Python
+`aaf2` library (pyaaf2). It emits ONE JSON object on stdout:
+
+    {
+      "ok": true,
+      "sequences": [
+        { "id": <mob-id str>, "name": <str>, "eventCount": <int>,
+          "unhandled": { "<ComponentClass>": <int>, ... },
+          "events": [ {normalized-event}, ... ] }
+      ]
+    }
+
+Normalized event shape mirrors resolve-advanced/server/editorial.mjs `evt()`:
+    { index, track, source, srcIn, srcOut, recIn, recOut, speed, reverse, transition, fps }
+
+Honest-refuse discipline (no fake parses):
+  * exit 3  → pyaaf2 not installed        (stderr: AAF_PROBE_NO_PYAAF2)
+  * exit 4  → file unreadable / not an AAF (stderr: AAF_PROBE_UNREADABLE: <detail>)
+  * exit 2  → bad invocation
+Per-sequence event extraction is best-effort and defensive: if a component can't
+be decoded we still report the sequence with its clip count — we never fabricate.
+
+`unhandled` is the teeth behind that promise. A structural miss (a component class
+this walker does not model) used to be swallowed silently, so a whole multi-layer
+timeline could come back as `ok:true` with `eventCount: 0` — indistinguishable from
+an genuinely empty sequence, and worse than an honest refusal because downstream
+consumers gate on `ok`. Every component we skip is now counted by class name and
+reported per sequence, so a miss is VISIBLE without changing the exit-code contract.
+
+Segment model (Avid Media Composer picture turnovers):
+  * NestedScope  — a multi-layer video track. Its `.slots` are the layers (V1..Vn);
+                   it has NO `.components`. Layers are PARALLEL, so each layer's
+                   record position restarts at 0.
+  * Sequence     — ordered `.components`, laid end to end.
+  * OperationGroup — effect wrapper. Its `.segments` are the effect INPUTS, and the
+                   primary input is usually a nested Sequence (not a bare SourceClip).
+  * Selector     — an enabled/disabled layer variant; the live one is `Selected`.
+  * ScopeReference — "show the NestedScope layer beneath me": real record time, no
+                   clip of this layer's own. Treated as a gap, like Filler.
+"""
+
+import json
+import os
+import sys
+
+
+def _fps_from_edit_rate(edit_rate):
+    try:
+        return round(float(edit_rate), 6)
+    except Exception:
+        return None
+
+
+# How far to chase the mob reference chain looking for a named mob (see _source_name).
+_MAX_MOB_CHASE = 8
+
+
+def _usable_name(obj):
+    """A real name, or None. pyaaf2 returns the CLASS NAME for an unset `.name`, so a
+    value equal to the object's type name means "absent", not a source called SourceClip."""
+    try:
+        v = getattr(obj, "name", None)
+    except Exception:
+        return None
+    if not v:
+        return None
+    text = str(v).strip()
+    if not text or text == type(obj).__name__:
+        return None
+    return text
+
+
+def _find_source_clip(segment, depth=0):
+    """First SourceClip inside an arbitrary segment tree (bounded)."""
+    if segment is None or depth > 8:
+        return None
+    cls = type(segment).__name__
+    if cls == "SourceClip":
+        return segment
+    if cls == "Selector":
+        return _find_source_clip(_selector_selected(segment), depth + 1)
+    if cls == "Sequence":
+        children = getattr(segment, "components", None) or []
+    elif cls == "OperationGroup":
+        children = getattr(segment, "segments", None) or []
+    elif cls == "NestedScope":
+        children = _nested_layers(segment)
+    else:
+        return None
+    for child in children:
+        found = _find_source_clip(child, depth + 1)
+        if found is not None:
+            return found
+    return None
+
+
+def _source_name(clip):
+    """Best-effort human name for a SourceClip: the nearest NAMED mob it references.
+
+    Avid does not point a timeline SourceClip straight at a MasterMob. Subclips, group
+    clips and motion-effect sources go through one or more UNNAMED intermediate
+    CompositionMobs, so stopping at `clip.mob.name` yields nothing for the majority of
+    a real turnover's clips. Chase the reference chain — mob → its slot's SourceClip →
+    that clip's mob — until a mob actually carries a name (typically the MasterMob, e.g.
+    "A001C001_240101_AB01.new.01"). Bounded and cycle-guarded.
+    """
+    current = clip
+    seen = set()
+    for _ in range(_MAX_MOB_CHASE):
+        try:
+            mob = getattr(current, "mob", None)
+        except Exception:
+            mob = None
+        if mob is None:
+            break
+        try:
+            key = str(getattr(mob, "mob_id", "") or id(mob))
+        except Exception:
+            key = str(id(mob))
+        if key in seen:
+            break  # reference cycle — stop rather than spin
+        seen.add(key)
+        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:
+            break
+        current = nxt
+    # No named mob anywhere in the chain — fall back to the clip's own name.
+    return _usable_name(clip) or "UNKNOWN"
+
+
+def _emit_source_clip(clip, *, index, track, rec, fps, transition=None):
+    """Turn a SourceClip into a normalized event. Returns (event, length)."""
+    try:
+        length = int(getattr(clip, "length", 0) or 0)
+    except Exception:
+        length = 0
+    try:
+        start = int(getattr(clip, "start", 0) or 0)
+    except Exception:
+        start = 0
+    event = {
+        "index": index,
+        "track": track,
+        "source": _source_name(clip),
+        "srcIn": start,
+        "srcOut": start + length,
+        "recIn": rec,
+        "recOut": rec + length,
+        "speed": 100,
+        "reverse": False,
+        "transition": transition,
+        "fps": fps,
+    }
+    return event, length
+
+
+# Depth guard: AAF nesting is a graph and a malformed file could cycle. Real Avid
+# turnovers nest ~4 deep (NestedScope > Sequence > Selector > OperationGroup > Sequence).
+_MAX_DEPTH = 24
+
+
+def _length(obj):
+    try:
+        return int(getattr(obj, "length", 0) or 0)
+    except Exception:
+        return 0
+
+
+def _note_unhandled(state, cls):
+    """Record a component class we could not turn into events. See module docstring."""
+    state["unhandled"][cls] = state["unhandled"].get(cls, 0) + 1
+
+
+def _nested_layers(scope):
+    """The parallel layers of a NestedScope.
+
+    pyaaf2 hands back the layer Segments directly for this class, but tolerate a
+    slot-like wrapper (`.segment`) too so we work across pyaaf2 versions.
+    """
+    layers = []
+    for item in getattr(scope, "slots", []) or []:
+        inner = getattr(item, "segment", None)
+        layers.append(inner if inner is not None else item)
+    return layers
+
+
+def _selector_selected(comp):
+    """The live variant of a Selector (Avid enabled/disabled layer variants).
+
+    This is the AAF `Selected` PROPERTY — pyaaf2 does not expose it as a `.selected`
+    python attribute, so read it via getvalue()/[] first and only then fall back.
+    """
+    for getter in (
+        lambda c: c.getvalue("Selected"),
+        lambda c: c["Selected"].value,
+        lambda c: getattr(c, "selected", None),
+    ):
+        try:
+            v = getter(comp)
+            if v is not None:
+                return v
+        except Exception:
+            pass
+    return None
+
+
+def _operation_name(comp):
+    try:
+        return str(getattr(getattr(comp, "operation", None), "name", "") or "")
+    except Exception:
+        return ""
+
+
+def _walk_segment(segment, *, track, fps, rec, state, depth=0, transition=None):
+    """
+    Emit normalized events for ONE segment placed at record position `rec`.
+
+    Appends to `state["events"]` (indices from the monotonic `state["idx"]`) and
+    counts anything it cannot model into `state["unhandled"]`.
+
+    Returns the number of RECORD frames this segment occupies, so a caller laying
+    components end to end can advance. Container classes return their own declared
+    length rather than the sum of what we managed to decode — a partial decode must
+    not silently slide every later clip earlier on the timeline.
+    """
+    cls = type(segment).__name__
+    declared = _length(segment)
+
+    if depth > _MAX_DEPTH:
+        _note_unhandled(state, cls)
+        return declared
+
+    if cls == "SourceClip":
+        ev, length = _emit_source_clip(
+            segment, index=state["idx"], track=track, rec=rec, fps=fps, transition=transition
+        )
+        state["events"].append(ev)
+        state["idx"] += 1
+        return length
+
+    if cls in ("Filler", "ScopeReference"):
+        # Filler = a real gap. ScopeReference = "the NestedScope layer beneath shows
+        # through here" — real record time, but no clip of THIS layer's own.
+        return declared
+
+    if cls == "Sequence":
+        return _walk_components(segment, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+
+    if cls == "NestedScope":
+        # Layers are parallel in time: every one starts at this segment's own rec.
+        for layer in _nested_layers(segment):
+            _walk_segment(layer, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+        return declared
+
+    if cls == "Selector":
+        selected = _selector_selected(segment)
+        if selected is None:
+            _note_unhandled(state, cls)
+        else:
+            _walk_segment(selected, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+        return declared
+
+    if cls == "OperationGroup":
+        # Effect wrapper (retime, paint, resize, blend, matte key...). Its `.segments`
+        # are the effect INPUTS, and the primary is usually a nested Sequence, NOT a
+        # bare SourceClip — only descending to a direct SourceClip finds nothing.
+        #
+        # EVERY input is walked, not just the primary: an SBlend B-side or a matte
+        # key's fill/key are real referenced media that a conform has to relink, and
+        # dropping them is the same data loss this walker exists to prevent. They share
+        # the primary's record span (that is what a blend IS), so they intentionally
+        # overlap it on the same track label. Callers already cannot assume events are
+        # non-overlapping — parallel NestedScope layers overlap by construction.
+        before = len(state["events"])
+        for inp in getattr(segment, "segments", None) or []:
+            _walk_segment(inp, track=track, fps=fps, rec=rec, state=state, depth=depth + 1, transition=transition)
+        op_name = _operation_name(segment)
+        if op_name and ("speed" in op_name.lower() or "motion" in op_name.lower()):
+            # We can detect that a retime is present but not reliably its ratio
+            # offline; flag it honestly rather than fake a speed number.
+            for ev in state["events"][before:]:
+                ev["effect"] = op_name
+        return declared
+
+    # Unknown component — advance by its declared length, don't fake an event, and
+    # make the miss loud so it cannot masquerade as an empty timeline.
+    _note_unhandled(state, cls)
+    return declared
+
+
+def _walk_components(sequence, *, track, fps, rec, state, depth, transition=None):
+    """Lay a Sequence's components end to end. Returns the record length consumed."""
+    start = rec
+    pending_transition = transition
+    components = getattr(sequence, "components", None)
+    if components is None:
+        components = [sequence]
+    for comp in components:
+        cls = type(comp).__name__
+        try:
+            if cls == "Transition":
+                # A transition overlaps its neighbours; it does not advance rec itself.
+                pending_transition = {"type": "dissolve", "duration": _length(comp)}
+                continue
+            rec += _walk_segment(
+                comp, track=track, fps=fps, rec=rec, state=state, depth=depth, transition=pending_transition
+            )
+            pending_transition = None
+        except Exception:
+            # Never let one bad component abort the whole sequence — but say so.
+            _note_unhandled(state, cls)
+            pending_transition = None
+            continue
+    return rec - start
+
+
+def _walk_slot(segment, *, prefix, fps, state):
+    """
+    Walk one mob slot's top-level segment into `state`.
+
+    A NestedScope slot is a multi-layer track: each layer gets its own numbered label
+    (V1..Vn / A1..An) and restarts at record 0, because layers are parallel, not
+    sequential. A plain (single-layer) slot keeps the flat "V"/"A" label.
+    """
+    if type(segment).__name__ == "NestedScope":
+        for n, layer in enumerate(_nested_layers(segment), start=1):
+            _walk_segment(layer, track=f"{prefix}{n}", fps=fps, rec=0, state=state, depth=1)
+        return
+    _walk_segment(segment, track=prefix, fps=fps, rec=0, state=state, depth=0)
+
+
+# Slot media kinds that carry no editorial cuts. Matched on MEDIA KIND, not on the
+# segment's class name: Avid wraps timecode slots in a Pulldown (segment class
+# "Pulldown", media_kind "Timecode"), so a class-name-only skip let them through and
+# they polluted both the events and the unhandled counter.
+_NON_EDITORIAL_KINDS = frozenset(
+    {"timecode", "edgecode", "descriptivemetadata", "soundmastertrack"}
+)
+
+
+def _norm_kind(value):
+    try:
+        return "".join(str(value or "").split()).lower()
+    except Exception:
+        return ""
+
+
+def _slot_media_kind(slot):
+    """Media kind of a slot, falling back to its segment's."""
+    for owner in (slot, getattr(slot, "segment", None)):
+        kind = _norm_kind(getattr(owner, "media_kind", None))
+        if kind:
+            return kind
+    return ""
+
+
+def _is_editorial_slot(slot):
+    return _slot_media_kind(slot) not in _NON_EDITORIAL_KINDS
+
+
+def _media_kind_to_track(slot):
+    return "A" if _slot_media_kind(slot).startswith("sound") else "V"
+
+
+def probe(path):
+    import aaf2
+
+    sequences = []
+    with aaf2.open(path, "r") as f:
+        toplevel = list(f.content.toplevel())
+        # Fall back to all composition mobs if no explicit top-level usage is set.
+        if not toplevel:
+            try:
+                toplevel = [m for m in f.content.mobs if type(m).__name__ == "CompositionMob"]
+            except Exception:
+                toplevel = []
+        for mob in toplevel:
+            try:
+                mob_id = str(getattr(mob, "mob_id", "") or "")
+            except Exception:
+                mob_id = ""
+            name = None
+            try:
+                name = getattr(mob, "name", None)
+            except Exception:
+                name = None
+            # `idx` is monotonic across the WHOLE mob, every slot and every nested layer.
+            state = {"idx": 1, "events": [], "unhandled": {}}
+            for slot in getattr(mob, "slots", []) or []:
+                seg = getattr(slot, "segment", None)
+                if seg is None:
+                    continue
+                # Skip non-editorial slots by MEDIA KIND (timecode/edgecode/descriptive
+                # metadata/sound master) — see _NON_EDITORIAL_KINDS.
+                if not _is_editorial_slot(slot):
+                    continue
+                _walk_slot(
+                    seg,
+                    prefix=_media_kind_to_track(slot),
+                    fps=_fps_from_edit_rate(getattr(slot, "edit_rate", None)),
+                    state=state,
+                )
+            events = state["events"]
+            sequences.append(
+                {
+                    "id": mob_id or (str(name) if name else f"seq{len(sequences) + 1}"),
+                    "name": str(name) if name else f"Sequence {len(sequences) + 1}",
+                    "eventCount": len(events),
+                    # Component classes we could not model, by name+count. Empty {} means
+                    # a structurally complete read; non-empty means events are INCOMPLETE.
+                    "unhandled": dict(sorted(state["unhandled"].items())),
+                    "events": events,
+                }
+            )
+    return sequences
+
+
+def main(argv):
+    if len(argv) < 2:
+        sys.stderr.write("AAF_PROBE_USAGE: aaf_probe.py <path.aaf>\n")
+        return 2
+    path = argv[1]
+    if not os.path.exists(path):
+        sys.stderr.write(f"AAF_PROBE_UNREADABLE: no such file: {path}\n")
+        return 4
+    try:
+        import aaf2  # noqa: F401
+    except Exception:
+        sys.stderr.write(
+            "AAF_PROBE_NO_PYAAF2: the pure-Python 'aaf2' package (pyaaf2) is not installed\n"
+        )
+        return 3
+    try:
+        sequences = probe(path)
+    except Exception as e:  # unreadable / not an AAF / decode failure
+        sys.stderr.write(f"AAF_PROBE_UNREADABLE: {type(e).__name__}: {e}\n")
+        return 4
+    json.dump({"ok": True, "sequences": sequences}, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/src/granular/common.py

@@ -85,7 +85,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.73.0"
+VERSION = "2.73.2"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.73.0"
+VERSION = "2.73.2"
 
 import base64
 import os
@@ -6048,9 +6048,23 @@ def _import_timeline_checked(proj, mp, p: Dict[str, Any]):
                     imported = t
         if not imported:
             if is_binary:
+                # importSourceClips defaults to True, so Resolve tries to pull in the
+                # sequence's source clips during import — and when those paths do not
+                # resolve it fails the whole import rather than creating an offline
+                # timeline. That is the normal case for a turnover (the paths belong
+                # to the offline editor), so it is by far the most common reason a
+                # valid AAF "creates no timeline", and the flag fixes it. Naming a
+                # format conversion first sent people down a much longer road than
+                # the one-flag retry that actually works. Note sourceClipsPath does
+                # NOT rescue it: Resolve matches source clips by the filenames
+                # recorded in the sequence, so an AAF referencing Avid MXF finds
+                # nothing in a folder of differently-named finishing media.
                 remediation = (
-                    f"Resolve created no timeline from this {ext}. Verify it exports/opens in "
-                    "Resolve directly, or convert to FCP7 XML / FCPXML upstream and import that."
+                    f"Resolve created no timeline from this {ext}. Most often the source clips "
+                    "could not be resolved: retry with import_source_clips=false to land the "
+                    "timeline offline, then add the media to the media pool and relink. "
+                    "Otherwise verify it exports/opens in Resolve directly, or convert to "
+                    "FCP7 XML / FCPXML upstream and import that."
                 )
             elif sanitize:
                 remediation = None
@@ -6583,6 +6597,7 @@ def _missing_media_diagnosis(missing_rows: List[Dict[str, Any]]) -> Dict[str, An
 def _detect_missing_media_from_snapshot(snapshot: Dict[str, Any]):
     missing = []
     present = []
+    unlinked = []
     for track_type, type_payload in (snapshot.get("tracks") or {}).items():
         for track in type_payload.get("tracks", []):
             for item in track.get("items", []):
@@ -6603,13 +6618,40 @@ def _detect_missing_media_from_snapshot(snapshot: Dict[str, Any]):
                 }
                 if is_missing:
                     missing.append(row)
+                elif not file_path and not item.get("media_pool_item_id"):
+                    # No path AND no media pool item: the timeline item has nothing
+                    # behind it at all. It is not "present" — we simply know nothing
+                    # about it — and counting it as present is how an entirely
+                    # offline timeline reported full coverage (an AAF imported with
+                    # importSourceClips=false yields 882 such items and used to
+                    # report present_count 882 / missing_count 0, while every one of
+                    # them returned None from GetMediaPoolItem()).
+                    #
+                    # Kept out of `missing` deliberately: those rows drive relink
+                    # plans keyed on media_pool_item_id, and there is no pool item
+                    # here to relink. This is a third state, so it gets its own.
+                    unlinked.append(row)
                 else:
                     present.append(row)
     diagnosis = _missing_media_diagnosis(missing)
+    if unlinked and not missing:
+        # Nothing to relink, so the generic "no offline media detected" advice
+        # would send the caller away satisfied from a timeline with no media.
+        diagnosis = dict(diagnosis)
+        diagnosis["primary_cause"] = "no_media_pool_items"
+        diagnosis["recommended_next_step"] = (
+            f"{len(unlinked)} timeline items have no media pool item at all — the timeline was "
+            "imported without its source clips. Add the media to the media pool, then relink; "
+            "there is nothing here for a path-based relink to act on."
+        )
     return {
         "missing": missing,
         "present_count": len(present),
         "missing_count": len(missing),
+        # Timeline items with neither a file path nor a media pool item. Never
+        # folded into present_count — see above.
+        "unlinked": unlinked,
+        "unlinked_count": len(unlinked),
         "diagnosis": diagnosis,
     }