"""
Operator operations — one implementation, several front doors.

Three things ask this node to act: the CLI (over the loopback admin API), the
local admin UI, and — from Stage B3 — signed MNP messages from a paired client.
They must agree, and the way to make them agree is not to write the operation
three times and hope.

**C1 and C6 were both "a second path into the node with its own weaker
handshake."** Two implementations of `revoke` with two authorization checks is
the same shape one size down. So each operation lives here once, takes the
daemon's `state`, and knows nothing about HTTP, argv or MNP. The adapters
translate: `ui/app.py` turns `OpError` into a JSON response, the CLI prints it,
the MNP handler sends an error frame.

**Authorization is not here.** Reaching this module already means the caller got
past its adapter's check — the loopback session token (11.5.3) for the API, an
Ed25519 signature verified against the roster for MNP. These functions do what
they are told; deciding who may tell them is the adapter's job and stays visible
in the adapter.
"""

from __future__ import annotations

import asyncio
import logging
import re
from dataclasses import asdict
from pathlib import Path
from typing import Any

from meshbay_common.crypto import generate_gek, wrap_gek_aes
from meshbay_node.config import DEFAULT_CONFIG_PATH
from meshbay_common.join import ROLE_MEMBER, ROLE_OPERATOR
from meshbay_node.roots import RootError, RootSet

log = logging.getLogger(__name__)


class OpError(Exception):
    """
    An operation refused, with enough for any adapter to report it.

    `status` is an HTTP code because one adapter needs one; the others ignore it.
    `extra` carries the "here is what would have worked" payload — a bare "no
    such group" leaves an operator guessing at a UUID.
    """

    def __init__(self, message: str, *, status: int = 400,
                 extra: dict[str, Any] | None = None):
        super().__init__(message)
        self.message = message
        self.status = status
        self.extra = extra or {}

    def as_dict(self) -> dict:
        return {"error": self.message, **self.extra}


# ── Shared lookups ───────────────────────────────────────────────────────────

def _roster(state: dict):
    roster = state.get("roster")
    if not roster:
        raise OpError("Roster not available", status=503)
    return roster


def _hub(state: dict):
    hub = state.get("hub")
    if not hub or not hub._session:
        raise OpError("Hub not connected", status=503)
    return hub


def _group_ctx(state: dict, group_id: str) -> dict:
    groups_ctx = state.get("groups_ctx", {})
    if group_id not in groups_ctx:
        raise OpError("Group not hosted on this node", status=404,
                      extra={"available": [
                          {"id": gid} for gid in groups_ctx]})
    return groups_ctx[group_id]


def _config(state: dict):
    config = state.get("config")
    if not config:
        raise OpError("No config loaded", status=503)
    return config


# ── Roster ───────────────────────────────────────────────────────────────────

async def read_roster(state: dict, group_id: str = "") -> dict:
    roster = state.get("roster")
    if not roster:
        return {"identities": [], "members": [], "invites": []}
    members = await roster.list_members(group_id or None)
    members = [m for m in members if m.get("pk_ed25519") is not None]
    return {
        "identities": await roster.list_identities(),
        "members": members,
        "invites": await roster.list_invites(),
    }


async def resolve_user(state: dict, username: str) -> dict:
    """
    Map a username to an account id.

    The roster answers first — it is the node's own record. The hub is the
    fallback for identities pinned before invitations carried a name, and for
    people admitted through an open-join group. Only an account id comes back;
    no key is ever taken from there.
    """
    roster = state.get("roster")
    if roster:
        for ident in await roster.list_identities():
            if ident["username"] == username:
                return {"user_id": ident["user_id"], "source": "roster"}
    hub = state.get("hub")
    if hub and hub._session:
        try:
            account = await hub.get_user_pubkeys(username)
            return {"user_id": account["user_id"], "source": "hub"}
        except Exception:
            pass
    raise OpError(f"Unknown user {username!r}", status=404)


async def pair_operator(state: dict) -> dict:
    """
    Issue a one-time code that pairs a browser as this node's operator.

    The code is the whole point: it binds the operator's browser identity key to
    their account without asking the hub, which is what stops a hub from naming
    itself node administrator (M3, and the same substitution as H3). Returned
    once and stored only as a hash.
    """
    roster = _roster(state)
    user_id = state.get("node_user_id")
    if not user_id:
        raise OpError("Node not connected to hub yet", status=503)

    config = state.get("config")
    ttl = (config.node.pair_ttl_hours if config else 24) * 3600
    code = await roster.create_invite(
        group_id="",                 # operator authority is node-wide
        user_id=user_id,
        role=ROLE_OPERATOR,
        created_by="local-cli",
        ttl=ttl,
        username=(config.hub.username if config else ""),
    )
    invites = await roster.list_invites()
    expires = next((i["expires_at"] for i in invites
                    if i["user_id"] == user_id and i["role"] == ROLE_OPERATOR), "")
    return {"code": code, "expires_at": expires, "user_id": user_id}


async def create_invite(state: dict, group_id: str, username: str, *,
                        user_id: str = "",
                        created_by: str = "local-cli") -> dict:
    """
    Issue an invitation code.

    The hub is asked for the account id and nothing else — never for a key. A hub
    that answered with the wrong account would produce an invite whose code it
    never learns, since the code goes to a human out of band.

    When ``user_id`` is supplied directly (MNP path), the hub lookup is skipped.
    """
    roster = _roster(state)
    _group_ctx(state, group_id)
    if not user_id:
        hub = _hub(state)
        try:
            account = await hub.get_user_pubkeys(username)
        except Exception as e:
            raise OpError(f"Unknown user {username!r}: {e}", status=404) from e
        user_id = account["user_id"]

    # Hub membership first, and fatal if it fails.
    #
    # `/v1/groups/mine` joins `GroupMember`, so someone who was never registered
    # does not see the group at all and can never redeem the code. Creating the
    # invite first and tolerating a failed registration — which is what this did
    # — hands the operator a code that cannot work, and says nothing. Worse, an
    # unreachable hub raised *after* the roster write, leaving a valid code
    # nobody was ever given; every retry left another.
    #
    # Registering before the roster write means a failure costs nothing: no code
    # exists to be orphaned. A membership row without an invite is harmless —
    # without the code there is still no group key.
    #
    # The endpoint is idempotent (`if not mem: db.add(...)`, no 409), so the SPA
    # registering the same membership again right after `createInvite`
    # (group-settings.js) costs nothing either.
    #
    # Skipped only when there is no username to register with: the MNP path
    # allows an empty one (`username || ''` in transport.js), and there the SPA
    # is the one that registers.
    if username:
        try:
            await _hub(state).add_group_member(group_id, username)
        except Exception as e:
            raise OpError(
                f"Could not register {username!r} on the hub, so the invite "
                f"could not be redeemed: {e}", status=502) from e

    config = state.get("config")
    ttl = (config.node.invite_ttl_hours if config else 168) * 3600
    code = await roster.create_invite(
        group_id=group_id,
        user_id=user_id,
        role=ROLE_MEMBER,
        created_by=created_by,
        ttl=ttl,
        username=username,
    )

    invites = await roster.list_invites()
    expires = next((i["expires_at"] for i in invites
                    if i["user_id"] == user_id
                    and i["group_id"] == group_id), "")
    return {"code": code, "expires_at": expires,
            "username": username, "user_id": user_id}


async def revoke_member(state: dict, user_id: str, group_id: str) -> dict:
    """
    Stop serving the group key to someone.

    Takes effect on their next connection: the key is wrapped on demand, so there
    is no stored bundle left behind that would outlive this. Rotating the group
    key is still required — they hold the current one.
    """
    roster = _roster(state)
    if not await roster.set_status(group_id, user_id, "revoked"):
        raise OpError("No such member in that group", status=404)
    log.info("Member revoked: user=%s group=%s", user_id[:8], group_id[:8])
    return {"status": "revoked", "user_id": user_id, "group_id": group_id,
            "reminder": "rotate the group key: meshbay-node gek rotate"}


async def unpin_member(state: dict, user_id: str) -> dict:
    """Forget a pinned identity, so the person can pair again with a new key."""
    roster = _roster(state)
    if not await roster.unpin(user_id):
        raise OpError("No such pinned identity", status=404)
    # Drop the stored keypair bundle too. Left behind, it is served to the next
    # connection, which then cannot open it (the passphrase may have changed
    # since) and dies in the identity step before it ever reaches the join the
    # unpin was meant to enable.
    bundle_store = state.get("bundle_store")
    if bundle_store:
        try:
            await bundle_store.delete_keypair(user_id)
        except Exception:
            log.warning("unpin: could not drop keypair bundle for %s", user_id[:8])
    log.info("Identity unpinned: user=%s", user_id[:8])
    return {"status": "unpinned", "user_id": user_id}


# ── Group keys ───────────────────────────────────────────────────────────────

async def set_gek(state: dict, group_id: str, *, rotate: bool = False) -> dict:
    """
    Generate the group key and activate it, or rotate an existing one.

    Nothing is pre-wrapped for members. Each member's copy is produced when they
    connect, for a key they proved they hold (`join_request`) — pre-wrapping used
    to fetch public keys from the hub, which is H3 with the node as the victim
    instead of the inviter. Only the node's own copy is stored, so the daemon can
    reload the key across restarts without the operator's browser.

    **`rotate` generates a fresh key even when one exists.** That is the point of
    it: after a revocation the ex-member still holds the current key, and nothing
    else takes it away from them. Without `rotate` an existing key is kept, so
    running this twice is not destructive by accident.
    """
    ctx = _group_ctx(state, group_id)
    hub = _hub(state)

    if rotate and ctx.get("visibility") == "public":
        raise OpError(
            "Key rotation is not available for public groups", status=400)

    bundle_store = state.get("bundle_store")
    if not bundle_store:
        raise OpError("Bundle store not available", status=503)

    existing = ctx.get("gek")
    gek = generate_gek() if (rotate or not existing) else existing
    rotated = bool(existing) and gek is not existing
    errors: list[str] = []

    roster = state.get("roster")
    authorized = len(await roster.list_members(group_id)) if roster else 0

    node_user_id = hub._session.user_id if hub._session else None
    pk_x_node_raw = state.get("pk_x25519_raw")
    if pk_x_node_raw and node_user_id:
        try:
            node_bundle = wrap_gek_aes(gek, pk_x_node_raw)
            await bundle_store.store(
                group_id, f"_node_{node_user_id}",
                node_bundle["pk_eph_b64"], node_bundle["nonce_b64"],
                node_bundle["wrapped_b64"],
            )
            log.info("GEK wrapped for node keystore (daemon reload)")
        except Exception as e:
            errors.append(f"node keystore: {e}")
            log.warning("Failed to wrap GEK for node keystore: %s", e)

    ctx["gek"] = gek
    log.info("GEK %s for group %s — %d authorized member(s) will receive it "
             "on connect", "rotated" if rotated else "initialized",
             group_id[:8], authorized)

    # The transport holds its own view of the group; a rotation that did not
    # reach it would keep serving the old key until the daemon restarted.
    for transport_key in ("webrtc", "quic_server"):
        transport = state.get(transport_key)
        groups = getattr(transport, "_ctx", {}).get("groups") if transport else None
        if groups and group_id in groups:
            groups[group_id]["gek"] = gek

    indexes = state.get("indexes") or {}
    index = indexes.get(group_id)
    if index is not None:
        # The index is encrypted under the GEK; leaving the old key on it would
        # serve members a listing they cannot open.
        index.gek = gek

    return {
        "status": "rotated" if rotated else "ok",
        "group_id": group_id,
        "rotated": rotated,
        "authorized_members": authorized,
        "errors": errors,
    }


# ── Groups and roots ─────────────────────────────────────────────────────────

async def list_groups(state: dict) -> dict:
    """What this node hosts, with live status. Milestone 14.2."""
    config = state.get("config")
    groups_ctx = state.get("groups_ctx", {})
    peers = state.get("peers") or {}
    out = []
    for gid, ctx in groups_ctx.items():
        cfg = next((g for g in config.groups if g.id == gid), None) if config else None
        idx = ctx.get("index")
        roots = ctx.get("roots")
        out.append({
            "id": gid,
            "name": cfg.name if cfg else gid[:8],
            "visibility": cfg.visibility if cfg else "private",
            "join_policy": cfg.join_policy if cfg else "invite",
            "has_gek": bool(ctx.get("gek")),
            "file_count": idx.count if idx else 0,
            "index_version": idx.version if idx else 0,
            "roots": roots.describe() if roots else [],
            "peers": sum(1 for p in peers.values() if p.get("group_id") == gid),
        })
    roster = state.get("roster")
    has_operator = False
    if roster:
        members = await roster.list_members()
        has_operator = any(m["role"] == "operator" and m["status"] == "active"
                          for m in members)
    from meshbay_node.config import DEFAULT_STUN_SERVERS
    nd = config.node if config else None
    defaults = {
        "invite_ttl_hours": nd.invite_ttl_hours if nd else 168,
        "pair_ttl_hours": nd.pair_ttl_hours if nd else 24,
        "device_request_ttl_minutes": nd.device_request_ttl_minutes if nd else 60,
        "max_concurrent_streams": nd.max_concurrent_streams if nd else 8,
        "transcode_incompatible_video": nd.transcode_incompatible_video if nd else True,
        "stun_servers": nd.stun_servers if nd and nd.stun_servers else list(DEFAULT_STUN_SERVERS),
        "ice_interfaces": nd.ice_interfaces if nd else [],
    }
    if roster:
        settings = await roster.node_settings(defaults)
    else:
        settings = defaults
    return {"groups": out, "operator_paired": has_operator, "settings": settings}


async def attach_group(state: dict, name: str, shared_dir: str,
                       upload_dir: str = "", writable: bool = True) -> dict:
    """
    Write a new [[groups]] block into node.toml.

    The name-to-id lookup happens here because this process is the one logged
    into the hub. Nothing is created on the hub: the group already exists, this
    only tells the node to host it.
    """
    if not name or not shared_dir:
        raise OpError("name and shared_dir are required")
    config = _config(state)
    hub = _hub(state)
    try:
        mine = await hub.list_my_groups()
    except Exception as e:
        raise OpError(f"Could not list groups: {e}", status=502) from e

    match = [g for g in mine if g["id"] == name or g["name"] == name]
    if not match:
        raise OpError(f"No group of yours is called {name!r}", status=404,
                      extra={"available": [{"name": g["name"], "id": g["id"]}
                                           for g in mine]})
    if len(match) > 1:
        raise OpError(f"Several of your groups are called {name!r} — use the id",
                      status=409,
                      extra={"available": [{"name": g["name"], "id": g["id"]}
                                           for g in match]})
    group = match[0]

    if any(g.id == group["id"] for g in config.groups):
        raise OpError(f"{group['name']!r} is already hosted by this node", status=409)

    path = Path(shared_dir).expanduser()
    try:
        path.mkdir(parents=True, exist_ok=True)
    except OSError as e:
        raise OpError(f"Cannot create {path}: {e}") from e

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    join_policy = group.get("join_policy", "invite")
    block = (f'\n[[groups]]\n'
             f'id          = "{group["id"]}"\n'
             f'name        = "{group["name"]}"\n'
             f'visibility  = "{group.get("visibility", "private")}"\n'
             f'join_policy = "{join_policy}"\n')
    # Legacy: upload_dir becomes a second writable root
    if upload_dir:
        upload_path = Path(upload_dir).expanduser().resolve()
        if upload_path != path.resolve():
            try:
                upload_path.mkdir(parents=True, exist_ok=True)
            except OSError as e:
                raise OpError(f"Cannot create {upload_path}: {e}") from e
            block += f'upload_dir  = "{upload_path.as_posix()}"\n'
    block += (f'\n  [[groups.roots]]\n'
              # Forward slashes: a Windows path in a TOML basic string is a
              # parse error (`\U`, `\a`, ... are escapes). pathlib reads `/`.
              f'  path     = "{path.as_posix()}"\n'
              f'  writable = {"true" if writable else "false"}\n')
    try:
        with conf_path.open("a", encoding="utf-8", newline="\n") as f:
            f.write(block)
    except OSError as e:
        raise OpError(f"Cannot write {conf_path}: {e}", status=500) from e

    result = {"group_id": group["id"], "name": group["name"],
              "shared_dir": str(path), "config": str(conf_path),
              "writable": writable,
              "note": "restart the node to pick it up"}
    return result


async def detach_group(state: dict, name: str) -> dict:
    """
    Remove a [[groups]] block from node.toml.

    Does not touch the hub — only stops this node from hosting the group
    after the next reload or restart.
    """
    if not name:
        raise OpError("group name or id is required")
    config = _config(state)

    match = [g for g in config.groups if g.id == name or g.name == name]
    if not match:
        raise OpError(f"No hosted group matches {name!r}", status=404,
                      extra={"available": [{"name": g.name, "id": g.id}
                                           for g in config.groups]})
    group = match[0]

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    text = conf_path.read_text(encoding="utf-8")
    lines = text.split("\n")

    rng = _find_group_range(lines, group.id)
    if rng is None:
        raise OpError(f"Group {group.id[:8]} not found in {conf_path}")

    start, end = rng
    while end < len(lines) and lines[end].strip() == "":
        end += 1

    new_lines = lines[:start] + lines[end:]
    conf_path.write_text("\n".join(new_lines), encoding="utf-8", newline="\n")
    log.info("Group detached: %s (%s) removed from %s", group.name, group.id[:8], conf_path)

    return {"group_id": group.id, "name": group.name, "config": str(conf_path),
            "note": "restart the node to stop hosting it"}


def _find_group_range(lines: list[str], group_id: str) -> tuple[int, int] | None:
    """Line range of a [[groups]] block by id: (start, end_exclusive)."""
    id_re = re.compile(r'^\s*id\s*=\s*"([^"]*)"')
    block_starts: list[int] = []
    for i, line in enumerate(lines):
        if line.strip() == "[[groups]]":
            block_starts.append(i)

    for j, start in enumerate(block_starts):
        boundary = block_starts[j + 1] if j + 1 < len(block_starts) else len(lines)
        for k in range(start + 1, boundary):
            s = lines[k].strip()
            if s.startswith("[") and s != "[[groups.roots]]":
                boundary = k
                break
        for k in range(start + 1, boundary):
            m = id_re.match(lines[k])
            if m and m.group(1) == group_id:
                return (start, boundary)
    return None


def _update_node_toml(conf_path: Path, updates: dict) -> None:
    """Write changed [node] settings back to node.toml without disturbing comments.

    For each key, if the line exists (commented or not) it is replaced in place;
    otherwise the key is appended to the end of the [node] section.
    """
    if not conf_path.exists():
        return
    text = conf_path.read_text(encoding="utf-8")
    lines = text.split("\n")

    node_start = None
    node_end = len(lines)
    for i, line in enumerate(lines):
        stripped = line.strip()
        if stripped == "[node]":
            node_start = i
        elif node_start is not None and re.match(r'^\[', stripped):
            node_end = i
            break

    if node_start is None:
        lines.append("")
        lines.append("[node]")
        node_start = len(lines) - 1
        node_end = len(lines)

    def _format_value(key, value):
        if isinstance(value, bool):
            return f"{key} = {'true' if value else 'false'}"
        if isinstance(value, list):
            items = ", ".join(f'"{v}"' for v in value)
            return f"{key} = [{items}]"
        return f"{key} = {value}"

    remaining = dict(updates)
    for i in range(node_start + 1, node_end):
        for key in list(remaining):
            pattern = re.compile(
                r'^(\s*#?\s*)' + re.escape(key) + r'\s*=\s*.*$')
            if pattern.match(lines[i]):
                value = remaining.pop(key)
                lines[i] = _format_value(key, value)
                break

    for key, value in remaining.items():
        lines.insert(node_end, _format_value(key, value))
        node_end += 1

    conf_path.write_text("\n".join(lines), encoding="utf-8", newline="\n")


def _insert_roots_block(conf_path: Path, group_id: str,
                        root_block: str) -> None:
    """Append a [[groups.roots]] block inside the matching [[groups]] section."""
    text = conf_path.read_text(encoding="utf-8")
    lines = text.split("\n")

    rng = _find_group_range(lines, group_id)
    if rng is None:
        raise OpError(f"Group {group_id[:8]} not found in {conf_path}")

    _start, end = rng
    insert_at = end
    while insert_at > _start + 1 and lines[insert_at - 1].strip() == "":
        insert_at -= 1

    new_lines = (lines[:insert_at]
                 + [""]
                 + root_block.rstrip("\n").split("\n")
                 + lines[insert_at:])
    conf_path.write_text("\n".join(new_lines), encoding="utf-8", newline="\n")


def _remove_roots_block(conf_path: Path, group_id: str,
                        resolved_path: str) -> None:
    """Remove a [[groups.roots]] block whose resolved path matches."""
    text = conf_path.read_text(encoding="utf-8")
    lines = text.split("\n")

    rng = _find_group_range(lines, group_id)
    if rng is None:
        raise OpError(f"Group {group_id[:8]} not found in {conf_path}")

    start, end = rng
    path_re = re.compile(r'^\s*path\s*=\s*"([^"]*)"')
    roots_starts: list[int] = []
    for i in range(start + 1, end):
        if lines[i].strip() == "[[groups.roots]]":
            roots_starts.append(i)

    for j, rs in enumerate(roots_starts):
        rs_end = roots_starts[j + 1] if j + 1 < len(roots_starts) else end
        for k in range(rs, rs_end):
            m = path_re.match(lines[k])
            if m:
                try:
                    p = str(Path(m.group(1)).expanduser().resolve())
                except OSError:
                    continue
                if p == resolved_path:
                    rm_start = rs
                    if rm_start > 0 and lines[rm_start - 1].strip() == "":
                        rm_start -= 1
                    new_lines = lines[:rm_start] + lines[rs_end:]
                    conf_path.write_text("\n".join(new_lines), encoding="utf-8", newline="\n")
                    return

    raise OpError("Root path not found in config", status=404)


async def add_root(state: dict, group_id: str, path: str, *,
                   name: str = "", kind: str = "generic",
                   writable: bool = False,
                   removable: bool = False) -> dict:
    """
    Add a directory to a group, refusing anything ambiguous.

    Validated against the group's existing roots *before* being written, so a
    config that would be refused at startup is refused here instead — where the
    operator is watching and can fix it.
    """
    config = _config(state)
    cfg = next((g for g in config.groups if g.id == group_id), None)
    if cfg is None:
        raise OpError("Group not configured on this node", status=404)

    specs = [asdict(r) for r in cfg.roots]
    specs.append({"path": path, "name": name, "kind": kind,
                  "writable": writable, "removable": removable})
    try:
        built = RootSet.build(specs)
    except RootError as e:
        raise OpError(str(e)) from e

    added = built.roots[-1]

    try:
        added.path.mkdir(parents=True, exist_ok=True)
    except OSError as e:
        raise OpError(f"Cannot create {added.path}: {e}") from e

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    root_block = f'  [[groups.roots]]\n  path   = "{added.path.as_posix()}"'
    if name:
        root_block += f'\n  name   = "{added.name}"'
    if kind != "generic":
        root_block += f'\n  kind   = "{added.kind}"'
    if writable:
        root_block += '\n  writable = true'
    if removable:
        root_block += '\n  removable = true'
    _insert_roots_block(conf_path, group_id, root_block)

    from meshbay_node.config import RootSpec
    cfg.roots.append(RootSpec(
        path=str(added.path), name=added.name, kind=added.kind,
        writable=added.writable, removable=added.removable,
        direct=added.direct))

    log.info("Root added: %s → group %s", added.name, group_id[:8])
    return {"status": "added", "name": added.name, "path": str(added.path),
            "group_id": group_id, "roots": built.describe()}


async def remove_root(state: dict, group_id: str, root_name: str) -> dict:
    """Remove a named root from a group. At least one root must remain."""
    config = _config(state)
    cfg = next((g for g in config.groups if g.id == group_id), None)
    if cfg is None:
        raise OpError("Group not configured on this node", status=404)

    from meshbay_common.paths import fold
    from meshbay_node.roots import derive_name
    target = fold(root_name)
    match_idx = None
    for i, r in enumerate(cfg.roots):
        try:
            rname = r.name or derive_name(Path(r.path).expanduser().resolve())
        except Exception:
            continue
        if fold(rname) == target:
            match_idx = i
            break

    if match_idx is None:
        raise OpError(f"No root named {root_name!r} in this group", status=404)
    if len(cfg.roots) < 2:
        raise OpError("Cannot remove the only root", status=400)

    removed = cfg.roots[match_idx]
    resolved = str(Path(removed.path).expanduser().resolve())

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    _remove_roots_block(conf_path, group_id, resolved)

    cfg.roots.pop(match_idx)

    # Update the live RootSet so GET /api/groups returns correct data
    # immediately, without waiting for the async reload.
    live_roots = state.get("groups_ctx", {}).get(
        group_id, {}).get("roots")
    if live_roots:
        live_roots.roots = [
            r for r in live_roots.roots if fold(r.name) != target]

    # Built from config when there is no live set, never returned empty: an
    # empty list is a *valid answer* meaning "this group has no directories",
    # and the client cannot tell it from "the node could not say". It would
    # blank the operator's table on an op that succeeded.
    result_roots = (live_roots.describe() if live_roots
                    else RootSet.build([asdict(r) for r in cfg.roots]).describe())

    log.info("Root removed: %s from group %s", root_name, group_id[:8])
    return {"status": "removed", "name": root_name, "group_id": group_id,
            "roots": result_roots}


async def update_root(state: dict, group_id: str, root_name: str, *,
                      writable: bool | None = None,
                      removable: bool | None = None) -> dict:
    """Toggle writable/removable on an existing root without removing it."""
    config = _config(state)
    cfg = next((g for g in config.groups if g.id == group_id), None)
    if cfg is None:
        raise OpError("Group not configured on this node", status=404)

    from meshbay_common.paths import fold
    from meshbay_node.roots import RootSet
    target = fold(root_name)
    match = None
    for r in cfg.roots:
        rname = r.name or str(Path(r.path).name)
        if fold(rname) == target:
            match = r
            break
    if match is None:
        raise OpError(f"No root named {root_name!r} in this group", status=404)

    changed = False
    if writable is not None and match.writable != writable:
        match.writable = writable
        changed = True
    if removable is not None and match.removable != removable:
        match.removable = removable
        changed = True

    if not changed:
        specs = [asdict(r) for r in cfg.roots]
        built = RootSet.build(specs)
        return {"status": "unchanged", "name": root_name, "group_id": group_id,
                "roots": built.describe()}

    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)
    _update_root_field(conf_path, group_id, str(Path(match.path).expanduser().resolve()),
                       writable=match.writable, removable=match.removable)

    # Update the live RootSet so GET /api/groups returns correct data
    # immediately, without waiting for the async reload to finish.
    live_roots: RootSet | None = state.get("groups_ctx", {}).get(
        group_id, {}).get("roots")
    if live_roots:
        for lr in live_roots.roots:
            lr_name = lr.name or str(Path(lr.path).name)
            if fold(lr_name) == target:
                if writable is not None:
                    lr.writable = writable
                if removable is not None:
                    lr.removable = removable
                break

    # Built from config when there is no live set, never returned empty: an
    # empty list is a *valid answer* meaning "this group has no directories",
    # and the client cannot tell it from "the node could not say". It would
    # blank the operator's table on an op that succeeded.
    result_roots = (live_roots.describe() if live_roots
                    else RootSet.build([asdict(r) for r in cfg.roots]).describe())

    log.info("Root updated: %s (writable=%s, removable=%s) in group %s",
             root_name, match.writable, match.removable, group_id[:8])
    return {"status": "updated", "name": root_name, "group_id": group_id,
            "roots": result_roots}


async def eject_root(state: dict, group_id: str, root_name: str) -> dict:
    """Mark a removable root as ejected so the operator can safely unplug."""
    config = _config(state)
    cfg = next((g for g in config.groups if g.id == group_id), None)
    if cfg is None:
        raise OpError("Group not configured on this node", status=404)

    from meshbay_common.paths import fold
    target = fold(root_name)
    ctx = _group_ctx(state, group_id)
    roots: RootSet | None = ctx.get("roots")
    if not roots:
        raise OpError("Group has no roots", status=503)

    root = None
    for r in roots:
        if fold(r.name) == target:
            root = r
            break
    if root is None:
        raise OpError(f"No root named {root_name!r} in this group", status=404)
    if not root.removable:
        raise OpError(f"Root {root_name!r} is not marked as removable", status=400)
    if root.ejected:
        return {"status": "already_ejected", "name": root_name,
                "group_id": group_id, "roots": roots.describe()}

    # The indexer stops its watchdog and freezes the entries; it holds the same
    # RootSet object, but the flags are set here too so a context whose indexer
    # was replaced by a retarget cannot be left disagreeing with the roster.
    indexer = state.get("indexers", {}).get(group_id)
    if indexer:
        indexer.eject_root(root_name)
    root.ejected = True
    root.available = False

    await _roster(state).set_root_ejected(
        group_id, root_name, True, set_by=state.get("node_user_id", ""))

    log.info("Root ejected: %s from group %s", root_name, group_id[:8])
    return {"status": "ejected", "name": root_name, "group_id": group_id,
            "roots": roots.describe()}


async def plug_root(state: dict, group_id: str, root_name: str) -> dict:
    """Re-enable an ejected root after the device is plugged back in."""
    config = _config(state)
    cfg = next((g for g in config.groups if g.id == group_id), None)
    if cfg is None:
        raise OpError("Group not configured on this node", status=404)

    from meshbay_common.paths import fold
    target = fold(root_name)
    ctx = _group_ctx(state, group_id)
    roots: RootSet | None = ctx.get("roots")
    if not roots:
        raise OpError("Group has no roots", status=503)

    root = None
    for r in roots:
        if fold(r.name) == target:
            root = r
            break
    if root is None:
        raise OpError(f"No root named {root_name!r} in this group", status=404)
    if not root.ejected:
        return {"status": "already_plugged", "name": root_name,
                "group_id": group_id, "roots": roots.describe()}
    if not root.is_live():
        raise OpError(
            f"Directory not found: {root.path}. Is the device connected?",
            status=409)

    # Persisted before the rescan, which can take minutes on a large library:
    # a crash halfway through must leave the root plugged, not ejected with
    # entries half rebuilt.
    await _roster(state).set_root_ejected(
        group_id, root_name, False, set_by=state.get("node_user_id", ""))

    indexer = state.get("indexers", {}).get(group_id)
    if indexer:
        await indexer.plug_root(root_name)
    root.ejected = False
    root.available = root.is_live()

    log.info("Root plugged: %s in group %s", root_name, group_id[:8])
    return {"status": "plugged", "name": root_name, "group_id": group_id,
            "roots": roots.describe()}


def _update_root_field(conf_path: Path, group_id: str,
                       resolved_path: str, *,
                       writable: bool, removable: bool) -> None:
    """Update writable/removable fields on a root in node.toml."""
    text = conf_path.read_text(encoding="utf-8")
    lines = text.split("\n")

    rng = _find_group_range(lines, group_id)
    if rng is None:
        raise OpError(f"Group {group_id[:8]} not found in {conf_path}")

    start, end = rng
    path_re = re.compile(r'^\s*path\s*=\s*"([^"]*)"')
    writable_re = re.compile(r'^\s*(writable|upload)\s*=')
    removable_re = re.compile(r'^\s*removable\s*=')
    roots_starts: list[int] = []
    for i in range(start + 1, end):
        if lines[i].strip() == "[[groups.roots]]":
            roots_starts.append(i)

    for j, rs in enumerate(roots_starts):
        rs_end = roots_starts[j + 1] if j + 1 < len(roots_starts) else end
        found_path = False
        for k in range(rs, rs_end):
            m = path_re.match(lines[k])
            if m:
                try:
                    p = str(Path(m.group(1)).expanduser().resolve())
                except OSError:
                    continue
                if p == resolved_path:
                    found_path = True
                    break
        if not found_path:
            continue

        writable_idx = None
        removable_idx = None
        for k in range(rs, rs_end):
            if writable_re.match(lines[k]):
                writable_idx = k
            if removable_re.match(lines[k]):
                removable_idx = k

        if writable_idx is not None:
            lines[writable_idx] = f"  writable = {'true' if writable else 'false'}"
        else:
            lines.insert(rs_end, f"  writable = {'true' if writable else 'false'}")
            if removable_idx is not None and removable_idx >= rs_end:
                removable_idx += 1
            rs_end += 1

        if removable_idx is not None:
            lines[removable_idx] = f"  removable = {'true' if removable else 'false'}"
        else:
            lines.insert(rs_end, f"  removable = {'true' if removable else 'false'}")

        conf_path.write_text("\n".join(lines), encoding="utf-8", newline="\n")
        return

    raise OpError("Root path not found in config", status=404)


# ── Files ────────────────────────────────────────────────────────────────────

async def delete_file(state: dict, group_id: str, file_id: str) -> dict:
    """
    Remove a file from a group. Milestone 14.11 — the last operator action that
    needed a browser.

    Authorization happened in the adapter. On the loopback path that is the
    session token, which means physical or SSH access to the machine hosting the
    files — an operator who can run this can also `rm` the file, so the check is
    not weaker than the alternative.
    """
    ctx = _group_ctx(state, group_id)
    index = ctx.get("index")
    roots = ctx.get("roots")
    if not index or not roots:
        raise OpError("Group has no index", status=503)

    entry = index.get_entry(file_id)
    if not entry:
        raise OpError("No such file in this group", status=404)

    from meshbay_node.roots import entry_abs_path
    path = entry_abs_path(roots, entry)
    if path is None:
        raise OpError(
            f"{entry.name!r} is in root {entry.path.split('/')[0]!r}, which is "
            f"not readable right now — the file is frozen, not gone", status=409)

    try:
        path.unlink()
    except FileNotFoundError:
        # Already gone from disk; drop the stale entry rather than refusing.
        log.warning("Index named a file that is not on disk: %s", path)
    except OSError as e:
        raise OpError(f"Cannot delete {entry.name!r}: {e}", status=500) from e

    index.remove_entry(file_id)
    log.info("File deleted by operator: %s/%s", entry.path, entry.name)
    return {"status": "deleted", "name": entry.name, "path": entry.path,
            "group_id": group_id}


# ── Revocation denylist ──────────────────────────────────────────────────────

async def read_denylist(state: dict) -> dict:
    """Milestone 14.10 — what the node is currently refusing."""
    denylist = state.get("denylist")
    if not denylist:
        return {"users": [], "groups": [], "jtis": [], "count": 0}
    entries = denylist.entries()
    return {**entries, "count": sum(len(v) for v in entries.values())}


async def clear_denylist(state: dict, *, subject: str = "") -> dict:
    """
    Drop denylist entries — all of them, or one identifier.

    Deliberately not silent: a cleared denylist re-admits whoever it was keeping
    out, and the count is what tells the operator whether they undid one
    revocation or all of them.
    """
    denylist = state.get("denylist")
    if not denylist:
        raise OpError("No denylist in this process", status=503)
    removed = denylist.clear(subject)
    log.warning("Denylist cleared (%s): %d entr(y/ies) removed",
                subject or "all", removed)
    return {"status": "cleared", "removed": removed, "subject": subject or "all"}


# ── Node settings ────────────────────────────────────────────────────────────

async def get_node_settings(state: dict) -> dict:
    """Return current effective node settings."""
    from meshbay_node.config import DEFAULT_STUN_SERVERS
    roster = _roster(state)
    config = _config(state)
    nd = config.node
    defaults = {
        "invite_ttl_hours": nd.invite_ttl_hours,
        "pair_ttl_hours": nd.pair_ttl_hours,
        "device_request_ttl_minutes": nd.device_request_ttl_minutes,
        "max_concurrent_streams": nd.max_concurrent_streams,
        "transcode_incompatible_video": nd.transcode_incompatible_video,
        "stun_servers": nd.stun_servers if nd.stun_servers else list(DEFAULT_STUN_SERVERS),
        "ice_interfaces": nd.ice_interfaces,
    }
    if roster:
        return await roster.node_settings(defaults)
    return defaults

async def set_node_settings(state: dict, settings: dict) -> dict:
    """Update node-level daemon settings. Writes to both roster.db and node.toml."""
    roster = _roster(state)
    config = _config(state)
    nd = config.node
    conf_path = Path(state.get("config_path") or DEFAULT_CONFIG_PATH)

    allowed_keys = {
        "invite_ttl_hours": ("int", roster.SETTING_INVITE_TTL),
        "pair_ttl_hours": ("int", roster.SETTING_PAIR_TTL),
        "device_request_ttl_minutes": ("int", roster.SETTING_DEVICE_TTL),
        "max_concurrent_streams": ("int", roster.SETTING_MAX_STREAMS),
        "transcode_incompatible_video": ("bool", roster.SETTING_TRANSCODE),
        "stun_servers": ("stun_list", roster.SETTING_STUN_SERVERS),
        "ice_interfaces": ("list", roster.SETTING_ICE_INTERFACES),
    }

    set_by = state.get("node_user_id", "")
    updated = {}
    for key, value in settings.items():
        if key not in allowed_keys:
            continue
        kind, setting_key = allowed_keys[key]
        if kind == "int":
            try:
                v = int(value)
            except (TypeError, ValueError):
                raise OpError(f"{key} must be an integer")
            if v < 1:
                raise OpError(f"{key} must be positive")
            setattr(nd, key, v)
            await roster.set_node_setting(setting_key, str(v), set_by)
            updated[key] = v
        elif kind == "bool":
            v = bool(value)
            setattr(nd, key, v)
            await roster.set_node_setting(setting_key, "1" if v else "0", set_by)
            updated[key] = v
        elif kind in ("list", "stun_list"):
            import json as _json
            if not isinstance(value, list):
                raise OpError(f"{key} must be a list")
            v = [str(s) for s in value]
            if kind == "stun_list":
                for s in v:
                    if not s.startswith("stun:"):
                        raise OpError(f"Invalid STUN server: {s} (must start with stun:)")
            setattr(nd, key, v)
            await roster.set_node_setting(setting_key, _json.dumps(v), set_by)
            updated[key] = v

    if updated:
        _update_node_toml(conf_path, updated)
        if "max_concurrent_streams" in updated:
            webrtc = state.get("webrtc")
            if webrtc and hasattr(webrtc, '_stream_sem'):
                webrtc._stream_sem = asyncio.Semaphore(updated["max_concurrent_streams"])
        if "stun_servers" in updated:
            webrtc = state.get("webrtc")
            if webrtc and hasattr(webrtc, '_stun'):
                webrtc._stun = updated["stun_servers"]
            from meshbay_node.transport.stun_multi import set_servers as _set_stun
            _set_stun(updated["stun_servers"])
        if "ice_interfaces" in updated:
            from meshbay_node.transport.ice_filter import install as install_ice_filter
            install_ice_filter(updated["ice_interfaces"] or None)

    log.info("Node settings updated: %s", updated)
    return {"updated": updated}


# ── Applications ─────────────────────────────────────────────────────────────

async def set_enabled_apps(state: dict, group_id: str, apps: list[str]) -> dict:
    """
    Which group "applications" (Chat, Files, ...) are shown to members.

    Same shape as other signed ops: lives on the node (roster.db), takes
    effect without a restart, and is signed by the operator (webrtc_server.py
    checks the caller's own admin-authority allow-list before this runs).
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    # See the same guard in webrtc_server._do_apps_enabled: Files cannot be
    # turned off, and both writers put it at the front so the two agree.
    if "files" not in apps:
        apps = ["files"] + list(apps)
    await roster.set_enabled_apps(group_id, apps,
                                  set_by=state.get("node_user_id", ""))
    ctx["enabled_apps"] = apps
    log.info("Enabled apps for group %s: %s", group_id[:8], ",".join(sorted(apps)))
    return {"apps": apps, "group_id": group_id}


# ── TMDB config (Videos app) ─────────────────────────────────────────────────

async def set_tmdb_config(state: dict, token: str | None = None,
                          language: str | None = None) -> dict:
    """
    Whether the node uses a custom API token instead of the shipped default,
    and in what language it queries TMDB (docs/mediacenter.md §5.5).

    Node-wide (roster.py group_settings, group_id="") rather than per-group
    like set_enabled_apps: the token and the shared-cache
    language are one operator's budget and one credential, not a per-group
    or per-viewer concern. Whether TMDB is used *at all* is the per-group
    decision set_tmdb_enabled below makes instead. `token=""` explicitly
    clears a previously-set custom token (reverts to the shipped default);
    `token=None` leaves whatever was there unchanged. Same discipline for
    `language`.
    """
    roster = _roster(state)
    await roster.set_tmdb_config(token, language, set_by=state.get("node_user_id", ""))
    # `token=None` means "leave whatever was there" (§ set_tmdb_config's own
    # docstring) — so the customized flag only changes when a value (a real
    # token, or "" to clear one) was actually given.
    if token is not None:
        state["tmdb_token_customized"] = bool(token)
    if language is not None:
        state["tmdb_language"] = language
    log.info("TMDB config: custom_token=%s language=%s",
             bool(token), language or state.get("tmdb_language", ""))
    return {
        "token_customized": state.get("tmdb_token_customized", False),
        "language": state.get("tmdb_language", ""),
    }


async def set_tmdb_enabled(state: dict, group_id: str, enabled: bool) -> dict:
    """
    Whether TMDB lookups run for this group at all (docs/mediacenter.md
    §5.5) — per-group, unlike set_tmdb_config above: an operator running a
    real media library alongside test/demo groups on one node wants
    outbound TMDB traffic (and API quota) spent for the one that needs it,
    not all of them just because one process serves both.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_tmdb_enabled(group_id, enabled, set_by=state.get("node_user_id", ""))
    ctx["tmdb_enabled"] = enabled
    log.info("TMDB enabled for group %s: %s", group_id[:8], enabled)
    return {"enabled": enabled, "group_id": group_id}


# ── MusicBrainz config (Music app) ───────────────────────────────────────────

# set_musicbrainz_config removed — MusicBrainz contact is now the owner's
# hub email, resolved at login (daemon.py / musicbrainz.py).

async def set_musicbrainz_enabled(state: dict, group_id: str, enabled: bool) -> dict:
    """
    Whether MusicBrainz lookups run for this group at all
    (docs/musicbay.md §6) — per-group from the start, same reasoning as
    set_tmdb_enabled: a real media-library group and a test/demo group on
    one node need not share the decision to make outbound requests.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_musicbrainz_enabled(group_id, enabled, set_by=state.get("node_user_id", ""))
    ctx["musicbrainz_enabled"] = enabled
    log.info("MusicBrainz enabled for group %s: %s", group_id[:8], enabled)
    return {"enabled": enabled, "group_id": group_id}


# ── App directories ──────────────────────────────────────────────────────────

def _validate_app_dirs(state: dict, group_id: str, paths: list[str], *,
                       require_writable: bool) -> list[str]:
    """
    Every path an app is pointed at must live inside one of the group's roots.

    The per-app setters this replaces validated nothing: a typo, or a path left
    behind by a root that was removed, was stored and then quietly matched no
    entry — an app showing an empty tab with no way to tell "misconfigured"
    from "no files yet". Refusing at the point of setting is the only moment
    the operator is present to be told.

    Not `RootSet.resolve()`, deliberately: that also refuses a directory whose
    root is currently *unavailable*, and an operator must be able to configure
    a library on a drive they have unplugged. What is checked here is the
    shape — inside a named root, no traversal — which does not change with
    what happens to be mounted.
    """
    roots: RootSet | None = _group_ctx(state, group_id).get("roots")
    if roots is None:
        raise OpError("Group has no roots", status=503)

    clean: list[str] = []
    for raw in paths:
        path = str(raw or "").strip().strip("/")
        if not path:
            continue
        if ".." in path.split("/"):
            raise OpError(f"{path!r} is not a directory inside this group",
                          status=400)
        found = roots.split(path)
        if found is None:
            raise OpError(
                f"{path!r} is not inside any of this group's shared "
                f"directories", status=400,
                extra={"available": roots.names})
        root, _tail = found
        if require_writable and not root.writable:
            raise OpError(
                f"{root.name!r} is read-only, and this setting needs a "
                f"directory that accepts uploads", status=400)
        clean.append(path)
    return sorted(set(clean))


async def set_app_directories(state: dict, group_id: str, app_key: str,
                              paths: list[str], *,
                              require_writable: bool = False) -> dict:
    """
    Which folder(s) inside the group's shared roots an application works over.

    One function for every app, keyed by the app's own name: adding an
    application is a registry entry and a settings component, not another
    near-identical op here. It replaces `set_video_root`, `set_audio_root` and
    `set_photo_roots`, which differed only in the key they wrote and whether
    they took a string or a list.

    Empty means nothing configured, which every app reads as "show nothing
    until an operator has chosen" — never "the whole group index". Pointing an
    app at the whole library is a decision, not a default nobody made.

    A change always fires (never awaits) a sweep of what the new directories
    already contain: the ordinary per-change enrichment path only looks at
    entries new since the last broadcast, so files already sitting in a folder
    when it was chosen would otherwise never be picked up.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    clean = _validate_app_dirs(state, group_id, paths,
                               require_writable=require_writable)
    await roster.set_app_directories(group_id, app_key, clean,
                                     set_by=state.get("node_user_id", ""))
    ctx[f"{app_key}_directories"] = clean
    # The scalar the handshake ack still publishes for MNP 1.0 clients is
    # derived, and has to be re-derived here: leaving it behind would make the
    # ack disagree with the list within a single run, and only until a restart
    # — the shape of bug that reads as "it works after a restart".
    from meshbay_node.roster import Roster
    alias = Roster.ctx_alias(app_key, clean)
    if alias:
        ctx[alias[0]] = alias[1]
    log.info("%s directories for group %s: %s", app_key, group_id[:8],
             ", ".join(clean) or "(none)")

    enrich = (state.get("enrich_app_dirs_fns") or {}).get(app_key)
    if enrich:
        asyncio.ensure_future(enrich(group_id))
    return {"app": app_key, "directories": clean, "group_id": group_id}


async def set_app_directory(state: dict, group_id: str, app_key: str,
                            path: str, *,
                            require_writable: bool = False) -> dict:
    """
    The single-directory form, for an app that only ever wants one.

    Stored as a one-element list like every other app, because two storage
    shapes for one idea is what made `video_root` (scalar) and `photo_roots`
    (list) need separate ops, separate MNP messages and separate widgets to
    say the same thing. `path=""` clears it.
    """
    result = await set_app_directories(
        state, group_id, app_key, [path] if path else [],
        require_writable=require_writable)
    dirs = result["directories"]
    return {**result, "path": dirs[0] if dirs else ""}


# The per-app wrappers MNP still names. They exist so an MNP 1.0 client's
# `video_root` / `audio_root` / `photo_roots` messages keep working; nothing
# new should be added here — a new app calls the generic pair above.

async def set_video_root(state: dict, group_id: str, path: str) -> dict:
    result = await set_app_directory(state, group_id, "video", path)
    return {"path": result["path"], "group_id": group_id}


async def set_audio_root(state: dict, group_id: str, path: str) -> dict:
    # "music", not "audio": the app's registry key is what identifies it
    # everywhere, and `audio_root` is only the name the setting used to have.
    result = await set_app_directory(state, group_id, "music", path)
    return {"path": result["path"], "group_id": group_id}


async def set_photo_roots(state: dict, group_id: str, roots: list[str]) -> dict:
    result = await set_app_directories(state, group_id, "photo", roots)
    return {"roots": result["directories"], "group_id": group_id}


# ── Chat ─────────────────────────────────────────────────────────────────────

async def set_chat_directory(state: dict, group_id: str, path: str) -> dict:
    """
    Where chat attachments are written.

    `require_writable`, unlike every other app directory: this one is a
    *destination*, not a view. Pointing it at a read-only root would produce an
    attachment button that fails at the moment somebody uses it, which is the
    failure mode the RO/RW model exists to move earlier.
    """
    return await set_app_directory(state, group_id, "chat", path,
                                   require_writable=True)


async def set_chat_link_preview(state: dict, group_id: str,
                                enabled: bool) -> dict:
    """
    Whether the node fetches a page's title and image when a member posts a
    link.

    Outbound third-party traffic on the operator's connection, caused by a
    message they did not write and pointing at a URL they did not choose — so
    it is theirs to switch off, on the same reasoning as the per-group TMDB
    switch. Absent means on, because that is what the node did before this
    existed.
    """
    roster = _roster(state)
    ctx = _group_ctx(state, group_id)
    await roster.set_chat_link_preview(group_id, enabled,
                                       set_by=state.get("node_user_id", ""))
    ctx["chat_link_preview"] = enabled
    log.info("Chat link previews for group %s: %s", group_id[:8],
             "on" if enabled else "off")
    return {"enabled": enabled, "group_id": group_id}


# ── Scan settings ────────────────────────────────────────────────────────────

async def set_scan_settings(state: dict, group_id: str, reconcile_interval_secs: float,
                            debounce_secs: float) -> dict:
    """
    How often the indexer's reconciliation backstop runs, and how long a
    changed file is left alone before being hashed (indexer.py
    DirectoryIndexer). Persisted like set_enabled_apps —
    but there is also a *live* DirectoryIndexer object to update, since it
    reads these once at construction and runs its own background loop with
    them rather than consulting groups_ctx on every use.
    """
    roster = _roster(state)
    await roster.set_scan_settings(group_id, reconcile_interval_secs, debounce_secs,
                                   set_by=state.get("node_user_id", ""))
    indexer = state.get("indexers", {}).get(group_id)
    if indexer:
        indexer.reconcile_secs = reconcile_interval_secs
        indexer.debounce_secs = debounce_secs
        # Apply the new interval now rather than after whatever backoff had
        # already stretched the wait to.
        indexer.note_activity()
    # Optional, unlike _group_ctx(): a group can be persisted here before it
    # is hot-loaded (or in a test that only cares about the roster/indexer
    # side), and that must not turn a successful write into a 404.
    ctx = state.get("groups_ctx", {}).get(group_id)
    if ctx is not None:
        ctx["reconcile_interval_secs"] = reconcile_interval_secs
        ctx["debounce_secs"] = debounce_secs
    log.info("Scan settings for group %s: reconcile=%.0fs debounce=%.0fs",
             group_id[:8], reconcile_interval_secs, debounce_secs)
    return {"reconcile_interval_secs": reconcile_interval_secs,
            "debounce_secs": debounce_secs, "group_id": group_id}


# ── Index cache maintenance ───────────────────────────────────────────────────
#
# The (path, size, mtime) -> hash accelerator (indexer/cache.py) is node-wide
# and grows for as long as a path was ever seen — a folder an operator later
# stops sharing (root removed, or every group hosting it is deleted) leaves
# its rows behind forever otherwise. Nothing about correctness needs this:
# a stale row just sits unused (lookup() keys on the live path string, so a
# path nothing scans any more is never looked up). This is disk space
# hygiene the operator can run when they want it, not a background job.

async def index_cache_stats(state: dict) -> dict:
    """Row count only — cheap, safe to call on every dashboard render.
    The actual staleness check (prune_index_cache) is not this cheap and
    must never run implicitly."""
    cache = state.get("index_cache")
    return {"count": await cache.count() if cache else 0}


async def prune_index_cache(state: dict) -> dict:
    """
    Drop cache rows that cannot be right for anything any more: the path is
    not under any group's root at all, or it is under a root that is
    available right now and the file is genuinely gone from disk.

    Deliberately leaves alone anything under a root that is currently
    *unavailable* (a disconnected drive) — indexer.py's own rule is that
    such a root freezes rather than empties, precisely so it does not pay a
    full rehash the moment it comes back. Pruning through an unavailable
    root here would reintroduce exactly that cost via a different door, so
    an owning-but-unavailable root wins over "the file isn't there right
    now" every time, unconditionally.

    A row lost here costs one rehash the next time that path is scanned,
    never a wrong answer: lookup() (cache.py) always re-validates size and
    mtime against a live stat() before trusting a cached hash.
    """
    cache = state.get("index_cache")
    if cache is None:
        raise OpError("No index cache in this process", status=503)

    indexers = list((state.get("indexers") or {}).values())
    roots = [root for indexer in indexers for root in indexer.roots]

    def _is_stale(path_str: str) -> bool:
        path = Path(path_str)
        owning = [r for r in roots if r.path in path.parents]
        if not owning:
            return True
        if any(not r.available for r in owning):
            return False
        return not path.exists()

    paths = await cache.all_paths()
    stale = await asyncio.to_thread(lambda: [p for p in paths if _is_stale(p)])
    await cache.remove_many(stale)
    log.info("Index cache pruned: %d stale row(s) removed, %d kept",
             len(stale), len(paths) - len(stale))
    return {"status": "pruned", "removed": len(stale), "kept": len(paths) - len(stale)}


# ── Videos: force TMDB re-matching ───────────────────────────────────────────
#
# `media_cache.file_tmdb` is keyed by a file's content hash and is otherwise
# only pruned on deletion, so a fixed matcher/parser never dislodges a match
# already in cache. This drops a group's *auto-resolved* mappings so the
# next `media_meta_req` for each poster tile re-resolves against the current
# code. Re-resolution is lazy and calls TMDB once per unique title — real
# API budget — so this is an explicit operator action, never a background job.
# Manual "Fix match" corrections (media_cache.tmdb_override) are kept.

async def rematch_video(state: dict, group_id: str) -> dict:
    media_cache = state.get("media_cache")
    if media_cache is None:
        raise OpError("No media cache in this process", status=503)
    indexer = (state.get("indexers") or {}).get(group_id)
    if indexer is None:
        raise OpError("Unknown group", status=404)
    file_ids = [e.id for e in indexer.index.entries if e.type == "video"]
    removed = await media_cache.clear_tmdb_matches(file_ids)
    log.info("Video rematch for group %s: %d auto match(es) cleared across %d video file(s)",
             group_id[:8], removed, len(file_ids))
    return {"status": "cleared", "removed": removed, "videos": len(file_ids),
            "group_id": group_id}


# ── Reload ──────────────────────────────────────────────────────────────────

async def reload_config(state: dict) -> dict:
    """Hot-reload node.toml without dropping connections. Blocks until the
    reload actually finishes — see start_reload for why the loopback route
    uses that instead."""
    reload_fn = state.get("reload_fn")
    if not reload_fn:
        raise OpError("Reload not available", status=503)
    await reload_fn()
    return {"status": "reloaded"}


async def start_reload(state: dict) -> dict:
    """
    Same as reload_config, but does not wait for the reload to finish.

    The loopback route uses this one: the Electron bridge caps every call at
    a fixed 30s (main.js node:call), and hot-loading a brand-new group runs
    its full initial scan synchronously inside _reload_config_inner()
    (daemon.py) before that coroutine returns — minutes, not seconds, on a
    real library (found against a 45 GB group on the same slow disk the
    StarWars benchmark used). The reload keeps running on the daemon's own
    event loop either way; add_root/remove_root below already fire it the
    same way for exactly this reason.
    """
    reload_fn = state.get("reload_fn")
    if not reload_fn:
        raise OpError("Reload not available", status=503)
    asyncio.ensure_future(reload_fn())
    return {"status": "reloading"}