#!/usr/bin/env python3
"""lane_render.py — render every window of a plan on the free Higgsfield lane.

WHY THIS EXISTS, and it is the whole reason this skill keeps producing hand-made films.

`explore_queue.py` is a supervisor over `vclaw video batch-submit`, and `submitBatch`
calls `submitSeedanceDirectNative` DIRECTLY — it never consults
`VCLAW_SEEDANCE_DIRECT_ADAPTER`. So on that one command `seedance-direct` is always the
paid native transport, the free in-tree engine is unreachable, and the supervisor refuses
on spend, never submits, then polls a queue that was never created. It looks exactly like
a slow queue. Two films in a row stopped at the stage before this one:

    $ cat build/rap-state
    scaffold lyrics song map hook styles plan vocal-map        <- stage 7b of 22

and everything after was hand-built in-session, which is where every defect an operator
later found on screen came from. This script is the missing transport: it drives the
adapter's documented SUBMIT/POLL contract itself, through the shared lane, so the runner
can reach `preview` on its own.

DO NOT "fix" the other path by relaxing batch-submit's spend gate to consult
`hasFreeInTreeSeedanceEngine`. That predicate governs the ADAPTER path
(`resolveAdapterCommand`), so on batch-submit it returns true while the route still
bills. Tried and reverted the same night (#353/#354).

WHAT IS PROMOTED HERE is the contract from three hand-written drivers, each rule below
learned by breaking it:

  ACCEPTANCE IS taskId AND EMPTY issues[]. The adapter returns an `externalJobId` even
  when every scene failed to submit. Trusting that id once recorded a job that did not
  exist as "accepted, do not resubmit" — which would have made the legitimate retry look
  like a forbidden resubmit. Check both fields, or record nothing.

  NEVER HOLD THE LANE WHILE BLOCKED. Turnstile (403 `turnstile_required`) is anti-bot
  RATE LIMITING, not moderation: the account is fine and the prompt is irrelevant.
  Holding the shared lane through a backoff starves the other machine for nothing, so
  the lease is released before every wait and on every exit path.

  NEVER RESUBMIT AN ACCEPTED JOB. There is no cancel endpoint. Once a taskId exists the
  job is the provider's; it is polled to terminal and never sent again. A draw that polls
  to `failed` is moderation — ~50% per draw, random — and MAY be redrawn, with the prompt
  UNCHANGED, because prompt-bisecting a random refusal burned six rewrites on one film.

  ONE LIST, ONE SLOT. Performance windows and B-roll come from the same work list. The
  hand-built B-roll driver `pgrep`-waited on the performance driver to exit, because two
  runners on a single-slot lane starve each other and it reads exactly like moderation
  failure. Pass several --plan files and they share the one queue.

  MOVE STALE OUTPUT ASIDE. The adapter SKIPS the download when `scene-0.mp4` already
  exists in the output dir. Two whole re-renders completed provider-side while the
  ORIGINAL clip was being inspected, and the conclusion drawn was "the model is ignoring
  the new prompt". It was not.

Plan validation is NOT re-implemented: `explore_queue.load_plan` already refuses
`synced: true` without a voiceRef, a voice video with no identity still, a `keyframe`
reference, more than one video reference, and a missing aspect. Provenance is written in
the same shape `index_library.py` reads, so the library and select layers work unchanged.

Usage:
  lane_render.py --plan <plan.json> [--plan <broll.json> ...] [--only w03,w08]
                 [--draws 4] [--dry-run]

Exit: 0 every job landed · 10 still outstanding (gate-compatible) · 1 broken · 3 blocked
"""
from __future__ import annotations

import argparse
import atexit
import uuid
import glob
import hashlib
import json
import os as _os, sys as _sys
_sys.path.insert(0, _os.path.dirname(_os.path.abspath(__file__)))   # a script loaded by path (tests) still finds its siblings
import raplib  # noqa: E402
import os
import re
import shutil
import signal
import subprocess
import sys
import threading
import time
from collections import Counter

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from explore_queue import load_plan, write_provenance  # noqa: E402  (same dir, by design)
from session_probe import ADVICE as SESSION_ADVICE, default_engine  # noqa: E402
from session_probe import probe as probe_engine_session  # noqa: E402
from sync_shift import MAX_HOLD_MS as SLIDE_MAX_HOLD_MS  # noqa: E402
from sync_profile import MAX_SPREAD_MS as SLIDE_MAX_SPREAD_MS  # noqa: E402
from sync_profile import MIN_SPANS as SLIDE_MIN_SPANS  # noqa: E402

ROUTE = "seedance-direct"
# TWO DRAWS, AND THE SECOND CHANGES SOMETHING. Draw 1 is the plan as approved. A
# moderation refusal (random ~50%/draw) gets ONE more submit — the approved SCRUB
# variant when the contract carries one (prompt_variants.py), else the same prompt. A
# take that LANDED is kept whatever its shape: placement is a slide, a wandering or
# stretched line is a cover or a re-split — never another draw of the same prompt,
# which fails the same way (w11: three draws, three rhythm defects, 2026-08-29). An
# invented vocal gets one unchanged redraw (4/4 evidence that it is a bad draw). A third
# draw is the operator's call (RAP_DRAWS=3), never the driver's.
MAX_DRAWS = 2
MAX_SUBMIT_TRIES = 12         # turnstile / transient-session attempts per draw
MAX_LANE_TRIES = 40           # `await` can time out while the other machine renders
BACKOFF_S = [300, 600, 900, 1200, 1800, 1800, 1800, 1800, 1800, 1800, 1800, 1800]
TURNSTILE_WAIT_S = 120        # a long sleep does not un-challenge a fingerprint
POLL_S, POLL_MAX = 45, 160    # ~2h ceiling per render
LEASE_LOST_BEATS = 3          # heartbeats refused in a row before a poll gives the slot up
SLOT_BUSY_WAIT_S = 300        # the provider slot frees when its render ends
VERIFY_MODEL = "small"        # same model the transcribe stage uses
MIN_VOICE_COVERAGE = 0.45     # below this the render is not performing its reference
MIN_REFERENCE_WORDS = 6       # too few and the overlap measure means nothing
MIN_UNIQUE_REFERENCE_WORDS = 5  # a phrase repeated 3x is not a vocabulary (see below)
MIN_TIMING_CORR = 0.6         # mirrors check_sync.SYNC_MIN — the bar `cut` enforces
NO_SLIDE_NEEDED_MS = 100      # a borderline take this close to the bar needs no slide, so needs no stability proof
BORDERLINE_CORR = 0.5         # 0.50–0.60: kept, TAGGED, only if slide can still fix it
MAX_SILENT_WORDS = 2          # a no-voice window may mumble; >= 3 heard words is a vocal
SHAPE_OFFSET_MS = 300         # beyond this a miss has a SHAPE (late/early), not a lottery
MAX_SLIDEABLE_MS = SLIDE_MAX_HOLD_MS   # past this `slide` cannot fix it; the hold shows

# RAP_BAR=keep — THE OPERATOR'S RELAXED BAR (2026-08-23 09:00, "relax all"). Three days
# for one film was the cost of the ship bar at the DRAW: ~30 min a draw on one slot, one
# in three passing. Under `keep`: a take with the right words is kept when its
# correlation clears 0.5 and its offset-after-slack is within 400 ms; a wandering take
# is kept and tagged (slide copies it, cover hides the worst seconds with B-roll);
# three draws a window, not four. An invented vocal or no vocal is still refused.
RELAXED = os.environ.get("RAP_BAR", "ship") == "keep"
if RELAXED:
    MIN_TIMING_CORR = BORDERLINE_CORR
    MAX_SLIDEABLE_MS = 400
if os.environ.get("RAP_DRAWS", "").strip().isdigit():
    MAX_DRAWS = max(1, int(os.environ["RAP_DRAWS"]))     # the operator's call, per run
STABILITY_SPAN_S = 2.0        # the span slide profiles over; mirrors sync_profile
# SALVAGE (operator, 2026-08-24: "add b-roll if incorrect ... before reject, as
# regenerating takes a long time"). A take that sings the RIGHT words with its HEAD on
# the bar but drifts off in a contiguous TAIL is kept, and the drifting tail is handed
# to the `cover` stage as B-roll spans (build/salvage-cover.json) instead of burning a
# ~30-min redraw. Bounded: words must have been verified, >=2 leading spans within
# SALVAGE_GOOD_MS, the covered tail <= SALVAGE_MAX_FRACTION of the window. A constant
# whole-take offset has no good head and never salvages — that class stays a redraw.
# RAP_SALVAGE=0 turns it off.
SALVAGE = os.environ.get("RAP_SALVAGE", "1") != "0"
SALVAGE_GOOD_MS = 150         # a head span this close needs no slide and reads fine
SALVAGE_MAX_FRACTION = 0.6    # cover more than this and the singer is hidden, which is worse
LANE_TTL_S, LANE_MAX_WAIT_S = 3600, 7200
# Re-check clips already on disk. ON by default — a bad take from an older driver is
# otherwise permanent, because every later run counts it as done. RAP_REVERIFY_LANDED=0
# is the deadline escape hatch and announces itself per clip.
REVERIFY_LANDED = os.environ.get("RAP_REVERIFY_LANDED", "1") != "0"
# RAP_ONE_DRAW=1 — THE OPERATOR'S "MOVE ON" RULE (2026-08-28 15:20: "stop doing the same
# prompt, move onto the next... you have already got video from this prompt, let's move
# on and figure out what B-roll we can add later"). A completed render LANDS on its first
# draw whatever the judge says — the verdict is written on the record and in the log so
# the cut/cover stages know what they hold — and a moderation refusal gets exactly ONE
# more submit. Redrawing a landed take is the operator's decision, not the driver's.
ONE_DRAW = os.environ.get("RAP_ONE_DRAW", "0") == "1"
if ONE_DRAW:
    # "keep every take, move on" has to hold on RESUME too: the resume path re-verifies
    # every clip on disk and parks a failing one for re-render — which, on the first
    # re-run after a one-draw batch, parked four kept takes and queued them again
    # (2026-08-28 22:57). Under one-draw the operator's rule outranks the re-verify.
    REVERIFY_LANDED = False

# Turnstile has already locked this profile out headless before, and the adapter's own
# recorded evidence (adapter.py, 2026-08-07) is that a headless fingerprint is challenged
# far more aggressively and ONCE CHALLENGED IT STAYS CHALLENGED. A visible window is the
# price of a render that can actually submit.
HEADED_ENV = {"HIGGS_VCLAW_HEADLESS": "0"}

_HELD: list[str] = []
_LOG = None


def say(msg: str) -> None:
    line = f"{time.strftime('%H:%M:%S')}  {msg}"
    print(line, flush=True)
    if _LOG:
        with open(_LOG, "a", encoding="utf-8") as handle:
            handle.write(line + "\n")


def die(msg: str, code: int = 1) -> "None":
    say(f"FATAL: {msg}")
    raise SystemExit(code)


# --------------------------------------------------------------------------
# where things are — resolved, never hardcoded
# --------------------------------------------------------------------------

def resolve_main() -> str:
    """The videoclaw-v3 checkout. Self-locating so this runs from any worktree.

    The hand-written drivers carried `~/Documents/GitHub/videoclaw-shared-queue` as a
    literal, and one of them pointed at a worktree that was deleted — the lane broke and
    the failure looked like the provider. This script is three levels below the repo
    root; that is a fact about the file, not about one machine.
    """
    env = os.environ.get("VCLAW_MAIN")
    if env:
        return os.path.abspath(os.path.expanduser(env))
    here = os.path.dirname(os.path.abspath(__file__))          # .../skills/rap-avatar-mv/scripts
    return os.path.abspath(os.path.join(here, "..", "..", ".."))


def resolve_adapter(main: str) -> str:
    """The engine binary. The in-tree engine is the default and needs no wiring.

    An override used to be mandatory because main's adapter submitted the retired
    `seedance_unlimited` and took an instant 403. That was fixed in #363 — main now sends
    `seedance_2_5` with `use_unlim`. An override pointing at a private copy of the
    adapter is therefore a fork that will silently drift from the engine everything else
    uses, so it is reported loudly rather than used quietly.
    """
    override = os.environ.get("VCLAW_SEEDANCE_DIRECT_ADAPTER")
    if override:
        path = os.path.abspath(os.path.expanduser(override))
        if not os.access(path, os.X_OK):
            die(f"VCLAW_SEEDANCE_DIRECT_ADAPTER is not executable: {path}")
        say(f"NOTE: using an adapter OVERRIDE ({path}). The in-tree engine is the "
            f"default since #363; an override is a fork that will drift.")
        return path
    run = os.path.join(main, "engines", "seedance-direct", "run.sh")
    if not os.access(run, os.X_OK):
        die(f"no engine at {run} — run engines/seedance-direct/bootstrap.sh", 3)
    engine = os.path.dirname(run)
    if not os.path.exists(os.path.join(engine, ".venv", "bin", "python")):
        die(f"engine has no venv at {engine}/.venv — run bootstrap.sh", 3)
    # A missing or logged-out browser profile is THE failure that masquerades as
    # moderation: every draw refuses, nothing in the message says "log in".
    if not os.path.isdir(os.path.join(engine, ".cloak-profile")):
        die(f"no Higgsfield browser profile at {engine}/.cloak-profile. This is not "
            f"moderation — the lane cannot authenticate at all. Log in to higgsfield.ai "
            f"in that profile, or set HIGGS_VCLAW_PROFILE to one that is logged in.", 3)
    return run


def resolve_queue_wrapper(main: str) -> str:
    wrapper = os.path.join(main, "scripts", "with-shared-queue.sh")
    if not os.access(wrapper, os.X_OK):
        die(f"no shared-queue wrapper at {wrapper}. Every submit on this lane goes "
            f"through the shared coordinator — another machine may be rendering.", 3)
    return wrapper


# --------------------------------------------------------------------------
# the shared lane
# --------------------------------------------------------------------------

class Lane:
    def __init__(self, main: str, wrapper: str, slug: str, account: str) -> None:
        self.main, self.wrapper, self.slug, self.account = main, wrapper, slug, account
        self.vclaw = os.path.join(main, "dist", "cli", "vclaw.js")
        if not os.path.isfile(self.vclaw):
            die(f"no built CLI at {self.vclaw} — run npm run build", 3)
        # ONE CLAIM PER DRIVER. Every lane call is a fresh node process; the coordinator's
        # owner check used to be the machine alone, and two sessions on one Mac share a
        # machine — so either could end the other's lease (2026-09-04). The claim is minted
        # once here, exported into every call, and the coordinator matches it on
        # heartbeat and release. VCLAW_LANE_CLAIM pre-set = the trace harness / a test.
        self.claim = os.environ.get("VCLAW_LANE_CLAIM") or f"lane-render-{os.getpid()}-{uuid.uuid4().hex[:8]}"
        self._env: dict | None = None

    def _lane_env(self) -> dict:
        """The wrapper's resolved environment, read ONCE. `with-shared-queue.sh` sources the
        config and reads the token from the Keychain on every invocation; at a 45 s
        heartbeat cadence that was a Keychain read per beat for the whole render."""
        if self._env is None:
            proc = subprocess.run(["bash", self.wrapper, "/usr/bin/env"], cwd=self.main,
                                  capture_output=True, text=True, timeout=60)
            if proc.returncode != 0:
                # FAIL CLOSED. A bare `node vclaw.js video lane` with no coordinator URL is
                # the local-SQLite dev default: two drivers each "holding" a private lane,
                # which is the original collision in a worse costume.
                die(f"shared-queue wrapper failed ({proc.returncode}): "
                    f"{(proc.stderr or proc.stdout).strip()[-300:]}", 3)
            env = dict(os.environ)
            for line in proc.stdout.splitlines():
                if line.startswith("VCLAW_"):
                    k, _, v = line.partition("=")
                    env[k] = v
            for key in ("VCLAW_SHARED_QUEUE_URL", "VCLAW_SHARED_QUEUE_TOKEN", "VCLAW_MACHINE_ID"):
                if not env.get(key):
                    die(f"shared-queue wrapper resolved no {key} — refusing to run on a local lane", 3)
            env["VCLAW_LANE_CLAIM"] = self.claim
            self._env = env
        return self._env

    def _run(self, verb: str, *args: str, timeout: int | None = None) -> dict:
        cmd = [os.environ.get("NODE_BIN", "node"), self.vclaw,
               "video", "lane", verb, "--route", ROUTE, "--account", self.account, *args]
        try:
            proc = subprocess.run(cmd, cwd=self.main, capture_output=True, text=True,
                                  timeout=timeout, env=self._lane_env())
        except subprocess.TimeoutExpired:
            return {"error": f"lane {verb} timed out"}
        try:
            return json.loads(proc.stdout[proc.stdout.index("{"):])
        except (ValueError, json.JSONDecodeError):
            return {"error": (proc.stdout + proc.stderr)[-400:]}

    def await_grant(self, prompt_hash: str) -> str | None:
        """Wait for the lane using the coordinator's OWN `await` verb.

        DO NOT hand-roll this poll loop. The CLI stamps `holder: ${process.pid}` on every
        call, and a hand-rolled loop makes a fresh node process — a fresh pid — each time.
        So when the coordinator GRANTED the ticket, the next poll did not recognise it as
        its own and reported "queued" again, forever. Observed live: HELD for 54s while
        the driver logged "lane busy", waiting for a lane it was already holding and
        starving the other machine throughout. `lane.ts` says it outright: "await exists
        so drivers stop hand-rolling the poll loop."
        """
        reply = self._run("await", "--project", self.slug, "--prompt-hash", prompt_hash,
                          "--ttl", str(LANE_TTL_S), "--max-wait", str(LANE_MAX_WAIT_S),
                          timeout=LANE_MAX_WAIT_S + 120)
        ticket = reply.get("ticketId")
        # Track a QUEUED ticket too: a ghost ticket left by a killed driver holds a slot
        # just as effectively as a granted one.
        if ticket and ticket not in _HELD:
            _HELD.append(ticket)
        if reply.get("status") == "granted":
            return ticket
        say(f"  lane await ended {reply.get('status')} "
            f"(timedOut={reply.get('timedOut')}) — will retry")
        return None

    def heartbeat(self, ticket: str) -> bool:
        """True while the coordinator still holds this ticket for THIS driver. False is a
        real event (the lease expired, or another driver ended it), not noise: it used to be
        discarded, and a driver polled on for 30 minutes on a lease the ledger had already
        handed to someone else."""
        reply = self._run("heartbeat", "--ticket", ticket, "--ttl", str(LANE_TTL_S), timeout=120)
        if reply.get("error"):
            say(f"  lane heartbeat error: {reply['error'][:160]}")
            return False
        return reply.get("refreshed") is True

    def release(self, ticket: str | None, outcome: str | None = None, job: str | None = None,
                note: str | None = None) -> None:
        """Give the slot back AND say what happened on it. The coordinator keeps the
        outcome on the done ticket and the control room lists it as the render log
        (2026-09-04): completed / failed / timeout / lease-lost / not-submitted /
        slot-busy / abandoned. A release with no outcome is a legacy row (null)."""
        if not ticket:
            return
        args = ["release", "--ticket", ticket]
        if outcome:
            args += ["--outcome", outcome]
            if job:
                args += ["--job", str(job)[:256]]
            if note:
                args += ["--note", str(note)[:512]]
        self._run(*args, timeout=120)
        if ticket in _HELD:
            _HELD.remove(ticket)


_LANE: Lane | None = None


def _release_all(*_args) -> None:
    """The lease must not outlive the process.

    A driver was killed mid-wait while holding the lane. Nothing was rendering, but the
    lease stayed held and the other machine sat queued behind a dead ticket — the exact
    starvation that release-before-every-wait exists to prevent. The TTL recovers it in
    an hour; nobody should wait an hour for a process that is already dead. atexit does
    not run on SIGTERM/SIGINT, so both doors are covered.
    """
    while _HELD:
        ticket = _HELD.pop()
        try:
            if _LANE:
                _LANE._run("release", "--ticket", ticket, "--outcome", "abandoned",
                           "--note", "driver exited while holding the lease", timeout=60)
            say(f"released ticket on exit: {ticket}")
        except Exception:
            pass


def _install_exit_hooks() -> None:
    """Called from main(), not at import: spend_gate.py and preflight_higgs.py import
    this module for `build_payload_doc`/`payload_hash`, and an import must not install
    signal handlers in a process that never touches the lane."""
    atexit.register(_release_all)
    for _sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
        signal.signal(_sig, lambda s, f: (_release_all(), sys.exit(143)))


# --------------------------------------------------------------------------
# the provider session
# --------------------------------------------------------------------------

def probe_session() -> tuple[int, str]:
    """0 authenticated · 4 not logged in · 7 could not tell. See session_probe.py."""
    return probe_engine_session(default_engine())


def session_alive() -> bool | None:
    """Probe the session rather than believing the adapter's guess.

    The adapter reports "the Clerk token could not be minted — the session is likely
    dead/expired" for a transient in-page fetch failure too, and the two read identically.
    Acting on the guess cost a stopped queue once: the keepalive answered "OK session
    alive" seconds later. higgs-cloak's keepalive also RE-SEEDS from the user's Chrome
    cookies when the session really has expired, so this both diagnoses and repairs.

    True = alive or reseeded · False = genuinely dead, a human must log in ·
    None = the probe itself could not run, which proves NOTHING and must not be
    treated as either answer.
    """
    cloak = os.environ.get("HIGGS_CLOAK_ROOT",
                           os.path.expanduser("~/Documents/GitHub/higgs-cloak"))
    venv = os.path.join(resolve_main(), "engines", "seedance-direct", ".venv", "bin", "python")
    if not (os.path.exists(venv) and os.path.isdir(cloak)):
        return None
    try:
        proc = subprocess.run([venv, "higgs_auth_keepalive.py"], cwd=cloak,
                              capture_output=True, text=True, timeout=300)
    except (subprocess.TimeoutExpired, OSError):
        return None
    out = proc.stdout + proc.stderr
    if "OK session alive" in out or "RESEEDED" in out:
        return True
    if "DEAD" in out:
        return False
    return None


# --------------------------------------------------------------------------
# one render
# --------------------------------------------------------------------------

def clip_path(plan: dict, job: dict) -> str:
    """Where index_library.py will look for this clip. Not negotiable.

    `explore_queue.write_provenance` keys provenance by realpath of
    <queueDir>/clips/<id>.mp4, and index_library finds a clip on disk with only its path
    to look up with. Land it anywhere else and every downstream layer loses its lineage.
    """
    return os.path.join(plan["queueDir"], "clips", f"{job['id']}.mp4")


def build_payload_doc(plan: dict, job: dict, work: str) -> dict:
    """The exact payload for one job — PURE. No directories made, nothing moved, nothing
    written. preflight_higgs.py builds the contract page from this and spend_gate.py
    hashes it, so what the operator approves is what the driver sends, by construction.

    Raises FileNotFoundError for a reference that is not on disk.
    """
    refs: list[str] = []
    identity = job.get("identityRef", plan.get("identityRef"))
    if identity:
        refs.append(os.path.abspath(identity))
    # Second still BEFORE the voice: image, image, audio — the adapter numbers per
    # role, so this is what makes @IMG_2 land on <<<image_2>>>.
    if job.get("identityRef2"):
        refs.append(os.path.abspath(job["identityRef2"]))
    if job.get("identityRef3"):          # a two-performer shot-ref window: keyframe + both portraits
        refs.append(os.path.abspath(job["identityRef3"]))
    if job.get("voiceRef"):
        refs.append(os.path.abspath(job["voiceRef"]))
    for ref in refs + ([os.path.abspath(job["motionRef"])] if job.get("motionRef") else []):
        if not os.path.exists(ref):
            raise FileNotFoundError(f"{job['id']}: reference missing on disk: {ref}")

    # referenceRole MUST be 'character'. split_references() attaches the voice only when
    # the role is 'character' AND exactly one video is present; any other role falls
    # through to "everything is a start-frame candidate", no voice, and NO WARNING. The
    # render succeeds and the man moves his mouth to nothing. A hand-built payload with
    # `referenceRole: "identity"` is exactly how one window shipped at 0.00 lip-sync.
    #
    # generateAudio FOLLOWS THE VOICE. A window sent with no voice reference is a
    # wordless window — an intro, a break — and asking the model to generate audio for
    # it is asking it to invent a vocal, which it then mouths. The song is muxed over
    # the picture at assembly; the clip's own audio is only ever a verification aid,
    # and a no-voice window is verified for SILENCE (see verify_landed).
    return {
        "projectSlug": plan["slug"],
        "routeId": ROUTE,
        "workspaceRoot": plan["workspaceRoot"],
        "outputDir": work,
        "executionProfile": {
            "aspectRatio": plan["aspect"],
            "quality": "standard",
            "resolution": plan["resolution"],
            "generateAudio": bool(job.get("voiceRef")),
        },
        "tasks": [{
            "sceneIndex": 0,
            "prompt": job["prompt"],
            "durationSeconds": job.get("seconds", plan.get("seconds")),
            "referencePaths": refs,
            **({"referenceRole": "character"} if refs else {}),
            # THE MOTION DONOR IS NOT A REFERENCE PATH. split_references() attaches the voice
            # only when exactly ONE video is in referencePaths; a second video there would
            # silently drop the voice. The donor rides its own field, which the adapter
            # uploads as a `video` media (cited @video1) beside the voice (`audio_1`).
            **({"motionReferencePath": os.path.abspath(job["motionRef"])} if job.get("motionRef") else {}),
        }],
    }


def _sha256_file(path: str) -> str:
    h = hashlib.sha256()
    with open(path, "rb") as fh:
        for chunk in iter(lambda: fh.read(1 << 20), b""):
            h.update(chunk)
    return h.hexdigest()


def payload_hash(payload: dict) -> str:
    """What an approval binds to: the prompt, the duration, the shape, and the BYTES of
    every reference, in order. Shared with spend_gate.py (which hashes the contract's
    payloads at --approve) so the driver's check is the same arithmetic, not a copy.

    Reference CONTENTS, not basenames: `voice/w08.mp4` kept its name across a re-plan
    while its audio moved 12 seconds (the slice cache was keyed on duration), and a
    name-keyed record would have called the two the same submission.
    """
    task = payload["tasks"][0]
    profile = payload["executionProfile"]
    parts = [task.get("prompt", ""), str(task.get("durationSeconds")),
             profile.get("aspectRatio", ""), profile.get("resolution", "")]
    parts += [_sha256_file(r) for r in task.get("referencePaths", [])]
    return hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()


def build_payload(plan: dict, job: dict, work: str, payload_name: str = "payload.json") -> str:
    os.makedirs(work, exist_ok=True)
    superseded = os.path.join(plan["queueDir"], "superseded")
    os.makedirs(superseded, exist_ok=True)
    # See the module docstring: the adapter skips the download when an mp4 is already
    # here, so a re-render silently returns the previous take.
    for name in os.listdir(work):
        if name.endswith(".mp4"):
            shutil.move(os.path.join(work, name),
                        os.path.join(superseded,
                                     f"{job['id']}-prev-{int(time.time())}-{name}"))
    try:
        payload = build_payload_doc(plan, job, work)
    except FileNotFoundError as exc:
        die(str(exc))
    path = os.path.join(work, payload_name)
    with open(path, "w", encoding="utf-8") as handle:
        json.dump(payload, handle, indent=1)
    return path


# The shape a landed-but-wrong take leaves for the NEEDS report — what fixes it, and
# that another draw of the same prompt does not.
NEEDS_FOR_SHAPE = {"rhythm": "rerender:resplit", "early": "cover", "late": "cover", "silent": "rerender:redraw"}
# A SUNG TAKE MUST BE HEARD. Baby Nimbooda w13 (2026-09-04) landed with its voice at −38.7 dB
# mean (every other take −14) and passed "on the bar": the words were there, just inaudible,
# and the vocal swap boosted 22 dB of noise into the master. Below this mean level a voiced
# take is a redraw.
VOICE_MIN_MEAN_DB = float(os.environ.get("VOICE_MIN_MEAN_DB", "-25"))


def clip_mean_db(clip: str) -> float | None:
    """ffmpeg volumedetect mean_volume of the clip's audio, or None when unmeasurable."""
    try:
        r = subprocess.run(["ffmpeg", "-v", "info", "-i", clip, "-af", "volumedetect", "-f", "null", "-"],
                           capture_output=True, text=True, timeout=120)
    except (OSError, subprocess.TimeoutExpired):
        return None
    m = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", r.stderr or "")
    return float(m.group(1)) if m else None


def prompt_sha(job: dict) -> str:
    """12 hex of the job's prompt — the content key a landed clip is pinned to."""
    return hashlib.sha256((job.get("prompt") or "").encode("utf-8")).hexdigest()[:12]


def stale_prompt(plan: dict, job: dict, dest: str) -> str | None:
    """Why the clip on disk was rendered from a different prompt than the plan's, or None.

    CACHE BY CONTENT (operator, 2026-09-05): the provenance record carries the prompt's
    sha at submit time; a re-plan that rewrote the prompt must not silently reuse the
    old picture (three empty-set cutaways were about to be reused after their prompts
    had been rewritten to show the troupe). A record without a sha (older driver) is
    not judged."""
    # A PLACED clip has no prompt of its own. reuse_clips leaves <id>-reused.json beside
    # the queue; the operator's word (and the world/length judge) is what stands behind
    # it, so a re-plan that rewrites the window's prompt must not park it (four placed
    # cutaways + a dance window were parked "stale" and re-queued, 2026-09-07).
    if os.path.isfile(os.path.join(plan["queueDir"], f"{job.get('id')}-reused.json")):
        return None
    prov_path = os.path.join(plan["queueDir"], "provenance.json")
    try:
        prov = json.load(open(prov_path, encoding="utf-8"))
    except (OSError, ValueError):
        return None
    rec = prov.get(os.path.realpath(dest)) or prov.get(dest) or {}
    if rec.get("placedFrom"):
        return None
    old = rec.get("promptSha")
    now = prompt_sha(job)
    if old and old != now:
        return f"was rendered from an older prompt ({old} → {now})"
    return None


def variant_for(plan: dict, jid: str, name: str) -> dict | None:
    """The approved variant prompt for this job (stashed by approval_gate), or None."""
    return ((plan.get("_variants") or {}).get(jid) or {}).get(name)


def submit(adapter: str, payload: str) -> tuple[str | None, str, list[str]]:
    """Returns (jobId, taskId, issues). A job EXISTS only when taskId is non-empty."""
    with open(payload, encoding="utf-8") as stdin:
        proc = subprocess.run([adapter], stdin=stdin, capture_output=True, text=True,
                              env={**os.environ, **HEADED_ENV})
    try:
        reply = json.loads(proc.stdout[proc.stdout.index("{"):])
    except (ValueError, json.JSONDecodeError):
        # Keep the whole reply on disk: the 300-char tail that reaches the log carried
        # the provider's sentence but not what the adapter printed around it (w19,
        # 2026-09-05 — three stalls, no way to tell why the JSON did not parse).
        raw_path = os.path.join(os.path.dirname(payload), f"submit-raw-{time.strftime('%H%M%S')}.txt")
        try:
            with open(raw_path, "w", encoding="utf-8") as fh:
                fh.write("--- stdout ---\n" + proc.stdout + "\n--- stderr ---\n" + proc.stderr)
        except OSError:
            raw_path = "(unsaved)"
        return None, "", [f"adapter produced no JSON: {(proc.stdout + proc.stderr)[-300:]} (raw: {raw_path})"]
    raw = reply.get("rawResult", reply)
    scenes = raw.get("submittedScenes") or [{}]
    return reply.get("externalJobId"), (scenes[0].get("taskId") or ""), (raw.get("issues") or [])


HEARTBEAT_S = 45              # the lease is kept alive on ITS OWN clock, not the adapter's


def poll(adapter: str, plan: dict, work: str, job_id: str, ticket: str, lane: Lane) -> str:
    path = os.path.join(work, "poll.json")
    with open(path, "w", encoding="utf-8") as handle:
        json.dump({"action": "poll", "projectSlug": plan["slug"], "routeId": ROUTE,
                   "externalJobId": job_id, "outputDir": work,
                   "workspaceRoot": plan["workspaceRoot"]}, handle, indent=1)
    # THE HEARTBEAT RUNS BESIDE THE ADAPTER, NOT AFTER IT. One adapter poll is a whole
    # cloak-browser session and can block for thirty minutes; the heartbeat used to
    # wait for it, and each beat had already reset the lease to 30 min — so w15's
    # lease expired mid-render at 23:27 with the job still running and nobody
    # refusing anything (film #3, 2026-09-04). A daemon thread beats every
    # HEARTBEAT_S while the adapter runs; three refusals in a row raise `lost`.
    # Not this process's lease (a recovery poll of an earlier driver's job): no thread,
    # a refusal would mean nothing.
    lost = threading.Event()
    stop = threading.Event()
    mine = bool(ticket and ticket in _HELD)

    def keep_alive() -> None:
        misses = 0
        while not stop.wait(HEARTBEAT_S):
            if lane.heartbeat(ticket):
                misses = 0
                continue
            misses += 1
            if misses >= LEASE_LOST_BEATS:
                say(f"  lane: {LEASE_LOST_BEATS} heartbeats refused in a row — the coordinator no "
                    f"longer holds {ticket} for this driver; another driver may be on the slot")
                lost.set()
                return

    beater = threading.Thread(target=keep_alive, name="lane-heartbeat", daemon=True) if mine else None
    if beater:
        beater.start()
    try:
        for _ in range(POLL_MAX):
            with open(path, encoding="utf-8") as stdin:
                proc = subprocess.run([adapter], stdin=stdin, capture_output=True, text=True)
            status = ""
            try:
                status = json.loads(proc.stdout[proc.stdout.index("{"):]).get("status", "")
            except (ValueError, json.JSONDecodeError):
                pass
            if status in ("completed", "failed"):
                return status
            if lost.is_set():
                # THE LEASE IS GONE; STOP POLLING ON IT. The provider job keeps running —
                # the resume path reconciles it from the live-job record — but this
                # driver no longer owns the slot and must not behave as if it did.
                return "lease-lost"
            time.sleep(POLL_S)
        return "timeout"
    finally:
        stop.set()


def land(work: str, dest: str) -> bool:
    os.makedirs(os.path.dirname(dest), exist_ok=True)
    clips = [os.path.join(work, f) for f in os.listdir(work) if f.endswith(".mp4")]
    if not clips:
        return False
    shutil.move(max(clips, key=os.path.getsize), dest)
    return True


def _skeleton(token: str) -> str:
    """A Devanagari (or any abugida) word reduced to its consonant skeleton: combining
    vowel signs, nukta and anusvara stripped after NFD. whisper-small writes the SAME
    Hindi word differently from one recording to the next — the reused w05 take and
    its own slice came back "काजल कंगन" vs "बाज़ल खंगन", "महिफिलती" vs "महिफल ती" —
    so exact tokens scored 33% on an identical lyric and the gate parked a good clip
    (2026-08-22 22:01). English is untouched: it has no combining marks."""
    import unicodedata
    return "".join(c for c in unicodedata.normalize("NFD", token.lower())
                   if unicodedata.category(c) not in ("Mn", "Mc")) or token.lower()


def _consonants(word: str) -> int:
    """How many consonant letters a wanted word has once transliterated to Latin."""
    from vocal_brief import norm_latin, transliterate
    return len(re.findall(r"[b-df-hj-np-tv-z]", norm_latin(transliterate(word)).lower()))


_REPEAT = re.compile(r"\b(\w+)(?:[,!.]?\s+\1\b){2,}", re.I | re.U)


def repeated_shout_spans(job: dict) -> list[dict]:
    """The window's own spans whose text repeats a word three or more times in a row —
    "Main, main, main", "Me me me" — the shouts a transcriber does not write down."""
    out = []
    for sp in ((job.get("vocal") or {}).get("spans") or []):
        if sp.get("partialHead") or sp.get("partialTail"):
            continue
        if _REPEAT.search(sp.get("text", "") or ""):
            out.append(sp)
    return out


SHOUT_LATE_S = 1.5   # a take may sing its line this late and still be judged on it


def shout_verdict(clip: str, ref: str, job: dict) -> tuple[bool, str]:
    """A repeated shout is judged on the ENVELOPE, not the transcript: the take must
    carry at least as many voice bursts over the line as the reference does, less
    one (a merged pair). Both on the window's clock; the take is read up to
    SHOUT_LATE_S later, because takes sing late."""
    spans = repeated_shout_spans(job)
    if not spans:
        return True, ""
    notes = []
    for sp in spans:
        a, b = float(sp["start"]), float(sp["end"])
        want_n = raplib.bursts(ref, a, b - a)
        got_n = raplib.bursts(clip, max(0.0, a - 0.3), (b - a) + 0.3 + SHOUT_LATE_S)
        if want_n >= 3 and got_n < want_n - 1:
            m = _REPEAT.search(sp.get("text", ""))
            word = m.group(1).lower() if m else "the shout"
            return False, (f"did not shout {word!r} the way the record does — {got_n} voice burst(s) over "
                           f"\u201c{sp.get('text', '')}\u201d against the record's {want_n} (the envelope, not "
                           f"the transcript: shouts are never written down)")
        notes.append(f"{sp.get('text', '')[:30]}: {got_n}/{want_n} bursts")
    return True, "; ".join(notes)


def _skeleton_coverage(want: list[str], got: list[str]) -> float:
    """Fraction of the reference's CONCATENATED consonant skeleton covered by matching
    blocks of the render's. Token matching failed on TOKENISATION, not words: whisper
    wrote "aviator" as "को तवी एटोर" in the slice and "कोट आवियेटर" in the take, and a
    take singing the right lyric scored 6/15 tokens (2026-08-23 00:43). Character-level
    alignment on the joined skeletons: the day's real takes 0.60-0.88, an invented vocal
    0.19-0.22, the song's other bars 0.16-0.25."""
    import difflib
    a = "".join(_skeleton(w) for w in want)
    b = "".join(_skeleton(w) for w in got)
    if not a:
        return 0.0
    m = difflib.SequenceMatcher(None, a, b, autojunk=False)
    return sum(bl.size for bl in m.get_matching_blocks()) / len(a)


def _fuzzy_shared(want: list[str], got: list[str], threshold: float) -> int:
    """Greedy one-to-one matching on skeletons: each reference word consumes the best
    unmatched render word scoring >= threshold (difflib ratio)."""
    import difflib
    pool = [_skeleton(g) for g in got]
    shared = 0
    for w in want:
        sk = _skeleton(w)
        best, score = -1, 0.0
        for i, g in enumerate(pool):
            r = difflib.SequenceMatcher(None, sk, g).ratio()
            if r > score:
                best, score = i, r
        if best >= 0 and score >= threshold:
            shared += 1
            pool.pop(best)
    return shared


def must_hear_for(job_id: str | None, spec: str | None = None) -> list[str]:
    """RAP_MUST_HEAR: "bold,untraditional" applies to every window; "w01=bold,untraditional"
    (';'-separated per window) applies to that window only. The unscoped form once parked
    four good takes for not containing the redraw's words (New Era, 2026-08-31 09:21)."""
    spec = os.environ.get("RAP_MUST_HEAR", "") if spec is None else spec
    words: list[str] = []
    for part in spec.split(";"):
        part = part.strip()
        if not part:
            continue
        if "=" in part:
            jid, _, rest = part.partition("=")
            if jid.strip().lower() != str(job_id or "").lower():
                continue
            part = rest
        words += [w.strip().lower() for w in part.split(",") if w.strip()]
    return words


def voice_verdict(want: list[str], got: list[str], fuzzy: bool = False, job_id: str | None = None) -> tuple[bool, str]:
    """The judgment, separated from the transcriber so it can be pinned by a test.

    Multiset overlap, not order: a clip may drift in time and still be performing the
    right words, which is a SLIDE problem and not this one.

    `fuzzy` (a non-English lyric, transcribed in its own script): tokens match on their
    consonant skeleton at >= 0.7 similarity instead of exact equality, because the
    transcriber's spelling of one word is not stable across recordings. An invented
    vocal still shares few skeletons, and the TIMING check behind this still has to
    pass, so the gate keeps its teeth.
    """
    if len(want) < MIN_REFERENCE_WORDS:
        return True, f"the reference itself has only {len(want)} words; nothing to check"
    # A REPEATED PHRASE IS NOT A VOCABULARY. w07 of the birthday film is the outro:
    # "floatin' either way" three times — nine words, THREE unique. A multiset overlap
    # over three words carries almost no information, and washy outro vocals are exactly
    # what whisper mishears: two draws came back as "don't know any of the way" x3 and
    # "go any the way" x3. Same rhythm, same repetition count, same rhyme — both were
    # genuinely performing the reference (they correlate 0.73 and 0.61), and this check
    # threw both away. Fuzzy matching does not save it either; the words really are
    # transcribed differently.
    #
    # So on a sparse reference the words abstain and the TIMING check decides, because
    # correlation measures the performance rather than the transcription of it.
    if len(set(want)) < MIN_UNIQUE_REFERENCE_WORDS:
        return True, (f"the reference is {len(set(want))} unique word(s) repeated "
                      f"({len(want)} total) — too little vocabulary to judge; leaving "
                      f"the verdict to the timing check")
    if not got:
        return False, "the render produced NO intelligible vocal at all"
    a, b = Counter(want), Counter(got)
    shared = sum((a & b).values())
    how = "words"
    coverage = shared / max(1, len(want))
    if fuzzy:
        shared = max(shared, _fuzzy_shared(want, got, 0.7))
        char_cov = _skeleton_coverage(want, got)
        if char_cov > shared / max(1, len(want)):
            how = "consonant skeleton, aligned"
            coverage = char_cov
            shared = round(char_cov * len(want))
        else:
            how = "words, matched on consonant skeletons"
            coverage = shared / max(1, len(want))
    if coverage < MIN_VOICE_COVERAGE:
        return False, (f"sings {coverage:.0%} of its reference "
                       f"({shared}/{len(want)} {how}) — it ignored the voice and "
                       f"invented a vocal")
    # RAP_MUST_HEAR="bold,untraditional": words the take MUST sing, matched on the
    # consonant skeleton (the operator's call for a redraw of one window whose take
    # sang "old moves only, unconditional lane" for "Bold moves only, untraditional
    # lane" — 97 % of the words, kept, and wrong; New Era 2026-08-31 09:25). Under
    # vocal-swap the take's words ARE the film's, so a slip is a redraw, not a keep.
    must = must_hear_for(job_id)
    if must:
        # A HOMOPHONE SKELETON IS NOT THE WORD. "main" (मैं) and "mein" (में) share the
        # skeleton "mn", so a must-hear for "main" was satisfied by a take that sang
        # "bagiya mein" and never shouted "main" (w09, 2026-09-02). A heard word counts
        # exactly, or transliterated (मैं -> main), or on the skeleton only when the
        # wanted word has three consonants or more to make one.
        from vocal_brief import norm_latin, transliterate
        heard = {g.lower() for g in got} | {norm_latin(transliterate(g)) for g in got}
        skel = {_skeleton(g) for g in got}
        missing = [w for w in must if w not in heard and norm_latin(transliterate(w)) not in heard
                   and not (_consonants(w) >= 3 and _skeleton(w) in skel)]
        if missing:
            return False, (f"did not sing {', '.join(repr(w) for w in missing)} (RAP_MUST_HEAR) — "
                           f"heard: {' '.join(got)[:160]}")
    return True, f"follows its reference ({coverage:.0%} of the {how})"


def _whisper_words_lang(whisper_words, media: str, cache: str,
                        prompt: str | None = None) -> list[dict]:
    """transcribe_clips.whisper_words, in the SONG's language when the store can take
    one (`language=` is Group C's parameter; until it lands this passes nothing, so
    the call shape is whatever the installed store accepts).

    PRIMED WITH THE WINDOW'S LINES when the store can take a prompt. Unprimed `small`
    heard a GOOD take of the New Era chant ("A new era over all the old era, old era",
    on the slice's clock) as "I knew where I was, all night" — 0/20 words, "invented a
    vocal" — and the redraw it forced was refused by moderation, so a landed window
    was lost (2026-08-30). Slice and take are primed identically, so a mishearing is
    at least the same mishearing on both sides."""
    import inspect
    params = inspect.signature(whisper_words).parameters
    kw = {}
    lang = os.environ.get("SONG_LANGUAGE")
    if lang and "language" in params:
        kw["language"] = lang
    if prompt and "prompt" in params:
        kw["prompt"] = prompt
    return whisper_words(media, VERIFY_MODEL, cache, **kw)["words"]


def _window_lines(job: dict) -> str | None:
    """The lines the brief says are sung in this window — the judge's whisper prompt.

    THE WINDOW'S OWN LINES ONLY. A neighbour line's fragment (partialHead/partialTail —
    the slice is muted there) primed whisper with a whole line the slice carries 0.65 s
    of, and it "heard" that line in the mute; the judge then demanded its words from
    every draw (Baby Ram & Sita w04, 2026-09-01: three draws, all correct, all refused)."""
    spans = ((job.get("vocal") or {}).get("spans") or [])
    own = [sp for sp in spans if not sp.get("partialHead") and not sp.get("partialTail")] or spans
    text = ". ".join(str(sp.get("text") or "").strip() for sp in own if sp.get("text"))
    return text[:700] or None


def _own_line_words(job: dict) -> set[str]:
    """Consonant skeletons of the words in this window's own lines (see _window_lines).
    Split on whitespace and punctuation, NOT on \\w: Devanagari matras are not \\w and a
    \\w split cut every Hindi word at its vowel signs ("काजल" -> "क", "जल"), so a correct
    RAP_MUST_HEAR was refused at startup; apostrophes and hyphens stay inside a word
    ("don't", "half-sings") the way the judge's whisper tokens carry them."""
    text = _window_lines(job) or ""
    return {_skeleton(w) for w in re.split(r"[\s,.;:!?\"()\[\]…—–]+", text) if w}


def check_must_hear_spec(plans: list[dict], wanted: set | None = None) -> None:
    """RAP_MUST_HEAR names a word for a window: the word must be IN that window's own
    lines, or every draw fails for a word it was never asked to sing. Three 40-minute
    draws went that way (w04 asked for "ooncha…", which is w03's line; 2026-09-01) —
    refuse the spec before the first render, naming the window that carries the word."""
    spec = os.environ.get("RAP_MUST_HEAR", "")
    if "=" not in spec:
        return
    jobs = [j for pl in plans for j in pl.get("jobs", [])]
    by_id = {str(j.get("id")).lower(): j for j in jobs}
    for part in spec.split(";"):
        if "=" not in part:
            continue
        jid, _, rest = part.partition("=")
        job = by_id.get(jid.strip().lower())
        if not job:
            continue
        if wanted and str(job.get("id")) not in wanted:
            continue          # a stale spec for a window this pass does not render is nobody's business
        own = _own_line_words(job)
        if not own:
            continue
        words = [w.strip() for w in rest.split(",") if w.strip()]
        stray = [w for w in words if _skeleton(w) not in own]
        if not stray:
            continue
        where = sorted({str(j2.get("id")) for j2 in jobs
                        if any(_skeleton(w) in _own_line_words(j2) for w in stray)})
        msg = (
            f"RAP_MUST_HEAR asks {job.get('id')} for {', '.join(repr(w) for w in stray)}, but "
            f"{job.get('id')}'s slice carries: \"{(_window_lines(job) or '')[:100]}\" — "
            f"{'those words are sung in ' + ', '.join(where) if where else 'no window carries those words'}. "
            f"Fix the spec; a redraw cannot sing a line that is not in its slice.")
        say("REFUSED — " + msg)          # into lane-render.log, where the runner's die message points
        raise SystemExit(msg)


def word_onset_drift(want: list[dict], got: list[dict], fuzzy: bool = False) -> dict:
    """Did the take sing the words ON THE SLICE'S CLOCK, not just the right words?

    THE DEFECT THIS CATCHES SHIPPED (2026-08-29, "Smooth Like That" w11): a take sang
    "The city hums below us and I" over 4.7s where the slice has it in 2.9s. Every word
    was right (the word check passed) and the envelope correlation locked onto the two
    syllables that happened to line up (+0ms, "on the bar") — while the operator heard
    each word land later than the last. A multiset has no clock and an envelope can
    lock anywhere; word ONSETS are the clock.

    Pairs each slice word with the take's first unpaired match (skeleton-fuzzy for a
    non-English lyric) in order, then reads the onset deltas: the median is the
    placement offset (slide fixes that), the SPREAD is the rhythm error (nothing but
    a re-render fixes that). Returns {pairs, medianMs, spreadMs, driftMs} — driftMs is
    the growth of the delta from the first paired word to the last, the signature of a
    stretched or compressed line."""
    def key(w):
        return _skeleton(w) if fuzzy else re.sub(r"[^a-z0-9']", "", w.lower())
    gi, deltas = 0, []
    for w in want:
        k = key(w["w"])
        if not k:
            continue
        for j in range(gi, len(got)):
            g = key(got[j]["w"])
            if g and (g == k or (fuzzy and _skeleton_coverage([k], [g]) >= 0.7)):
                deltas.append((float(got[j]["t"]) - float(w["t"])) * 1000.0)
                gi = j + 1
                break
    if len(deltas) < 3:
        return {"pairs": len(deltas), "medianMs": None, "spreadMs": None, "driftMs": None}
    from sync_profile import iqr_spread
    med = int(round(sorted(deltas)[len(deltas) // 2]))
    return {"pairs": len(deltas), "medianMs": med,
            "spreadMs": int(round(iqr_spread([int(d) for d in deltas]))),
            "driftMs": int(round(deltas[-1] - deltas[0]))}


# A take whose paired word onsets spread more than this is singing at the WRONG
# RHYTHM: a slide moves every word by the same amount and cannot fix it. Calibrated on
# the case above (drift +1300ms over 7 words, spread ~700ms); a good take reads <150ms.
WORD_DRIFT_MAX_MS = 500

def own_spans(plan: dict, job: dict) -> list[tuple[float, float]]:
    """[(start, end)] window-relative seconds where THIS face sings, from the brief the
    planner wrote onto the job (`vocal.spans`); [] when unknown (whole window judged)."""
    spans = (job.get("vocal") or {}).get("spans") or []
    if not spans:
        return []
    who = job.get("performer") or "a"
    spans = [sp for sp in spans if not sp.get("partialHead") and not sp.get("partialTail")]   # a neighbour line's fragment
    if who == "both":
        return [(float(sp["start"]), float(sp["end"])) for sp in spans if sp["end"] > sp["start"]]
    prons = [x.strip() for x in (plan.get("pronouns") or "he").split("|")]
    pron = prons[1 if who == "b" else 0] if len(prons) > (1 if who == "b" else 0) else "he"
    gender = {"he": "male", "she": "female"}.get(pron, "lead")
    if any(sp.get("who") in ("a", "b") for sp in spans):
        gender = who                     # a letter-tagged sheet: the performer IS the voice
    out = [(float(sp["start"]), float(sp["end"])) for sp in spans
           if sp.get("who") in ("both", "duet", "lead", gender) and sp["end"] > sp["start"]]
    return out


def _retimable(want: list[dict], got: list[dict]) -> dict | None:
    """The fit rate_fit would find, when it says RETIME. None when rate_fit is absent,
    the words do not pair, the line is not straight, or the rate is outside its window
    (RAP_RATE_MAX raises the ceiling per pack)."""
    try:
        import rate_fit
    except ImportError:
        return None
    return rate_fit.retimable(want, got)


def judge_landed(plan: dict, job: dict, clip: str) -> dict:
    """Did this render actually follow its voice reference? Ask before keeping it.

    THE FAILURE THIS CATCHES cost half a batch. Every window carried a voice slice and
    cited it as <<<audio_1>>>, and the model followed it on some draws and invented its
    own vocal on others — measured on one film: at 8s windows 4 of 4 followed, at 14s
    only 2 of 4. A clip that ignored its reference has a mouth moving to words the song
    never sings, and the assembler muxes the SONG over the picture, so what ships is a
    man plainly lip-syncing to nothing.

    Every existing gate catches it — at `select`, HOURS later, once all eight renders
    have been paid for in single-slot queue time. Asked here it costs ~20 seconds of
    whisper and the driver can simply redraw, which it was going to do for a moderation
    refusal anyway.

    THE VOICE SLICE IS THE GROUND TRUTH. Not the song, not the lyric sheet: the slice is
    exactly what this window was asked to perform, so transcribing both sides needs no
    alignment and no assumptions about where the window sits in the track.

    Returns {ok, why, borderline, shape}. `shape` names HOW it failed (`late`, `early`,
    `invented`) or None — the driver stops redrawing when the same shape repeats, since
    two identical misses are a plan problem and not the lottery. Anything that cannot
    be measured returns ok — an unavailable check must never fail a good render.
    """
    def verdict(ok, why, borderline=False, shape=None, needs=None):
        # `needs` overrides NEEDS_FOR_SHAPE when the judge already knows the fix: a
        # rhythm take whose line is STRAIGHT is the slide stage's job (rate_fit), not
        # a re-split.
        return {"ok": ok, "why": why, "borderline": borderline, "shape": shape,
                "needs": needs}

    try:
        from transcribe_clips import whisper_words
    except ImportError:
        whisper_words = None

    voice = job.get("voiceRef")
    cache = os.path.join(plan["queueDir"], "verify-tx")
    if not voice or not os.path.isfile(voice):
        # NO VOICE MEANS NO VOCAL. The window was sent without a reference because the
        # brief says nothing is sung here, and generateAudio is off — so any words heard
        # in the clip are a vocal the model invented over an instrumental, mouthed on
        # screen. Assembly muxes the song, and what ships is mouthing over a break.
        if whisper_words is None:
            return verdict(True, "no voice reference; transcribe_clips unavailable, silence unverified")
        # A clip rendered with generateAudio off usually has NO audio stream at all —
        # the strongest possible "nothing sung" — and ffmpeg's audio extraction then
        # fails (exit 234), which read as "could not transcribe". Name it.
        probe = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "a",
                                "-show_entries", "stream=codec_type", "-of", "csv=p=0", clip],
                               capture_output=True, text=True)
        if probe.returncode == 0 and not probe.stdout.strip():
            return verdict(True, "no voice reference; the clip has no audio stream — nothing sung")
        os.makedirs(cache, exist_ok=True)
        try:
            got = _whisper_words_lang(whisper_words, clip, cache)
        except (SystemExit, subprocess.CalledProcessError, OSError) as exc:
            return verdict(True, f"no voice reference; could not transcribe ({exc}) — keeping the clip")
        if len(got) > MAX_SILENT_WORDS:
            return verdict(False, (f"sang over silence — {len(got)} words heard "
                                   f"(\u201c{' '.join(w['w'] for w in got[:8])}\u2026\u201d) on a window sent with "
                                   f"NO voice; the brief says nothing is sung here"), shape="invented")
        return verdict(True, f"no voice reference; lips verified closed ({len(got)} words heard)")
    mean_db = clip_mean_db(clip)
    if mean_db is not None and mean_db < VOICE_MIN_MEAN_DB:
        return verdict(False, (f"voice nearly SILENT — mean {mean_db:.1f} dB where a sung take reads "
                               f"≥ {VOICE_MIN_MEAN_DB:g} dB; the mouth may match but nothing is heard"),
                       shape="silent", needs="rerender:redraw")
    if whisper_words is None:
        return verdict(True, "transcribe_clips unavailable")

    os.makedirs(cache, exist_ok=True)
    # THE WORD CHECK IS ENGLISH-ONLY unless the store can take a language. transcribe_clips
    # used to force whisper to English, and on a Hindi/Hinglish vocal that TRANSLATES
    # rather than transliterates — the slice came back "Entry Pesab Chho…" and a draw
    # "I want to make you suffer", so a take that sang the right words could never
    # match. The plan says `verifyWords: false` for a non-English lyric; with
    # SONG_LANGUAGE set and a language-aware store, the words are judged in that language.
    import inspect
    lang_aware = (bool(os.environ.get("SONG_LANGUAGE"))
                  and "language" in inspect.signature(whisper_words).parameters)
    if plan.get("verifyWords", True) or lang_aware:
        try:
            lines = _window_lines(job)
            want = _whisper_words_lang(whisper_words, voice, cache, prompt=lines)
            got = _whisper_words_lang(whisper_words, clip, cache, prompt=lines)
        except (SystemExit, subprocess.CalledProcessError, OSError) as exc:
            # UNJUDGED IS NOT OK. Kept (a landed clip is worth its draws) but tagged
            # borderline so the resume path re-measures it and the needs report shows
            # it — w07 (2026-09-04) shipped with three "chhota"s because its
            # transcription was interrupted and the verdict read as a pass.
            return verdict(True, f"could not transcribe ({exc}) — kept UNJUDGED; re-measured on the next pass",
                           borderline=True)

        want = trim_reference_at_mute(want, job)
        ok, why = voice_verdict([w["w"] for w in want], [w["w"] for w in got], job_id=job.get("id"),
                                fuzzy=(os.environ.get("SONG_LANGUAGE", "en") or "en") != "en")
        # AUDIO_MODE=vocal-swap: THE TAKE'S WORDS ARE THE FILM'S WORDS. A take that sings
        # a wrong word is a redraw (once — the second miss is kept and flagged for the
        # operator's ear, verify:words), not a 97 % keep: w01 sang "old moves only,
        # unconditional lane" for "Bold moves only, untraditional lane" (2026-08-31).
        # A SHOUTED, REPEATED WORD IS JUDGED ON THE ENVELOPE (2026-09-02, w09): the
        # transcript cannot see it, the must-hear can be fooled by a homophone.
        if ok:
            shout_ok, shout_why = shout_verdict(clip, voice, job)
            if not shout_ok:
                return verdict(False, shout_why, shape="words")
            if shout_why:
                say(f"{job.get('id')}: shouts on the envelope — {shout_why}")
        if ok and raplib.audio_mode(plan) == "vocal-swap":
            missing = words_missing([w["w"] for w in want], [w["w"] for w in got],
                                    fuzzy=(os.environ.get("SONG_LANGUAGE", "en") or "en") != "en")
            if missing:
                return verdict(False, f"did not sing {', '.join(repr(w) for w in missing[:6])} — "
                                      f"heard: {' '.join(w['w'] for w in got)[:160]}", shape="words")
        if not ok and not got:
            # HEARD NOTHING IS NOT SANG NOTHING. A deaf transcription (w08 noir: whisper
            # returned 0 segments on a take singing the correct lyric) is
            # indistinguishable here from a truly vocal-less render — but the two
            # separate cleanly on TIMING: a real performance correlates against its own
            # slice, an instrumental-only render does not. So an empty transcription
            # abstains and the timing check downstream decides; an invented vocal still
            # fails above (it transcribes AS words that do not match).
            why = "transcriber heard nothing (words unjudgeable); timing decides"
            words_checked = False
        elif not ok:
            return verdict(ok, why, shape="invented")
        else:
            words_checked = True
            # RIGHT WORDS ON THE WRONG CLOCK. Onset drift is the one measure that saw the
            # stretched-line take the envelope called "on the bar"; a large spread means
            # the rhythm is wrong and only a re-render fixes it (slide cannot).
            wd = word_onset_drift(want, got, fuzzy=(os.environ.get("SONG_LANGUAGE", "en") or "en") != "en")
            if wd["spreadMs"] is not None and (wd["spreadMs"] > WORD_DRIFT_MAX_MS
                                               or abs(wd["driftMs"] or 0) > 2 * WORD_DRIFT_MAX_MS):
                return verdict(False, (f"{why}, but sings them at the WRONG RHYTHM — word onsets "
                                       f"drift {wd['driftMs']:+d}ms across {wd['pairs']} words "
                                       f"(spread {wd['spreadMs']}ms, median {wd['medianMs']:+d}ms); "
                                       f"a slide moves every word equally and cannot fix a stretched "
                                       f"line — re-render"), shape="rhythm")
            why = f"{why} (word onsets steady: spread {wd['spreadMs']}ms)" if wd["spreadMs"] is not None else why
    else:
        why = "words not judged (non-English lyric); timing decides"
        words_checked = False

    # RIGHT WORDS IS NOT RIGHT TIMING. w01 on the birthday film sang 75% of its
    # reference — a clear pass on words — while its audio sat about a second out, and
    # correlated 0.43 against the bar it has to sit on. The word check cannot see that
    # (a multiset has no clock) and the timing check cannot see a clip that sang
    # gibberish (nothing to correlate). They fail differently and both are needed.
    #
    # Left to `cut`, a clip like that is a `die`, three stages and hours later — and
    # `slide` cannot rescue it either: 500ms is past the 350ms hold that would show, and
    # its spans did not agree, so it is a re-render whichever way it is measured. Better
    # to know while the lane is still ours.
    try:
        from check_sync import best_offset
        from sync_profile import envelope
        globals().setdefault('best_offset', best_offset)
        globals().setdefault('envelope', envelope)
        span = float(job.get("seconds") or 0)
        # JUDGE ONLY THE SECONDS THIS FACE SINGS. A take was refused for a 600 ms
        # offset measured over a head that was the OTHER performer's voice (operator:
        # "the lady speaks at the beginning, but the video is of the man — the guy is
        # fine here"). Silences and the other voice are not this performer's to sync.
        mine = own_spans(plan, job)
        if mine:
            def env_of(path):
                out = []
                for a, bb in mine:
                    out.extend(envelope(path, a, bb - a))
                return out
            corr, off = best_offset(env_of(voice), env_of(clip))
        else:
            corr, off = best_offset(envelope(voice, 0, span), envelope(clip, 0, span))
    except Exception as exc:                      # noqa: BLE001 — never fail on the check
        return verdict(True, f"{why}; timing unmeasurable ({exc})")

    def shape_of():
        if corr < BORDERLINE_CORR:
            return None                      # nothing performed this bar: lottery, not shape
        # best_offset: POSITIVE = the mouth is EARLY (sync_shift delays the video to fix
        # it). This line had the words swapped for a day; the stop rule compares labels
        # so it still stopped, but every log line and a night's diagnosis read backwards.
        return "early" if off > SHAPE_OFFSET_MS else "late" if off < -SHAPE_OFFSET_MS else None

    def try_salvage(reason: str):
        """Right words, head on the bar, drift confined to the tail -> keep + cover."""
        if not (SALVAGE and words_checked):
            return None
        try:
            rows = []
            for k in range(int(span // STABILITY_SPAN_S)):
                t0 = k * STABILITY_SPAN_S
                if t0 + STABILITY_SPAN_S > span:
                    break
                if mine and not any(a <= t0 and t0 + STABILITY_SPAN_S <= bb for a, bb in mine):
                    continue
                c3, o3 = best_offset(envelope(voice, t0, STABILITY_SPAN_S),
                                     envelope(clip, t0, STABILITY_SPAN_S))
                rows.append((t0, c3, o3))
            picked = salvage_plan(rows, span)
        except Exception:                 # noqa: BLE001 — salvage must never crash a judge
            return None
        if not picked:
            return None
        lo, hi = picked
        path = _write_salvage(plan, job, lo, hi)
        return verdict(True, (f"{why}; SALVAGED — head on the bar, {reason}; the drifting "
                              f"{lo:.1f}–{hi:.1f}s tail goes to B-roll cover "
                              f"({os.path.basename(path)}) instead of a redraw"),
                       borderline=True)

    if corr < BORDERLINE_CORR:
        # A TIME-STRETCHED TAKE CANNOT CORRELATE — and a retime, not a cut point, is its
        # fix. A take singing every word on a STRAIGHT LINE at 1.10-1.15x reads 0.32-0.42
        # here for exactly the reason it is fixable: the envelope of a slow performance
        # never lines up with the slice's. Four New Era draws were parked this way while
        # rate_fit (the slide stage) would have retimed them (w05, w07, w12x2, 2026-08-30;
        # the operator watched the x0.74 probe: "retime looks perfect"). So before the
        # reject, fit the rate: a straight line within the retime ceiling is a KEPT
        # `rhythm` take that the slide stage handles, not a lost render.
        if words_checked:
            fitted = _retimable(want, got)
            if fitted:
                return verdict(False, (f"{why}, sung at {fitted['rate']:.2f}x the track's speed "
                                       f"(a straight line: residual {fitted['residualMs']}ms over "
                                       f"{fitted['pairs']} words) — the envelope cannot correlate "
                                       f"({corr:.2f}) until it is retimed; rate_fit in `slide` "
                                       f"fixes this without a redraw"), shape="rhythm", needs="slide")
        s = try_salvage(f"whole-window corr {corr:.2f} dragged down by the tail")
        if s:
            return s
        return verdict(False, (f"sings the right words at the WRONG TIME — correlates "
                               f"{corr:.2f} against its own voice slice at {off:+d}ms "
                               f"({_early_late(off)}; needs {MIN_TIMING_CORR}); no cut point fixes that"))
    # A GOOD CORRELATION AT A BAD OFFSET IS STILL A RE-RENDER. Correlation says the clip
    # is performing this bar; the OFFSET says how far off it sits, and `slide` — the free
    # fix — can only take up MAX_HOLD_MS before the held frame is visible. Past that the
    # verdict at sync-gate is "needs re-render" no matter how clean the correlation is.
    #
    # Three of the first six draws measured +575, -425 and +1050ms, all beyond reach. On
    # a bar of correlation alone the driver would have kept two clips that ship half a
    # second out of sync, and nothing would say so until sync-gate, three stages later,
    # with the lane long since given up.
    # SOURCE SLACK CHANGES THE REACH. A window rendered with head/tail slack (make_plan
    # --slack-head/--slack-tail; the last window's trimStartSec is head slack too) lets
    # `slide` correct from REAL frames; only the remainder past the slack is a held
    # frame, and only that remainder is held to the ceiling (sync_shift.slack_plan).
    from sync_shift import slack_plan
    head = float(job.get("trimStartSec") or 0.0)
    tail = float(job.get("tailSec") or 0.0)
    hold_needed = slack_plan(int(off), head, tail)[1]
    if hold_needed > MAX_SLIDEABLE_MS:
        s = try_salvage(f"median offset {off:+d}ms lives in the tail")
        if s:
            return s
        return verdict(False, (f"correlates {corr:.2f} but sits {off:+d}ms off the bar ({_early_late(off)}), "
                               + (f"{abs(off) - hold_needed}ms of it covered by the clip's own slack, still "
                                  if (head or tail) else "")
                               + f"past the {MAX_SLIDEABLE_MS}ms `slide` can take up without the "
                               f"held frame showing — it would need a re-render anyway"),
                       shape=shape_of())

    # AN OFFSET SLIDE *CAN* ABSORB IS NOT AN OFFSET SLIDE *WILL* ABSORB. `slide` refuses
    # to shift a take whose offset WANDERS — it needs several sub-spans agreeing within
    # MAX_SPREAD_MS, because a median drawn from disagreeing samples moves the clip by
    # the wrong amount and makes it worse. So a wandering clip inside the 350ms reach
    # passed this gate, was left unshifted by slide, and shipped at its full offset with
    # nothing left to fix it.
    #
    # That is not hypothetical: w01 measured 0.89 @ +250ms with 325ms of spread, was
    # accepted here TWICE — once on a render and once on a recovery — and reached the
    # operator both times. Apply the same stability test slide applies, so "accepted"
    # means "the next stage can actually fix this".
    borderline = corr < MIN_TIMING_CORR
    span_bar = BORDERLINE_CORR if borderline else MIN_TIMING_CORR
    offs = []
    for k in range(int(span // STABILITY_SPAN_S)):
        t0 = k * STABILITY_SPAN_S
        if t0 + STABILITY_SPAN_S > span:
            break
        if mine and not any(a <= t0 and t0 + STABILITY_SPAN_S <= bb for a, bb in mine):
            continue          # a stability span must sit inside the performer's own singing
        c2, o2 = best_offset(envelope(voice, t0, STABILITY_SPAN_S),
                             envelope(clip, t0, STABILITY_SPAN_S))
        if c2 >= span_bar:
            offs.append(o2)
    from sync_profile import iqr_spread   # the SAME robust spread slide uses
    spread = iqr_spread(offs) if len(offs) >= SLIDE_MIN_SPANS else None
    if RELAXED and spread is not None and spread > SLIDE_MAX_SPREAD_MS and abs(off) > 80:
        return verdict(True, (f"{why}, WANDERS ({len(offs)} spans disagree by {spread}ms around "
                              f"{off:+d}ms) — kept under RAP_BAR=keep; cover/B-roll hides the worst of it"),
                       borderline=True)
    if spread is not None and spread > SLIDE_MAX_SPREAD_MS and abs(off) > 80:
        return verdict(False, (f"WANDERS — {len(offs)} spans disagree by {spread}ms "
                               f"(limit {SLIDE_MAX_SPREAD_MS}ms) around {off:+d}ms, so "
                               f"`slide` will refuse to shift it and nothing downstream "
                               f"fixes it; only a re-render will"), shape=shape_of())
    if borderline:
        # BORDERLINE IS KEPT ONLY WHEN IT IS PROVABLY FIXABLE. Relaxing the bar to 0.50
        # without a measured stability is an auto-accept dressed as a judgment: a 0.55
        # clip rarely has spans clearing 0.60, so "too few spans" would read as stable.
        if spread is None and abs(off) <= NO_SLIDE_NEEDED_MS:
            # Stability is what makes a SLIDE safe. At an offset this small there is no
            # slide to make, so "cannot measure stability" is not a reason to refuse: a
            # 5 s window (two spans) landed 0.59 @ +25ms and was parked for it.
            return verdict(True, (f"{why}, BORDERLINE (corr {corr:.2f} @ {off:+d}ms, "
                                  f"{len(offs)} spans — too few to measure spread, but "
                                  f"nothing needs sliding) — kept and tagged"), borderline=True)
        if spread is None and RELAXED:
            return verdict(True, (f"{why}, BORDERLINE (corr {corr:.2f} @ {off:+d}ms, stability "
                                  f"unmeasured) — kept under RAP_BAR=keep"), borderline=True)
        if spread is None:
            return verdict(False, (f"borderline ({corr:.2f} @ {off:+d}ms) and its stability "
                                   f"cannot be measured ({len(offs)} spans at {span_bar}) — "
                                   f"not keepable on a relaxed bar"), shape=shape_of())
        return verdict(True, (f"{why}, BORDERLINE (corr {corr:.2f} @ {off:+d}ms, "
                              f"{len(offs)} spans within {spread}ms) — kept and tagged; "
                              f"slide can take it up"), borderline=True)
    return verdict(True, f"{why}, on the bar (corr {corr:.2f} @ {off:+d}ms)")


def _early_late(off_ms: int) -> str:
    """best_offset's sign in words: positive = the mouth is EARLY, negative = LATE."""
    if abs(off_ms) <= 100:
        return "on the bar"
    return "mouth EARLY, rushing ahead of the track" if off_ms > 0 else "mouth LATE, behind the track"


def verify_landed(plan: dict, job: dict, clip: str) -> tuple[bool, str]:
    """(keep, why) — the judgment as a pair, for the resume and recovery paths.

    KEEP MEANS THE SAME THING ON EVERY PATH. The render path keeps a take that landed
    with a SHAPE (rhythm / early / late): placement is a slide, a stretched line is
    rate_fit's job in `slide`, and the same prompt drawn again fails the same way. The
    resume path judged with `ok` alone, so re-running the runner after a finished
    render parked THIRTEEN good New Era takes and queued 6.5 hours of redraws for
    windows whose fix is a retime (2026-08-30). A shape the render path keeps, resume
    keeps.
    """
    v = judge_landed(plan, job, clip)
    keep = v["ok"] or (v.get("shape") in NEEDS_FOR_SHAPE)
    return keep, v["why"]


def submission_id(plan: dict, job: dict) -> str:
    """What this submission IS: prompt, references and duration.

    A recorded job may belong to a DIFFERENT plan. Today one did — a window rendered
    against a 29-second film's prompt was still in flight when the film was re-planned
    to cover the whole song. Landing its clip because the window id matched would have
    put footage from another edit into this one, silently, which is the worst outcome
    available. So the record carries what it was made from and reconciliation refuses
    anything that does not match.
    """
    # Reference CONTENTS, not basenames. `voice/w08.mp4` kept its name across a
    # re-plan while its audio moved 12 seconds; by name the two were the same job.
    # (Existing records carry the old name-keyed id and will simply render fresh.)
    refs = []
    for r in (job.get("identityRef"), job.get("identityRef2"), job.get("identityRef3"), job.get("voiceRef")):
        if r:
            refs.append(_sha256_file(r) if os.path.isfile(r) else os.path.basename(r))
    blob = "\x00".join([job.get("prompt", ""), str(job.get("seconds", plan.get("seconds"))),
                         plan.get("aspect", ""), plan.get("resolution", ""), *refs])
    return hashlib.md5(blob.encode("utf-8")).hexdigest()[:12]


def reconcile(plan: dict, job: dict, adapter: str, lane: Lane) -> bool:
    """Recover a job this driver already submitted but never saw finish.

    There is NO CANCEL ENDPOINT. A driver killed mid-poll leaves its job running: it
    keeps the provider's single free slot, and the clip it produces is thrown away
    because the next run submits a fresh one. Measured today: a killed driver cost
    ~25 minutes of HTTP 429 while the next attempt fought the slot its own abandoned
    job was holding.

    So before submitting anything, poll what is already ours. Needs no lane ticket —
    the job is submitted, the slot is already spent.
    """
    jid = job["id"]
    record_path = os.path.join(plan["queueDir"], f"{jid}-live-job.json")
    if not os.path.isfile(record_path):
        return False
    try:
        rec = json.load(open(record_path, encoding="utf-8"))
    except (OSError, ValueError):
        return False
    if rec.get("state") != "accepted-by-provider" or not rec.get("providerJobId"):
        return False
    if rec.get("submissionId") != submission_id(plan, job):
        say(f"{jid}: an earlier job exists but was submitted from a DIFFERENT plan "
            f"(prompt/refs/duration changed) — ignoring it and rendering fresh.")
        return False

    say(f"{jid}: an earlier submission is unaccounted for (job {rec['providerJobId']}) "
        f"— polling it before spending the slot again.")
    work = os.path.join(plan["queueDir"], "work", jid)
    os.makedirs(work, exist_ok=True)
    status = poll(adapter, plan, work, rec["providerJobId"], rec.get("ticketId") or "", lane)
    if status == "completed" and land(work, clip_path(plan, job)):
        # RECOVERED IS NOT EXEMPT. This path used to land the clip and return, skipping
        # the voice check the render path does — so a recovered window could be the one
        # that ignored its reference and nothing would ever look. A second route around
        # a gate is the same bug as having no gate.
        ok, why = verify_landed(plan, job, clip_path(plan, job))
        if ok:
            say(f"{jid}: RECOVERED from the earlier submission — no new render needed. "
                f"({why})")
            return True
        superseded = os.path.join(plan["queueDir"], "superseded")
        os.makedirs(superseded, exist_ok=True)
        os.replace(clip_path(plan, job),
                   os.path.join(superseded, f"{jid}-recovered-ignored-voice.mp4"))
        say(f"{jid}: the recovered clip {why} — parking it and rendering fresh.")
        return False
    say(f"{jid}: the earlier submission ended {status}; rendering fresh.")
    return False


def salvage_plan(rows: list[tuple[float, float, int]], span: float,
                 min_cover: float = 1.0) -> tuple[float, float] | None:
    """(lo, hi) window-relative seconds to hand to B-roll cover, or None.

    rows = [(t0, corr, off_ms)] per stability span, in time order, only the
    performer's own singing. Salvageable = a good PREFIX (corr >= BORDERLINE_CORR and
    |off| <= SALVAGE_GOOD_MS, at least two spans) followed by drift; the cover runs
    from the first bad span to the end of the window. Pure — offline-testable.
    """
    if len(rows) < 3:
        return None                      # too little signal to call a head good
    n = 0
    for _t0, c, o in rows:
        if c >= BORDERLINE_CORR and abs(o) <= SALVAGE_GOOD_MS:
            n += 1
        else:
            break
    if n < 2 or n == len(rows):
        return None                      # no trustworthy head, or nothing to cover
    lo, hi = rows[n][0], span
    if hi - lo < min_cover:
        return None
    if (hi - lo) > SALVAGE_MAX_FRACTION * span:
        return None                      # would hide the performance, not rescue it
    return (lo, hi)


def _write_salvage(plan: dict, job: dict, lo: float, hi: float) -> str:
    """Record an absolute-time cover span for this window; `cover` consumes it.
    Merges by window id so re-verifies are idempotent. Returns the file path."""
    build = os.path.dirname(os.path.dirname(plan["queueDir"]))
    path = os.path.join(build, "salvage-cover.json")
    doc = {"schemaVersion": 1, "windows": {}}
    if os.path.isfile(path):
        try:
            doc = json.load(open(path, encoding="utf-8"))
        except (OSError, ValueError):
            pass
    start = float(job.get("startSec") or 0.0)
    doc.setdefault("windows", {})[job["id"]] = [[round(start + lo, 3), round(start + hi, 3)]]
    tmp = path + ".tmp"
    with open(tmp, "w", encoding="utf-8") as fh:
        json.dump(doc, fh, indent=1)
    os.replace(tmp, path)
    return path


def stale_cutaway(plan: dict, job: dict, dest: str) -> str | None:
    """Why a B-roll clip on disk does not belong to this job, or None when it does.

    The queue's provenance.json (explore_queue.write_provenance, keyed by realpath)
    records the jobId and styleId a clip was rendered for. A clip with no record, or a
    record for another world, is a stale file that kept a job's name."""
    prov_path = os.path.join(plan["queueDir"], "provenance.json")
    try:
        prov = json.load(open(prov_path, encoding="utf-8"))
    except (OSError, ValueError):
        return "has no render record (no provenance.json)"
    rec = prov.get(os.path.realpath(dest)) or prov.get(dest) or {}
    if not rec:
        return "has no render record in provenance.json"
    if rec.get("styleId") and job.get("styleId") and rec["styleId"] != job["styleId"]:
        return f"was rendered for world '{rec['styleId']}', not '{job['styleId']}'"
    if rec.get("jobId") and rec["jobId"] != job["id"]:
        return f"was rendered as {rec['jobId']}, not {job['id']}"
    return stale_prompt(plan, job, dest)


def trim_reference_at_mute(want: list[dict], job: dict) -> list[dict]:
    """The reference slice is muted from muteTailSec; anything whisper hears past it is
    the next line leaking through the mute or a hallucination — w02 read "80 % of the
    words" against a reference that carried w03's first line (New Era, 2026-08-31)."""
    # ... and from 0 to muteHeadSec: the neighbour's fragment at the head is muted too,
    # and a primed whisper still "heard" a whole line in it (w04, 2026-09-01).
    head = job.get("muteHeadSec")
    if head:
        # whisper pins a clip's FIRST word to t=0 (fit_takes), so a lone word in the
        # muted head is the line's first word, not a hallucination — keep it; a RUN of
        # words in the mute is the neighbour's line heard through the primer (w04) — drop
        # them (review finding, 2026-09-02: the first word was leaving the reference)
        in_head = [w for w in want if float(w.get("t", 0.0)) < float(head) - 0.05]
        pinned = len(in_head) == 1 and float(in_head[0].get("t", 0.0)) == 0.0
        if in_head and not pinned:
            want = [w for w in want if float(w.get("t", 0.0)) >= float(head) - 0.05]
    mute = job.get("muteTailSec")
    if mute is None:
        return want
    return [w for w in want if float(w.get("t", 0.0)) < float(mute) - 0.05]


def _latin_skeleton(token: str) -> str:
    """A romanised (Hinglish) word reduced to its consonants: vowels dropped, w/v and
    doubled letters folded. whisper romanises the SAME sung word differently from one
    recording to the next — "duaare" on the slice, "daare" on the take (film #3, w15,
    2026-09-05: two draws and a recovered clip all refused for one vowel)."""
    t = re.sub(r"[^a-z]", "", token.lower()).replace("w", "v")
    t = re.sub(r"[aeiou]+", "", t)
    return re.sub(r"(.)\1+", r"\1", t)


def words_missing(want: list[str], got: list[str], fuzzy: bool = False) -> list[str]:
    """Reference words the take did not sing, matched on consonant skeletons — the same
    ear heard both sides, so a word the slice's transcript carries and the take's does
    not is a real difference, not whisper's blind spot.

    `fuzzy` (a non-English lyric, the same seam voice_verdict uses): a romanised word
    also counts as sung when a take word shares its Latin consonant skeleton (three or
    more consonants, so "dar" cannot stand in for "duaare") or reads as the same word
    to difflib at 0.8 ("duaare"/"daare" 0.91, "rakhvaare"/"rakhwaare" 0.89)."""
    import difflib
    heard = {g.lower() for g in got} | {_skeleton(g) for g in got}
    missing = [w for w in want if w.lower() not in heard and _skeleton(w) not in heard]
    if not fuzzy or not missing:
        return missing
    # whisper also SPLITS a sung word on a token edge ("paisaare" -> "paisa re"), so
    # adjacent take words are tried joined as well.
    joined = [a + b for a, b in zip(got, got[1:])]
    latin = {_latin_skeleton(g) for g in got} | {_latin_skeleton(j) for j in joined}
    lowered = [g.lower() for g in got] + [j.lower() for j in joined]
    still = []
    for w in missing:
        sk = _latin_skeleton(w)
        if len(sk) >= 3 and sk in latin:
            continue
        if any(difflib.SequenceMatcher(None, w.lower(), g).ratio() >= 0.8 for g in lowered):
            continue
        still.append(w)
    return still


def _tag_record(plan: dict, jid: str, fields: dict) -> None:
    """Merge fields into the job's live-job record (the clip record every later layer
    reads). That record carries `doNotResubmit` and the provider job id — it must
    NEVER be overwritten from a failed read, or a later run re-sends a job the
    provider already ran. Unreadable → the verdict goes to a sidecar instead."""
    path = os.path.join(plan["queueDir"], f"{jid}-live-job.json")
    rec = None
    if os.path.isfile(path):
        try:
            rec = json.load(open(path, encoding="utf-8"))
        except (OSError, ValueError):
            rec = None
    if rec is None:
        side = os.path.join(plan["queueDir"], f"{jid}-verdict.json")
        say(f"{jid}: live-job record unreadable or absent — verdict written to {side}")
        path, rec = side, {}
    rec.update(fields)
    with open(path, "w", encoding="utf-8") as handle:
        json.dump(rec, handle, indent=1)


def parked_verdict(plan: dict, job: dict) -> str:
    """The `needs` an earlier pass left on this window's record when it parked the take
    (rerender:redraw / rerender:scrub / rerender:replan), or "" when nothing is parked.

    A PARKED WINDOW STAYS PARKED ACROSS RUNS. Every resume used to hand it a fresh draw
    budget: film #3's w06 burned ten draws over six restarts on the same refusal while
    the operator waited (2026-09-04), and one `--replace` retried it alone for four
    hours. The list walks past a parked window; spending more draws on it is the
    operator's call, made by naming it (--only / --replace), never the default."""
    jid = job["id"]
    for name in (f"{jid}-live-job.json", f"{jid}-verdict.json"):
        path = os.path.join(plan["queueDir"], name)
        if not os.path.isfile(path):
            continue
        try:
            rec = json.load(open(path, encoding="utf-8"))
        except (OSError, ValueError):
            continue
        needs = str(rec.get("needs") or "")
        if needs.startswith("rerender:"):
            return needs
    return ""


def rejudge_parked(plan: dict, job: dict) -> bool:
    """Judge a window's PARKED draws again with the current judge and promote the first
    one that lands — no submit, no slot.

    The judge's ear improves (it is now primed with the window's lines) but the takes
    it rejected are still on disk under superseded/: two good New Era windows (w00's
    chant, w05's "three hundred thousand") were parked as "ignored the voice" by an
    unprimed ear and re-read as 100% of the words by the primed one (2026-08-30).
    Newest draw first; a take that lands (ok, or a KEPT shape) moves to clips/<id>.mp4
    with a record that says it was rejudged and from which file.
    """
    jid = job["id"]
    dest = clip_path(plan, job)
    if os.path.exists(dest):
        say(f"{jid}: already on disk — nothing to rejudge")
        return True
    superseded = os.path.join(plan["queueDir"], "superseded")
    def _newest(path: str) -> tuple[int, float]:
        # THE DRAW NUMBER IS THE ORDER, mtime the tie-break. Two draws parked in the same
        # instant tie on mtime and glob order then promoted the OLDER one — a CI run
        # that passed as a pull request and failed as a push on the same commit
        # (2026-09-02). A recovered file has no draw number and sorts by time alone.
        m = re.search(r"-draw(\d+)", os.path.basename(path))
        return (int(m.group(1)) if m else -1, os.path.getmtime(path))
    cands = sorted(glob.glob(os.path.join(superseded, f"{jid}-draw*.mp4"))
                   + glob.glob(os.path.join(superseded, f"{jid}-recovered-*.mp4")),
                   key=_newest, reverse=True)
    if not cands:
        say(f"{jid}: no parked draws to rejudge")
        return False
    for clip in cands:
        v = judge_landed(plan, job, clip)
        keep = v["ok"] or (v.get("shape") in NEEDS_FOR_SHAPE)
        say(f"{jid}: rejudged {os.path.basename(clip)} -> "
            f"{'KEEP' if keep else 'still parked'} ({v['why']})")
        if not keep:
            continue
        os.makedirs(os.path.dirname(dest), exist_ok=True)
        os.replace(clip, dest)
        needs = "ok" if v["ok"] and not v.get("borderline") else (
            "slide" if v["ok"] else (v.get("needs")
                                     or NEEDS_FOR_SHAPE.get(v.get("shape") or "", "cover")))
        _tag_record(plan, jid, {"borderline": not v["ok"] or bool(v.get("borderline")),
                                "verdict": v["why"], "shape": v.get("shape"), "needs": needs,
                                "rejudged": True, "rejudgedFrom": os.path.basename(clip)})
        say(f"{jid}: -> {dest}  (promoted from superseded/ — needs: {needs})")
        return True
    return False


def render(plan: dict, job: dict, adapter: str, lane: Lane, max_draws: int) -> bool:
    jid = job["id"]
    work = os.path.join(plan["queueDir"], "work", jid)
    payload = build_payload(plan, job, work)
    dest = clip_path(plan, job)

    slot_waits = 0
    shapes: list[str | None] = []     # how each draw failed — the same shape twice is not luck
    active_variant = None             # "scrub" once the approved variant is what is being sent
    for draw in range(1, max_draws + 1):
        attempt = -1
        while True:
            attempt += 1
            if attempt >= MAX_SUBMIT_TRIES:
                say(f"{jid}: submission never accepted after {MAX_SUBMIT_TRIES} tries")
                return False
            ticket = None
            for _ in range(MAX_LANE_TRIES):
                ticket = lane.await_grant(f"{jid}-d{draw}-t{attempt}")
                if ticket:
                    break
                time.sleep(30)
            if not ticket:
                say(f"{jid}: never got the lane after {MAX_LANE_TRIES} attempts — stopping")
                return False

            job_id, task_id, issues = submit(adapter, payload)
            if task_id and not issues:
                say(f"{jid}: ACCEPTED job={job_id} task={task_id} (draw {draw})")
                # Written BEFORE the poll: if this process dies now, the record is what
                # stops a later run re-sending a job the provider is already rendering.
                with open(os.path.join(plan["queueDir"], f"{jid}-live-job.json"),
                          "w", encoding="utf-8") as handle:
                    json.dump({"window": jid, "providerJobId": job_id, "taskId": task_id,
                               "state": "accepted-by-provider", "doNotResubmit": True,
                               "ticketId": ticket, "draw": draw,
                               **({"variant": active_variant} if active_variant else {}),
                               # WHICH FACE THIS TAKE SHOWS. An archived take is only
                               # reusable for a later window if the indexer can tell
                               # whose face it carries; the morning's archives had no
                               # record of it and every one of them came back
                               # "face unknown" (2026-08-22).
                               "styleId": job.get("styleId"),
                               "performer": job.get("performer", "a"),
                               "startSec": job.get("startSec"), "seconds": job.get("seconds"),
                               "submissionId": submission_id(plan, job),
                               "submittedAt": time.strftime("%Y-%m-%dT%H:%M:%S%z")},
                              handle, indent=1)
                status = poll(adapter, plan, work, job_id, ticket, lane)
                lane.release(ticket, status, job_id, f"{jid} draw {draw}")
                say(f"{jid}: job {job_id} -> {status}")
                if status == "lease-lost":
                    # The provider job is still running; the live-job record stays so the
                    # resume path can reconcile it. The WINDOW is parked with the reason,
                    # not redrawn: a redraw now would be a second submission on a slot
                    # someone else holds — the exact collision this guard exists for.
                    say(f"{jid}: parked — needs: rerender:lease-lost (job {job_id} may still "
                        f"complete; resume reconciles it once the lane is quiet)")
                    _tag_record(plan, jid, {"needs": "rerender:lease-lost", "state": "lease-lost",
                                            "providerJobId": job_id})
                    return False
                if status == "completed":
                    if not land(work, dest):
                        say(f"{jid}: completed but produced no file")
                        return False
                    v = judge_landed(plan, job, dest)
                    if v["ok"]:
                        if v["borderline"]:
                            # Tagged on the record, said in the log: a borderline keep
                            # must never look like a clean one to whoever reads either.
                            _tag_record(plan, jid, {"borderline": True, "verdict": v["why"],
                                                    "needs": "slide"})
                            say(f"{jid}: BORDERLINE keep — {v['why']}")
                        else:
                            _tag_record(plan, jid, {"needs": "ok"})
                        say(f"{jid}: -> {dest}  ({v['why']})")
                        return True
                    if ONE_DRAW:
                        _tag_record(plan, jid, {"borderline": True, "oneDraw": True,
                                                "verdict": v["why"], "shape": v["shape"],
                                                "needs": NEEDS_FOR_SHAPE.get(v["shape"] or "", "cover")})
                        say(f"{jid}: KEPT under RAP_ONE_DRAW (judge said: {v['why']}) — "
                            f"moving on; cover/B-roll can hide it later")
                        say(f"{jid}: -> {dest}")
                        return True
                    if v["shape"] == "words" and shapes.count("words") >= 1:
                        # the second words miss: whisper may be the one mishearing —
                        # keep the take and hand the line to the operator's ear
                        _tag_record(plan, jid, {"borderline": True, "verdict": v["why"],
                                                "shape": "words", "needs": "verify:words"})
                        say(f"{jid}: KEPT after two draws with a words miss — {v['why']} — needs: verify:words (listen)")
                        say(f"{jid}: -> {dest}")
                        return True
                    if v["shape"] in NEEDS_FOR_SHAPE:
                        # A take that LANDED with a shape is KEPT. Placement is a slide,
                        # a stretched or wandering line is a cover or a re-split — the
                        # same prompt drawn again fails the same way (w11, three times).
                        needs = v.get("needs") or NEEDS_FOR_SHAPE[v["shape"]]
                        _tag_record(plan, jid, {"borderline": True, "verdict": v["why"],
                                                "shape": v["shape"], "needs": needs})
                        say(f"{jid}: KEPT with shape {v['shape']} — {v['why']} — needs: {needs} "
                            f"(no redraw: a draw of the same prompt fails the same way)")
                        say(f"{jid}: -> {dest}")
                        return True
                    # A render that ignored its voice is a BAD DRAW, not a bad prompt —
                    # the same window followed the same reference on other draws. Park
                    # it and redraw exactly as a moderation refusal would.
                    superseded = os.path.join(plan["queueDir"], "superseded")
                    os.makedirs(superseded, exist_ok=True)
                    parked = ("sang-over-silence" if not job.get("voiceRef")
                              else "ignored-voice")
                    os.replace(dest, os.path.join(
                        superseded, f"{jid}-draw{draw}-{parked}.mp4"))
                    say(f"{jid}: REJECTED draw {draw} — {v['why']}.")
                    # THE SAME SHAPE TWICE IS A PLAN PROBLEM, NOT THE LOTTERY. Moderation
                    # is random; a clip landing late twice, or inventing words twice, is
                    # the slice or the prompt — four draws of w01 came back +400, +725,
                    # +1325 and +1875ms late while the prompt told it to rap over an
                    # instrumental. Redrawing that is paying to learn it a third time.
                    shapes.append(v["shape"])
                    # Judged shapes only: a moderation refusal in between is not a shape.
                    judged = [s for s in shapes if s and s != "nsfw"]
                    if len(judged) >= 2 and judged[-1] == judged[-2]:
                        say(f"{jid}: STOPPED — plan problem, not lottery: {v['shape']} twice "
                            f"— read the slice and the prompt")
                        _tag_record(plan, jid, {"needs": "rerender:replan", "shape": v["shape"]})
                        return False
                    if draw >= max_draws:
                        say(f"{jid}: draw budget ({max_draws}) spent — the take is parked; "
                            f"needs: rerender:redraw (RAP_DRAWS=3 is the operator's call)")
                        _tag_record(plan, jid, {"needs": "rerender:redraw", "shape": v["shape"]})
                        return False
                    say(f"{jid}: redrawing; the prompt is unchanged because the prompt is "
                        f"not what failed.")
                    break
                if status == "failed":
                    shapes.append("nsfw")     # random per draw; never a stop reason
                    if ONE_DRAW and draw >= 2:
                        say(f"{jid}: moderation refused draw {draw} — RAP_ONE_DRAW allows one "
                            f"retry only; moving on (B-roll or a hand re-run can fill it)")
                        return False
                    if draw >= max_draws:
                        say(f"{jid}: moderation refused draw {draw} — draw budget ({max_draws}) "
                            f"spent; needs: rerender:scrub (rewrite the set clause, re-approve)")
                        _tag_record(plan, jid, {"needs": "rerender:scrub", "state": "refused"})
                        return False
                    variant = variant_for(plan, jid, "scrub")
                    if variant and not active_variant:
                        # THE SECOND DRAW CHANGES ONE THING: the approved scrub variant
                        # (its hash was approved with the card; recomputed here so nothing
                        # unreviewed reaches the wire).
                        payload = build_payload(plan, {**job, "prompt": variant["prompt"]}, work,
                                                payload_name="payload-scrub.json")
                        now = payload_hash(json.load(open(payload, encoding="utf-8")))
                        if now != variant["hash"]:
                            say(f"{jid}: the scrub variant no longer matches its approval "
                                f"({now[:8]} != {variant['hash'][:8]}) — not sending it; needs: rerender:scrub")
                            _tag_record(plan, jid, {"needs": "rerender:scrub", "state": "refused"})
                            return False
                        job = {**job, "prompt": variant["prompt"]}
                        active_variant = "scrub"
                        say(f"{jid}: moderation refused draw {draw} — draw {draw + 1} sends the approved "
                            f"SCRUB variant ({'; '.join(variant.get('changes') or [])})")
                    else:
                        say(f"{jid}: moderation refused draw {draw} — redrawing, prompt UNCHANGED "
                            f"(no approved scrub variant for this window)")
                    break            # a fresh submit after a terminal failure is legitimate
                return False         # timeout: the job may still be running. Do not resend.

            # No job was created. Release BEFORE waiting — never starve the other machine.
            why = "; ".join(issues)[:150] or "no taskId returned"
            low = why.lower()
            slot_busy = "429" in why or "slot stayed busy" in low or "slot is busy" in low
            lane.release(ticket, "slot-busy" if slot_busy else "not-submitted", None, f"{jid}: {why}")
            wait = BACKOFF_S[min(attempt, len(BACKOFF_S) - 1)]
            # THE PROVIDER'S OWN SLOT IS BUSY — a WAIT, not a rejection.
            #
            # HTTP 429 / "the free slot stayed busy" means someone else's render (often
            # one of OURS, abandoned mid-poll: there is no cancel endpoint, so a killed
            # driver leaves its job running and holding the slot) has the single free
            # slot. Nothing about this draw is wrong, so it must not spend a submit
            # attempt or a draw — the previous behaviour burned all 40 attempts in 15
            # minutes and then gave up on a window that was simply queued behind
            # something. It is also the failure that reads as moderation from the
            # outside; 88 slot-busy events were once diagnosed that way.
            #
            # Wait about as long as a render takes and try again, indefinitely: the slot
            # WILL free when the job in it finishes.
            if slot_busy:
                slot_waits += 1
                say(f"{jid}: the provider's single free slot is busy (attempt "
                    f"{slot_waits}) — someone's render is in it, ours or another "
                    f"machine's. Waiting {SLOT_BUSY_WAIT_S // 60}min; this costs no "
                    f"draw and no submit attempt.")
                time.sleep(SLOT_BUSY_WAIT_S)
                continue
            if "content check is taking longer" in low or "try again in a moment" in low:
                # THE PROVIDER'S CONTENT CHECK STALLED ON THIS WINDOW. It is per-window
                # (w19 three times, no other window ever, 2026-09-05) and each attempt
                # costs ~30 min of the lane before the sentence comes back. The
                # operator's rule: do not keep re-sending the same thing — park it, walk
                # on, and let the end-of-list pass (or a hand `--only w19`) try again.
                say(f"{jid}: the provider's content check stalled on this window — parked, "
                    f"moving on; needs: rerender:redraw (state content-check-stalled). "
                    f"Re-run with --only {jid} later, or scrub the set clause if it repeats.")
                _tag_record(plan, jid, {"needs": "rerender:redraw", "state": "content-check-stalled",
                                        "why": why[:200]})
                return False
            if "turnstile" in low:
                wait = TURNSTILE_WAIT_S
                say(f"{jid}: turnstile while HEADED — rate limiting, not moderation; "
                    f"retrying in {wait // 60}min rather than idling")
            elif "clerk" in low or "session" in low:
                alive = session_alive()
                if alive is False:
                    say(f"{jid}: the session is GENUINELY dead — a human must log in to "
                        f"higgsfield.ai in Chrome. Stopping rather than hammering.")
                    return False
                if alive is True:
                    wait = 60
                    say(f"{jid}: probe says session ALIVE — transient, retrying in 1min")
            say(f"{jid}: submit rejected ({why}) — lane released, waiting {wait // 60}min")
            time.sleep(wait)
    say(f"{jid}: {max_draws} draw(s) spent without a kept take — read the prompt and the "
        f"slice; the NEEDS report carries what to change")
    return False


# --------------------------------------------------------------------------
# the approval — the operator's act, bound to the bytes that will be sent
# --------------------------------------------------------------------------

APPROVAL_FILE = "submit-contract.approved"
CONTRACT_FILE = "submit-contract.json"
LOCK_FILE = "lane-render.lock"


def _pid_alive(pid: int) -> bool:
    try:
        os.kill(pid, 0)
    except ProcessLookupError:
        return False
    except PermissionError:
        return True
    return True


def take_lock(build: str) -> str:
    """One driver per project. Two runners on a single-slot lane starve each other, and
    88 slot-busy events once read as moderation failure. A lock left by a DEAD pid is
    taken over; a live one is refused."""
    path = os.path.join(build, LOCK_FILE)
    if os.path.isfile(path):
        try:
            pid = int(open(path, encoding="utf-8").read().split()[0])
        except (OSError, ValueError, IndexError):
            pid = 0
        if pid and pid != os.getpid() and _pid_alive(pid):
            die(f"another lane_render (pid {pid}) holds {path} — one driver per project; "
                f"wait for it or kill it, then re-run", 3)
    with open(path, "w", encoding="utf-8") as handle:
        handle.write(f"{os.getpid()} {time.strftime('%Y-%m-%dT%H:%M:%S%z')}\n")
    atexit.register(lambda: os.path.isfile(path) and os.remove(path))
    return path


def approval_gate(build: str, work: list[tuple[dict, dict]]) -> tuple[list, list]:
    """Keep only the jobs the operator approved, AS approved.

    `build/submit-contract.approved` is written by spend_gate.py --approve from the
    operator's own terminal and carries, per job, the hash of the exact payload the
    contract page showed (prompt, duration, shape, and the BYTES of every reference).
    The same hash is recomputed here from the payload about to be sent. A job not in
    the approval, or whose hash moved — a re-plan, a rebuilt slice, an edited prompt —
    is refused, loudly, and the rest render. Nothing is submitted without it.

    This is the gate that was kept in the agent's head and bypassed: draws went out
    against a contract nobody had looked at, twice in one day.
    """
    path = os.path.join(build, APPROVAL_FILE)
    if not os.path.isfile(path):
        die(f"no approval on disk — open {os.path.join(build, 'submit-contract.html')} "
            f"and approve (spend_gate.py --approve --hash <8 hex>, from YOUR terminal)", 3)
    try:
        approval = json.load(open(path, encoding="utf-8"))
    except (OSError, ValueError) as exc:
        die(f"approval unreadable ({exc}) — re-approve", 3)
    contract = os.path.join(build, CONTRACT_FILE)
    if not os.path.isfile(contract):
        # A missing contract must NOT skip the binding: the approval would then be checked
        # only against the per-job hashes it supplies itself, so a forged or stale
        # approval would clear. Nothing to bind to means nothing renders.
        die("submit-contract.json is missing — the approval has nothing to bind to; "
            "re-run preflight and re-approve", 3)
    if _sha256_file(contract) != approval.get("contractSha"):
        die("the contract changed since approval (submit-contract.json no longer matches "
            "the approved sha) — open the page and re-approve", 3)
    allowed = set(approval.get("allowedJobs") or [])
    hashes = approval.get("jobs") or {}
    # The approved VARIANTS (the scrub prompt for draw 2): hash from the approval,
    # prompt text from the contract it was approved against. Stashed on the plan for
    # render(); the hash is recomputed there before anything is sent.
    approved_variants = approval.get("variants") or {}
    try:
        cdoc = json.load(open(contract, encoding="utf-8"))
        contract_variants = {w["id"]: (w.get("variants") or {}) for w in cdoc.get("windows", [])}
    except (OSError, ValueError, KeyError):
        contract_variants = {}
    for plan, job in work:
        for vname, vhash in (approved_variants.get(job["id"]) or {}).items():
            cv = contract_variants.get(job["id"], {}).get(vname)
            if cv and cv.get("prompt"):
                plan.setdefault("_variants", {}).setdefault(job["id"], {})[vname] = {
                    "hash": vhash, "prompt": cv["prompt"], "changes": cv.get("changes") or []}
    kept, refused = [], []
    for plan, job in work:
        jid = job["id"]
        if jid not in allowed:
            say(f"{jid}: REFUSED — not in the approval's allowedJobs "
                f"({', '.join(sorted(allowed)) or 'none'}); approve it or narrow --only")
            refused.append(jid)
            continue
        try:
            now = payload_hash(build_payload_doc(
                plan, job, os.path.join(plan["queueDir"], "work", jid)))
        except FileNotFoundError as exc:
            say(f"{jid}: REFUSED — {exc}")
            refused.append(jid)
            continue
        if now != hashes.get(jid):
            say(f"{jid}: REFUSED — the contract changed since approval (payload hash "
                f"{now[:8]} != approved {str(hashes.get(jid))[:8]}): the prompt, the "
                f"duration or a reference's bytes moved. Re-run preflight and re-approve.")
            refused.append(jid)
            continue
        kept.append((plan, job))
    say(f"approval {approval.get('contractSha', '')[:8]} by {approval.get('approvedBy')}: "
        f"{len(kept)} job(s) cleared, {len(refused)} refused")
    return kept, refused


def prepare(path: str) -> dict:
    """load_plan + the few fields the transport needs that the validator does not."""
    plan = load_plan(path)
    project_dir = plan.get("projectDir") or os.path.dirname(os.path.dirname(os.path.abspath(path)))
    plan["projectDir"] = project_dir
    plan["slug"] = os.path.basename(project_dir.rstrip("/"))
    plan["workspaceRoot"] = (plan.get("workspaceRoot")
                             or os.path.dirname(os.path.dirname(project_dir.rstrip("/"))))
    plan["queueDir"] = plan.get("queueDir") or os.path.join(project_dir, "build", "queue",
                                                            plan.get("lane", "explore"))
    if plan["route"] != ROUTE:
        die(f"{path}: this driver renders {ROUTE} only; the plan says {plan['route']!r}")
    return plan


def main() -> None:
    global _LOG, _LANE
    _install_exit_hooks()
    ap = argparse.ArgumentParser()
    ap.add_argument("--plan", action="append", required=True,
                    help="plan.json; repeat for B-roll — one list, one slot")
    ap.add_argument("--only", default="", help="comma-separated job ids")
    ap.add_argument("--draws", type=int, default=MAX_DRAWS)
    ap.add_argument("--account", default=os.environ.get("VCLAW_LANE_ACCOUNT", "main-unlimited"))
    ap.add_argument("--dry-run", action="store_true",
                    help="resolve everything and write the real payloads; submit nothing")
    ap.add_argument("--rejudge", action="store_true",
                    help="no submit: judge each wanted window's PARKED draws again with the "
                         "current judge and promote the first that lands (see rejudge_parked)")
    ap.add_argument("--skip-session-check", action="store_true",
                    help="do not probe the login first (the probe costs nothing; skip "
                         "it only when the engine is unavailable for another reason)")
    args = ap.parse_args()

    main_repo = resolve_main()
    plans = [prepare(p) for p in args.plan]
    _LOG = os.path.join(plans[0]["projectDir"], "build", "lane-render.log")
    os.makedirs(os.path.dirname(_LOG), exist_ok=True)

    # An approved reuse edit can intentionally keep clips that do not qualify as
    # uninterrupted lip-sync takes. A stale render supervisor must not re-verify,
    # park, and replace those editorial assets after the operator has locked the cut.
    # The lock is project-scoped and deliberately checked before touching any clip.
    reuse_lock = os.path.join(plans[0]["projectDir"], "build", "reuse-cut.lock")
    if os.path.isfile(reuse_lock) and not args.dry_run:
        say(f"reuse cut locked by {reuse_lock} — provider rendering disabled; "
            "remove the lock only after explicit approval for new renders")
        raise SystemExit(0)

    wanted = {w.strip() for w in args.only.split(",") if w.strip()}
    check_must_hear_spec(plans, wanted)   # a word the window never carried fails every draw
    if args.rejudge:
        promoted = 0
        for plan in plans:
            for job in plan["jobs"]:
                if wanted and job["id"] not in wanted:
                    continue
                if rejudge_parked(plan, job):
                    promoted += 1
        say(f"=== rejudge: {promoted} window(s) on disk (no submits)")
        raise SystemExit(0)
    work: list[tuple[dict, dict]] = []
    landed = 0
    # --only NARROWS THE SUBMITS, NOT THE LOOK. Every job on disk is still verified and a
    # bad or stale clip still parked (the resume route past the gate must stay closed);
    # only the windows named are queued for the slot. The rest are reported, and the
    # runner's retry passes run without --only (review finding, 2026-09-02).
    others: list[str] = []
    parked_skipped: list[str] = []

    def _queue(plan_: dict, job_: dict, mine_: bool) -> None:
        if mine_:
            work.append((plan_, job_))
        else:
            others.append(job_["id"])

    for plan in plans:
        for job in plan["jobs"]:
            mine = not wanted or job["id"] in wanted
            dest = clip_path(plan, job)
            if os.path.exists(dest) and not REVERIFY_LANDED:
                # KEEP WHAT LANDED. Deliberate operator escape hatch, and it exists
                # because the re-verify has a cost the gate itself cannot weigh: a clip
                # it rejects for a soft offset still ASSEMBLES, and on a lane that
                # succeeds about half the time each re-render is another ~40 minutes of
                # a single slot. Against a deadline, a complete film with two soft
                # windows beats a perfect one that does not exist.
                #
                # Off by default, and it says so every time, because the honest
                # default is to re-render and the quiet default must never be the one
                # that ships a known-soft window without anybody saying so.
                say(f"{job['id']}: on disk, kept unverified (RAP_REVERIFY_LANDED=0)")
                landed += 1
                continue
            if os.path.exists(dest) and not job.get("voiceRef") and job.get("styleId"):
                # A CUTAWAY IS PINNED BY ITS RECORD, NOT ITS FILE NAME. b00.mp4 from an
                # earlier broll-plan (the studio) kept its name when the plan said
                # server-hall; both instrumental gaps showed the studio (New Era,
                # 2026-08-31). No record, or a record for another world = stale: park it.
                why_stale = stale_cutaway(plan, job, dest)
                if why_stale and not args.dry_run:
                    superseded = os.path.join(plan["queueDir"], "superseded")
                    os.makedirs(superseded, exist_ok=True)
                    os.replace(dest, os.path.join(superseded, f"{job['id']}-stale-{time.strftime('%m%d-%H%M')}.mp4"))
                    say(f"{job['id']}: the cutaway on disk {why_stale} — parked, re-rendering.")
                    _queue(plan, job, mine)
                    continue
                if why_stale:
                    say(f"{job['id']}: would be parked — {why_stale} (dry run)")
            if os.path.exists(dest) and job.get("voiceRef"):
                # A PERFORMANCE TAKE OUTLIVES A PROMPT EDIT — but never silently. It cost
                # its draws and its sync is measured; a wording change (a lemon leaving
                # her hand, a new vocal clause) does not make it wrong. Say so, name the
                # redraw command, and let the operator rank it by shipping cost.
                why_p = stale_prompt(plan, job, dest)
                if why_p:
                    say(f"{job['id']}: the take on disk {why_p} — KEPT (it earned its draws); "
                        f"--replace {job['id']} redraws it from the current prompt")
            if os.path.exists(dest):
                # RESUME IS THE THIRD ROUTE PAST THE GATE. The render path verifies and
                # the recovery path verifies, and a clip that was simply ALREADY THERE
                # sailed past both — so a bad take landed by an older driver, or by a
                # driver built before the check existed, was permanent: every later run
                # counted it as done and nothing ever looked at it again.
                #
                # That is exactly what happened here. Six clips landed under a driver
                # with only the word check, and one of them sings its words a full
                # second off the bar. Checking on resume costs ~20s a clip, once.
                ok, why = verify_landed(plan, job, dest)
                if ok:
                    say(f"{job['id']}: already on disk — {why}")
                    landed += 1
                    continue
                if args.dry_run:
                    # A DRY RUN MUST NOT MOVE FILES. This check runs while the work list
                    # is being built, which is before the --dry-run guard further down —
                    # so without this the "just show me what you would do" flag would
                    # quietly park clips on its way to saying it did nothing.
                    say(f"{job['id']}: would be REJECTED and re-rendered — {why} "
                        f"(dry run: the clip is left where it is)")
                    _queue(plan, job, mine)
                    continue
                superseded = os.path.join(plan["queueDir"], "superseded")
                os.makedirs(superseded, exist_ok=True)
                os.replace(dest, os.path.join(superseded, f"{job['id']}-resume-rejected.mp4"))
                say(f"{job['id']}: the clip already on disk {why} — parked, re-rendering.")
            parked_needs = parked_verdict(plan, job) if not os.path.exists(dest) else ""
            if parked_needs and job["id"] not in wanted:
                say(f"{job['id']}: PARKED by an earlier pass ({parked_needs}) — not redrawn; "
                    f"name it (--only {job['id']} / --replace {job['id']}) to spend more draws, "
                    f"or cover it at the cut")
                parked_skipped.append(job["id"])
                continue
            _queue(plan, job, mine)
    if others:
        say(f"--only: {len(others)} other window(s) still need a render ({', '.join(others)}) "
            f"— a pass without --only takes them")

    # DEFERRED B-roll (make_broll_plan --every-style): approved with the contract, rendered
    # only when named — the NEEDS report asks for the cutaway a cover will actually use.
    deferred = [j["id"] for _, j in work if j.get("deferred") and j["id"] not in wanted]
    if deferred:
        say(f"deferred — rendered only when the NEEDS report asks (--only): {', '.join(deferred)}")
        work = [(p, j) for p, j in work if not (j.get("deferred") and j["id"] not in wanted)]
    if parked_skipped:
        say(f"parked, left for the end: {', '.join(parked_skipped)} — decide per window "
            f"(cover / accept the parked take / redraw by name) once the list has walked")
    say(f"=== lane_render: {len(work)} to render, {landed} already on disk "
        f"({', '.join(j['id'] for _, j in work) or 'nothing'})")
    if not work:
        raise SystemExit(0)

    if args.dry_run:
        # A dry run is about the PAYLOAD, not the transport, so a machine with no
        # engine bootstrapped can still inspect exactly what would be sent. The engine
        # is still resolved, because "you have no engine" is worth knowing early —
        # it is just reported rather than fatal here.
        try:
            adapter = resolve_adapter(main_repo)
        except SystemExit:
            adapter = "UNRESOLVED — see the FATAL line above; a real run would stop there"
        # BUILD THE REAL PAYLOADS. A dry run that paraphrases what it would send is
        # worth very little — the failure this lane actually had was a payload whose
        # referenceRole silently dropped the voice, which no summary line would have
        # shown. These are the exact bytes the adapter would read on stdin.
        say(f"dry run — adapter {adapter}")
        for plan, job in work:
            path = build_payload(plan, job, os.path.join(plan["queueDir"], "work", job["id"]))
            task = json.load(open(path, encoding="utf-8"))["tasks"][0]
            say(f"  {job['id']}: {task['durationSeconds']}s {plan['aspect']} "
                f"{plan['resolution']} role={task.get('referenceRole', 'NONE')} "
                f"refs={[os.path.basename(r) for r in task['referencePaths']]} "
                f"-> {clip_path(plan, job)}")
            say(f"      payload: {path}")
        raise SystemExit(0)

    # THE THREE REFUSALS THAT NEED NO ENGINE, checked before anything is resolved so a
    # machine with no adapter still gets the right answer — and so nothing below can
    # touch the lane on a run that should not exist.
    # EVERY plan, not plans[0]: a second --plan from another project (or a -dryrun
    # copy with no approval of its own) must not ride in under the first plan's
    # approval, lock and slug check — the review's bypass hunt did exactly that.
    if len({p["projectDir"] for p in plans}) > 1 or len({p["slug"] for p in plans}) > 1:
        die("the --plan files belong to different projects/slugs — one driver, one "
            "project: run them separately so each is gated by its own approval", 3)
    build = os.path.join(plans[0]["projectDir"], "build")
    for p in plans:
        if p["slug"].endswith("-dryrun"):
            die(f"{p['slug']}: a -dryrun copy exists to prove the pipeline, never to "
                f"render — dryrun.sh marks render-all done before it runs; refusing", 3)
    take_lock(build)
    work, refused = approval_gate(build, work)
    if not work:
        say(f"=== nothing cleared to render ({len(refused)} refused) — nothing submitted")
        raise SystemExit(10)

    adapter = resolve_adapter(main_repo)
    wrapper = resolve_queue_wrapper(main_repo)

    # ASK BEFORE SPENDING HOURS. A logged-out profile refuses every draw, a few
    # minutes apart, across a shared single-slot lane — and because moderation is a
    # ~50%-per-draw coin flip, a run of refusals is exactly what moderation looks
    # like. The remedies are opposite: moderation wants another draw, a dead session
    # wants a human. Discovering that after 40 lane grants is the expensive way.
    if not args.skip_session_check:
        say("checking the Higgsfield session (read-only, spends nothing)...")
        code, detail = probe_session()
        if code == 4:
            say(f"BLOCKED: {detail}")
            say(f"  {SESSION_ADVICE}")
            say("  Nothing was submitted. Re-run once someone has logged in.")
            raise SystemExit(3)
        say(f"session: {detail}" if code == 0 else f"session check inconclusive ({detail}) "
            f"— proceeding; the first submit will settle it")

    _LANE = Lane(main_repo, wrapper, plans[0]["slug"], args.account)
    outstanding = list(refused)
    for wi, (plan, job) in enumerate(work):
        # A POLITE STOP. `touch build/STOP` ends the pass at the next boundary — after the
        # clip in flight has landed, before the next submit — instead of a kill that
        # once hit the wrong process (2026-09-04). The runner refuses to start while the
        # file exists, so a resume is an explicit act: rm build/STOP, re-run.
        stop = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(plan["queueDir"]))), "STOP")
        if os.path.exists(stop):
            rest = [j["id"] for _, j in work[wi:]]
            say(f"STOP file present ({stop}) — stopping before {job['id']} is submitted; "
                f"not rendered this pass: {', '.join(rest)}. rm it and re-run to resume.")
            outstanding.extend(rest)
            break
        say(f"--- {job['id']}")
        if reconcile(plan, job, adapter, _LANE):
            landed += 1
            continue
        if render(plan, job, adapter, _LANE, args.draws):
            landed += 1
        else:
            outstanding.append(job["id"])

    for plan in plans:
        try:
            write_provenance(plan["queueDir"], plan)
        except Exception as exc:                      # provenance is a record, not a gate
            say(f"could not write provenance for {plan['queueDir']}: {exc}")

    say(f"=== done: {landed} landed, {len(outstanding)} outstanding "
        f"({', '.join(outstanding) or 'none'})")
    raise SystemExit(10 if outstanding else 0)


if __name__ == "__main__":
    main()
