davinci-resolve-mcp 2.82.1 → 2.86.2

package/src/utils/api_truth.py

@@ -1008,7 +1008,8 @@ API_TRUTH: List[Dict[str, Any]] = [
                        "a normalised position vector (param 17). Exposed as "
                        "project_db list_subtitle_styles / set_subtitle_style "
                        "(font family/size/weight/italic + position). Confirmed "
-                       "live on Studio 19.1.3 (2026-08-06): Resolve opens a patched track "
+                       "live on BOTH editions 2026-08-06 — Studio 19.1.3 and "
+                       "free 21.0.3, identical behaviour: Resolve opens a patched track "
                        "and re-serialises it back to its own zstd form with the "
                        "patched values intact, so it genuinely parses the write. "
                        "Caveats: whole-TRACK style not per-caption, project must "
@@ -1070,13 +1071,29 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "NOT refute the 21.0.0 record: if the bridge resolves any name "
                    "known to the RemoteObject method table rather than literally any "
                    "string, an invented name is correctly rejected on both builds and "
-                   "the probe never exercised the failing case. Re-running the probe "
-                   "with those five real names is what would settle it; until then, "
-                   "assume fabrication is possible.",
+                   "the probe never exercised the failing case. "
+                   "PARTLY SETTLED 2026-08-06 on Studio 19.1.3.7, DIRECT connection "
+                   "(not the bridge): the five real borrowed names were re-run as the "
+                   "entry asked, across Resolve, ProjectManager, Project, MediaPool, "
+                   "Timeline, Folder and TimelineItem — 42 checks. Every one returned "
+                   "getattr-callable False and dir()-absent, agreeing in all 42 cases, "
+                   "exactly like the invented control. So NO fabrication on the direct "
+                   "path on this build, and the borrowed-name case the 21.0.2.4 probe "
+                   "missed is now covered there. What the same run DID establish is "
+                   "narrower and worse than expected: bare hasattr() returns True for "
+                   "EVERY name on every object — real, borrowed or invented — while "
+                   "getattr returns None. hasattr alone is therefore not a weak probe, "
+                   "it is a constant True and carries no information at all. "
+                   "STILL OPEN: the 21.0.0 record was against the BRIDGE, which this "
+                   "run did not exercise, so bridge-side fabrication remains untested "
+                   "and the recommendation below stands unchanged.",
         "recommended": "Use dir(obj) membership for capability probes. It is correct "
                        "on every build measured, and it is the only form not affected "
-                       "by whichever way this resolves. server._has_method uses "
-                       "hasattr/getattr and so may over-report on builds where "
+                       "by whichever way this resolves. NEVER use bare hasattr(): it "
+                       "is a constant True on Resolve objects and cannot distinguish "
+                       "anything. server._has_method uses callable(getattr(...)), "
+                       "which agreed with dir() in all 42 direct-path checks on "
+                       "19.1.3.7 but may still over-report on a bridge build where "
                        "fabrication is live — that is the case _requires_method gates "
                        "guard, so it matters most exactly where it is least tested. "
                        "Calling a fabricated method typically returns None/False with "
@@ -1444,7 +1461,12 @@ API_TRUTH: List[Dict[str, Any]] = [
                    "are all marker-only and all refused. Five names overlap both "
                    "palettes (Blue, Green, Yellow, Pink, Purple), which is why the "
                    "decoy survives: reasoning from the marker constants scores 5 of "
-                   "16 and looks like the right vocabulary with a few gaps.",
+                   "16 and looks like the right vocabulary with a few gaps. The "
+                   "reporter's field experience sharpens this — the trap is not that "
+                   "a decoy vocabulary exists, it is that the decoy HALF-WORKS. "
+                   "Intermittent successes read as an unreliable API rather than as "
+                   "a wrong vocabulary, so the wrong conclusion is the natural one; "
+                   "a clean 0-for-8 would have exposed the mechanism immediately.",
         "recommended": "Pass only the 16 clip-colour names; on False, treat it as an "
                        "invalid name rather than an item/lock/page problem. The set "
                        "is pinned in utils/clip_colors.py and named in the refusal "

package/src/utils/edit_engine.py

@@ -1742,6 +1742,12 @@ def plan_transcript_tighten(
         plan.get("keep_ranges") or [],
         source_duration_seconds=float(duration) if isinstance(duration, (int, float)) and duration else None,
     )
+    # The class this planner is structurally blind to. Its false-start heuristic
+    # only sees restarts the transcript actually reports; an immediate re-read is
+    # emitted ONCE with the pause and second take absorbed into one word, so the
+    # plan cannot propose removing what it was never told happened (issue #125).
+    from src.utils import swallowed_retakes as _swallowed
+    plan["possible_swallowed_retakes"] = _swallowed.swallowed_retake_report(words)
     return plan
 
 

package/src/utils/resolve_bridge_client.py

@@ -55,8 +55,10 @@ logger = logging.getLogger("resolve-mcp.bridge-client")
 DEFAULT_CONFIG_PATH = Path.home() / ".config/davinci-resolve-mcp/bridge.json"
 #: Env override, so a caller can point at a non-default bridge without editing code.
 ENV_CONFIG_PATH = "DAVINCI_RESOLVE_BRIDGE_CONFIG"
-#: Opt-in. Absent means "do not try the bridge", so nothing changes for existing
-#: installs until someone asks for it.
+#: Forces the bridge: it becomes the only transport tried, so its faults surface
+#: directly. Absent does NOT mean "never try the bridge" — `connect_resolve` falls
+#: back to it when a direct transport yields nothing, which is what lets the free
+#: edition work with no configuration beyond starting the in-Resolve script.
 ENV_ENABLE = "DAVINCI_RESOLVE_BRIDGE"
 
 #: Operations this client cannot work without. The in-Resolve script is a *copy*
@@ -390,7 +392,8 @@ def connect(*, timeout: float = DEFAULT_TIMEOUT_SECONDS, require_enabled: bool =
     """
     if require_enabled and not bridge_enabled():
         raise BridgeUnavailable(
-            f"The in-app bridge is opt-in: set {ENV_ENABLE}=1 to use it."
+            f"This caller required an explicitly-enabled bridge: set {ENV_ENABLE}=1, "
+            "or call connect(require_enabled=False) to use the bridge as a fallback."
         )
     path = config_path()
     try:

package/src/utils/resolve_connection.py

@@ -37,20 +37,51 @@ def _network_timeout():
     return timeout
 
 
+def _try_bridge_fallback():
+    """Last-resort bridge attempt after a direct transport has already failed.
+
+    Returns a proxy, or None when there is no bridge to reach. Unlike the
+    explicitly-requested path this swallows `BridgeUnavailable`: nobody asked for
+    the bridge, so "no bridge running" is simply "no Resolve" — the same answer
+    the caller got before this fallback existed.
+    """
+    if bridge_client is None:
+        return None
+    try:
+        proxy = bridge_client.connect(require_enabled=False)
+    except bridge_client.BridgeUnavailable as exc:
+        logger.debug("no in-app bridge to fall back to: %s", exc)
+        return None
+    logger.info(
+        "external scripting unavailable; automatically using the in-app bridge "
+        "(set %s=1 to require it and surface bridge faults directly)",
+        bridge_client.ENV_ENABLE,
+    )
+    return proxy
+
+
 def connect_resolve(dvr_script):
     """Create a Resolve handle. Three modes, tried in order of directness.
 
-    1. **Bridge** (opt-in, `DAVINCI_RESOLVE_BRIDGE=1`) — a proxy over the
+    1. **Bridge** (forced, `DAVINCI_RESOLVE_BRIDGE=1`) — a proxy over the
        authenticated loopback bridge running inside Resolve. This is the only
        mode that works on the **free edition**, whose external scripting API
-       refuses foreign processes. Tried first when enabled, because if a user has
-       asked for it, silently using a different transport would hide a broken
-       bridge.
+       refuses foreign processes. Tried first *and exclusively* when the env var
+       is set, because if a user has asked for it, silently using a different
+       transport would hide a broken bridge.
     2. **Network** (`RESOLVE_SCRIPT_HOST`) — Studio's remote scripting.
     3. **Local** — Studio's local scripting. The default.
 
-    `dvr_script` may be None in bridge mode: the bridge does not need Blackmagic's
-    module at all, which is precisely why it reaches editions the module cannot.
+    If a direct transport yields nothing, the bridge is tried once more as a
+    **fallback**, without the env var. That cannot mask a broken bridge the way
+    an unconditional bridge-first order would: it only runs on a path that has
+    already failed, so the env var stays meaningful as "require the bridge and
+    tell me when it breaks" while the free edition works with no configuration
+    beyond starting the in-Resolve script.
+
+    `dvr_script` may be None: the bridge does not need Blackmagic's module at
+    all, which is precisely why it reaches editions the module cannot — so a
+    missing module is a reason to try the bridge, not to give up.
     """
     if bridge_client is not None and bridge_client.bridge_enabled():
         try:
@@ -60,12 +91,16 @@ def connect_resolve(dvr_script):
             # falling through to a transport the user did not ask for.
             logger.error("in-app bridge requested but unavailable: %s", exc)
             raise
-    if dvr_script is None:
-        return None
-    host = os.environ.get("RESOLVE_SCRIPT_HOST")
-    if host:
-        return dvr_script.scriptapp("Resolve", host, _network_timeout())
-    return dvr_script.scriptapp("Resolve")
+    resolve = None
+    if dvr_script is not None:
+        host = os.environ.get("RESOLVE_SCRIPT_HOST")
+        if host:
+            resolve = dvr_script.scriptapp("Resolve", host, _network_timeout())
+        else:
+            resolve = dvr_script.scriptapp("Resolve")
+    if resolve is not None:
+        return resolve
+    return _try_bridge_fallback()
 
 
 def initialize_resolve():

package/src/utils/resolve_versions.py

@@ -0,0 +1,338 @@
+"""Resolve build comparison, and the API surfaces that are gated on a build.
+
+The scripting API changes per **patch** release, not per major one. "Resolve 21"
+is not a fine enough label to route on: `GetFairlightPresets` exists on 20.2.2
+and not on 19.1.3, and issue #131 reports three surfaces that appear only in
+21.0.4. An agent given the same guidance regardless of the build it is connected
+to will confidently describe a method that is not there — which is exactly the
+report in issue #132.
+
+Two separate questions live here, and conflating them is the trap:
+
+1. **Does this build have the method?** Answered from `VERSION_GATES` below,
+   which records only gates we can point at evidence for.
+2. **Was a recorded quirk measured on a build like mine?** Answered by comparing
+   an `api_truth` entry's stamp against the live build. A fact measured on
+   19.1.3.7 is a *prior* on 21.0.4, not a finding.
+
+Neither question is answered by guessing. A symbol absent from `VERSION_GATES`
+returns `unknown`, never `available` — the registry records what we know, and
+most of the API has never been version-bisected. `unknown` means "probe it",
+which is the honest instruction; a false `available` is how an agent ends up
+insisting a method exists.
+"""
+
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+# ── Version parsing ─────────────────────────────────────────────────────────
+# Resolve reports versions three ways depending on where you ask:
+#   Resolve.GetVersion()       -> [19, 1, 3, 7, ""]   (list, trailing build str)
+#   Resolve.GetVersionString() -> "19.1.3.7"
+#   and prose in this repo says things like "Studio 19.1.3.7 (macOS)".
+
+
+def parse_version(value: Any) -> Optional[Tuple[int, ...]]:
+    """Best-effort parse to a comparable tuple. None when nothing numeric is found.
+
+    Accepts the list form, the dotted string, or a sentence containing one. Only
+    leading numeric components are kept, so "21.0.4.5" -> (21, 0, 4, 5) and the
+    trailing build-name string Resolve appends is dropped rather than coerced.
+    """
+    # bool is a subclass of int, so True would otherwise parse as version (1,) —
+    # a truthy flag leaking in must not become a plausible-looking build number.
+    if value is None or isinstance(value, bool):
+        return None
+    if isinstance(value, (list, tuple)):
+        parts: List[int] = []
+        for item in value:
+            if isinstance(item, bool):
+                break
+            if isinstance(item, int):
+                parts.append(item)
+            elif isinstance(item, str) and item.strip().isdigit():
+                parts.append(int(item.strip()))
+            else:
+                break
+        return tuple(parts) or None
+    if isinstance(value, (int, float)):
+        return (int(value),)
+    if not isinstance(value, str):
+        return None
+
+    best: Optional[Tuple[int, ...]] = None
+    token: List[str] = []
+    for char in list(value) + [" "]:
+        if char.isdigit() or char == ".":
+            token.append(char)
+            continue
+        if token:
+            parts = [p for p in "".join(token).split(".") if p.isdigit()]
+            if parts:
+                candidate = tuple(int(p) for p in parts)
+                # Prefer the most specific run, so "Studio 19.1.3.7" beats a bare
+                # "19" appearing earlier in the same sentence.
+                if best is None or len(candidate) > len(best):
+                    best = candidate
+            token = []
+    return best
+
+
+def compare_versions(a: Any, b: Any) -> Optional[int]:
+    """-1/0/1 for a<b, a==b, a>b. None when either side will not parse.
+
+    Shorter tuples compare as though zero-padded: 21.0 == 21.0.0.
+    """
+    va, vb = parse_version(a), parse_version(b)
+    if va is None or vb is None:
+        return None
+    width = max(len(va), len(vb))
+    pa = va + (0,) * (width - len(va))
+    pb = vb + (0,) * (width - len(vb))
+    return (pa > pb) - (pa < pb)
+
+
+def at_least(live: Any, required: Any) -> Optional[bool]:
+    """True when `live` >= `required`. None when either will not parse."""
+    result = compare_versions(live, required)
+    return None if result is None else result >= 0
+
+
+# ── Version gates ───────────────────────────────────────────────────────────
+# Only surfaces with evidence behind them. `source` separates what this repo
+# measured from what a reporter measured, because the two carry different
+# weight and an agent relaying the fact should be able to say which it is.
+#
+#   measured  — probed live by this project
+#   reported  — a user's live probe, credited, not independently reproduced
+#   vendor    — stated by Blackmagic's shipped Developer/Scripting/README.txt
+
+VERSION_GATES: List[Dict[str, Any]] = [
+    {
+        "symbol": "Resolve.GetFairlightPresets",
+        "introduced_in": "20.2.2",
+        "source": "measured",
+        "note": "Absent on 19.1.3 (confirmed live). Without it the per-parameter "
+                "Fairlight gap is the whole story, because the whole-mix preset "
+                "workaround is unavailable.",
+        "issue": 128,
+    },
+    {
+        "symbol": "Timeline.ApplyFairlightPresetToCurrentTimeline",
+        "introduced_in": "20.2.2",
+        "source": "measured",
+        "note": "Same gate as GetFairlightPresets; the two are only useful together.",
+        "issue": 128,
+    },
+    {
+        "symbol": "Timeline.GetSelectedClips",
+        "introduced_in": "21.0.4",
+        "source": "reported",
+        "note": "Reported against 21.0.4.5 and listed in the shipped scripting "
+                "README. This repo's selection helper duck-probes three names and "
+                "reaches it by luck on builds that have it, so an absence here "
+                "degrades rather than errors.",
+        "issue": 131,
+    },
+    {
+        "symbol": "MediaPoolItem.GetTimeline",
+        "introduced_in": "21.0.4",
+        "source": "reported",
+        "note": "Reported against 21.0.4.5. Not reachable through this server yet.",
+        "issue": 131,
+    },
+    {
+        "symbol": "Project.SetRenderSettings UseFullExtents",
+        "introduced_in": "21.0.4",
+        "source": "vendor",
+        "note": "New SetRenderSettings key per the shipped scripting README. "
+                "SetRenderSettings ignores unknown keys silently, so on an older "
+                "build this is dropped with no signal rather than refused.",
+        "issue": 131,
+    },
+    {
+        "symbol": "Project.SetRenderSettings AddFrameHandles",
+        "introduced_in": "21.0.4",
+        "source": "vendor",
+        "note": "New SetRenderSettings key; ignored when full extents is enabled, "
+                "so it can do nothing for two different reasons.",
+        "issue": 131,
+    },
+    {
+        "symbol": "Project.SetRenderSettings DataBurnIn",
+        "introduced_in": "21.0.4",
+        "source": "vendor",
+        "note": "New SetRenderSettings key per the shipped scripting README.",
+        "issue": 131,
+    },
+]
+
+_GATES_BY_SYMBOL = {gate["symbol"].lower(): gate for gate in VERSION_GATES}
+
+AVAILABLE = "available"
+UNAVAILABLE = "unavailable"
+UNKNOWN = "unknown"
+
+
+def gate_for(symbol: str) -> Optional[Dict[str, Any]]:
+    """The recorded gate for `symbol`, matched loosely. None if we have none."""
+    if not symbol:
+        return None
+    needle = symbol.strip().lower()
+    if needle in _GATES_BY_SYMBOL:
+        return _GATES_BY_SYMBOL[needle]
+    for key, gate in _GATES_BY_SYMBOL.items():
+        if needle in key or key in needle:
+            return gate
+    return None
+
+
+def availability(symbol: str, live_version: Any) -> Dict[str, Any]:
+    """Is `symbol` present on `live_version`? Says `unknown` unless it knows.
+
+    The default matters more than the positive cases. Most of the API has never
+    been version-bisected, so anything outside VERSION_GATES is unknown — and an
+    agent should probe rather than assert.
+    """
+    gate = gate_for(symbol)
+    if gate is None:
+        return {
+            "status": UNKNOWN,
+            "symbol": symbol,
+            "reason": "No version gate is recorded for this symbol.",
+            "remediation": (
+                "Probe it on the live build with `name in dir(obj)` rather than "
+                "assuming either way. Do NOT use hasattr: on a Resolve API object "
+                "hasattr returns True for EVERY name, real or invented (measured on "
+                "Studio 19.1.3.7), so it can only ever say yes. "
+                "`callable(getattr(obj, name, None))` also works on the direct "
+                "connection, but dir() membership is the form unaffected by the "
+                "attribute-fabrication question — see the api_truth entry "
+                "'hasattr() / getattr() on Resolve API objects'. Most of the "
+                "scripting API has never been version-bisected here."
+            ),
+        }
+    ok = at_least(live_version, gate["introduced_in"])
+    if ok is None:
+        return {
+            "status": UNKNOWN,
+            "symbol": gate["symbol"],
+            "introduced_in": gate["introduced_in"],
+            "source": gate["source"],
+            "reason": f"Could not parse the live version ({live_version!r}).",
+            "remediation": "Read resolve_control get_version and pass version_string.",
+        }
+    return {
+        "status": AVAILABLE if ok else UNAVAILABLE,
+        "symbol": gate["symbol"],
+        "introduced_in": gate["introduced_in"],
+        "live_version": str(live_version),
+        "source": gate["source"],
+        "note": gate.get("note"),
+        "issue": gate.get("issue"),
+        "reason": (
+            f"{gate['symbol']} is recorded as introduced in {gate['introduced_in']} "
+            f"({gate['source']}); this build is {live_version}."
+        ),
+        "remediation": None if ok else (
+            f"Not present on this build. Do not offer it — say the build is too old "
+            f"and name {gate['introduced_in']} as the floor."
+        ),
+    }
+
+
+def gates_unavailable_on(live_version: Any) -> List[Dict[str, Any]]:
+    """Every recorded gate this build does NOT clear, for a session preflight."""
+    out = []
+    for gate in VERSION_GATES:
+        if at_least(live_version, gate["introduced_in"]) is False:
+            out.append({
+                "symbol": gate["symbol"],
+                "introduced_in": gate["introduced_in"],
+                "source": gate["source"],
+                "issue": gate.get("issue"),
+                "note": gate.get("note"),
+            })
+    return out
+
+
+# ── Applying a recorded fact to the live build ──────────────────────────────
+
+def measurement_relevance(verified_on: Any, live_version: Any) -> Dict[str, Any]:
+    """How much weight does a fact measured on `verified_on` carry here?
+
+    Deliberately three-valued. A fact measured on an older build is not wrong,
+    it is unconfirmed — and saying so is different from both "applies" and
+    "does not apply".
+    """
+    result = compare_versions(verified_on, live_version)
+    if result is None:
+        return {
+            "relevance": UNKNOWN,
+            "note": "Could not compare the measurement stamp with the live build.",
+        }
+    if result == 0:
+        return {
+            "relevance": "same_build",
+            "note": "Measured on this exact build.",
+        }
+    if result < 0:
+        return {
+            "relevance": "older_measurement",
+            "note": (
+                f"Measured on {verified_on}, older than this build ({live_version}). "
+                "Treat it as a prior, not a finding — Blackmagic changes the "
+                "scripting API per patch release. Re-confirm before relying on it."
+            ),
+        }
+    return {
+        "relevance": "newer_measurement",
+        "note": (
+            f"Measured on {verified_on}, NEWER than this build ({live_version}). "
+            "The behaviour described may not exist here yet, and a fix recorded "
+            "there has certainly not landed here."
+        ),
+    }
+
+
+def annotate_facts(
+    facts: Sequence[Dict[str, Any]],
+    live_version: Any,
+    *,
+    ledger_verified_on: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Copy `facts` with a `version_context` block against the live build.
+
+    `ledger_verified_on` is the module-wide stamp — when the ledger as a whole
+    was last reviewed. It is deliberately NOT used as a per-fact measurement:
+    most entries record the build they were actually measured on in their prose
+    (19.1.3.7, 21.0.0, 21.0.2.4 …), and attributing the ledger-wide stamp to
+    each of them would invent a measurement that never happened. An entry with
+    no structured `verified_on` therefore reports relevance `unknown` and says
+    where to look — which is true, and points at the real gap.
+
+    Non-destructive: entries are copied, so the ledger is never mutated.
+    """
+    if not live_version:
+        return [dict(fact) for fact in facts]
+    out = []
+    for fact in facts:
+        annotated = dict(fact)
+        context: Dict[str, Any] = {"live_version": str(live_version)}
+        stamp = fact.get("verified_on")
+        if stamp:
+            context.update(measurement_relevance(stamp, live_version))
+            context["measured_on"] = stamp
+        else:
+            context["relevance"] = UNKNOWN
+            context["note"] = (
+                "This entry carries no structured measurement stamp; the build it "
+                "was verified on is stated in its `reality` text. Read it there "
+                "before relying on the fact."
+            )
+            if ledger_verified_on:
+                context["ledger_reviewed_on"] = ledger_verified_on
+        if gate_for(fact.get("symbol", "")) or fact.get("min_version"):
+            context["availability"] = availability(fact.get("symbol", ""), live_version)
+        annotated["version_context"] = context
+        out.append(annotated)
+    return out

package/src/utils/swallowed_retakes.py

@@ -0,0 +1,139 @@
+"""Flag transcript words that may have swallowed an immediate retake.
+
+When a speaker re-reads a sentence immediately — the normal way people
+self-correct while recording — whisper emits the text ONCE, aligns it to the
+FIRST take, and absorbs "pause + entire second take" into the duration of a
+single word. The transcript then says the sentence was spoken once, cleanly.
+Every transcript-reading feature downstream inherits that lie: retake
+detection never fires, fluency scoring undercounts restarts, and a cut placed
+on a word boundary near the swallow point lands inside speech.
+
+Energy detection cannot catch it either. In the original measurement the
+swallowed span was breathing and keyboard noise peaking at -12.1 dB, LOUDER
+than the adjacent real speech at -16.7 dB, so `silencedetect` recalled 3 of 17
+ground-truth instances at any threshold. See issue #125.
+
+What this module does is deliberately small: it flags words whose duration is
+implausible for a single spoken word, and stops. It does not propose a cut
+point, because the data cannot support one — where inside the stretched word
+the second take begins is exactly what the timestamps have destroyed.
+
+**Why an absolute bar, after two better-sounding ideas failed.**
+The reporter measured all three on English material (2026-08-06, synthetic but
+acoustically matched, ground truth from a sample-accurate splice log):
+
+- A characters-per-second gate (`>= 2.5s and < 4.5 chars/s`), which worked on
+  the original Chinese material, fires on **0 of 50** English segments — the
+  swallowed segment itself runs 8.81 chars/s against an English median of 14.5.
+  Characters per second is not comparable across writing systems; it is retired
+  here rather than made configurable.
+- Scoring each word against the distribution of its OWN durations elsewhere in
+  the take — self-calibrating, and the obvious language-agnostic fix — missed
+  the swallow entirely and produced 8 false positives, all function words. The
+  reason is structural and worth keeping: the words that absorb retakes are
+  content words, and content words are naturally rare within one take, so they
+  never accumulate a distribution to be scored against.
+- The plain absolute bar found exactly one stretched word in 191.5s, and it was
+  the swallow point.
+
+So: one threshold, no calibration, no language assumptions.
+
+**Confidence.** The English confirmation rests on a single genuine swallow
+(n=1) in synthetic material — 13 of 15 planted retakes transcribed too cleanly
+to swallow, which is itself a limit of TTS-generated speech. The Chinese
+measurement it generalises from had 17 real instances. Treat the bar as a
+usable default, not a tuned constant.
+"""
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+# Seconds. A single spoken word above this is implausible in any language the
+# reporter measured; the one true positive ran well past it.
+DEFAULT_MIN_WORD_SECONDS = 1.2
+
+CAVEAT = (
+    "A flag is not a cut point. Where inside a stretched word the second take "
+    "begins is precisely what the swallow destroyed, so these need a human ear "
+    "(or a re-transcription pass over the isolated window) before anything is "
+    "removed. Absence of flags is not evidence of no retakes: a swallow that "
+    "smeared across several words rather than one will not clear the bar."
+)
+
+
+def _seconds(row: Mapping[str, Any], *keys: str) -> Optional[float]:
+    for key in keys:
+        value = row.get(key)
+        if isinstance(value, (int, float)):
+            return float(value)
+    return None
+
+
+def _word_text(row: Mapping[str, Any]) -> str:
+    for key in ("word", "text", "token"):
+        value = row.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+def find_swallowed_retake_candidates(
+    words: Sequence[Mapping[str, Any]],
+    *,
+    min_word_seconds: float = DEFAULT_MIN_WORD_SECONDS,
+) -> List[Dict[str, Any]]:
+    """Words whose duration exceeds the bar, in time order.
+
+    Accepts either transcript_words DB rows (`start_seconds`/`end_seconds`) or
+    raw whisper word dicts (`start`/`end`); a row missing either endpoint is
+    skipped rather than guessed at.
+    """
+    if not words or min_word_seconds <= 0:
+        return []
+    out: List[Dict[str, Any]] = []
+    for index, row in enumerate(words):
+        if not isinstance(row, Mapping):
+            continue
+        start = _seconds(row, "start_seconds", "start")
+        end = _seconds(row, "end_seconds", "end")
+        if start is None or end is None:
+            continue
+        duration = end - start
+        if duration < min_word_seconds:
+            continue
+        out.append({
+            "word_index": index,
+            "word": _word_text(row),
+            "start_seconds": round(start, 3),
+            "end_seconds": round(end, 3),
+            "duration_seconds": round(duration, 3),
+            "reason": (
+                f"word spans {duration:.2f}s, over the {min_word_seconds:.2f}s bar — "
+                "a retake may be absorbed into this word's duration"
+            ),
+        })
+    out.sort(key=lambda row: row["start_seconds"])
+    return out
+
+
+def swallowed_retake_report(
+    words: Sequence[Mapping[str, Any]],
+    *,
+    min_word_seconds: float = DEFAULT_MIN_WORD_SECONDS,
+) -> Dict[str, Any]:
+    """`find_swallowed_retake_candidates` plus the caveat, ready to attach."""
+    candidates = find_swallowed_retake_candidates(words, min_word_seconds=min_word_seconds)
+    return {
+        "count": len(candidates),
+        "min_word_seconds": min_word_seconds,
+        "candidates": candidates,
+        "caveat": CAVEAT,
+        "note": (
+            f"{len(candidates)} word(s) long enough to have swallowed an immediate "
+            "retake. Whisper reports a re-read sentence once and absorbs the pause "
+            "plus the second take into one word, so these are invisible to both the "
+            "transcript and any silence threshold (issue #125)."
+            if candidates
+            else "No words cleared the stretched-word bar. That is weak evidence, "
+                 "not proof: a swallow spread over several words will not show up here."
+        ),
+    }