pushraker 0.1.0.dev0__py3-none-any.whl

pushraker/component.py

@@ -0,0 +1,3718 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-PackageHomePage: https://github.com/noon92/pushraker
+# SPDX-FileCopyrightText: Copyright (c) 2026 @noon92
+
+# Push Notifications — print, progress and fault notifications with images,
+# sent through Apprise (ntfy, Pushover, Telegram, Discord, a webhook, email).
+#
+# Sources:
+#  * Moonraker job events: started, paused, resumed, error (and complete /
+#    cancelled as a fallback when the print hooks did not report them).
+#  * The Klipper print hooks (`_PRINT_END_NTFY`, `_CANCEL_PRINT_NTFY`), via
+#    the `push_notification` remote method, so complete/cancelled snapshots
+#    are taken before the printer parks.
+#  * Snapmaker's exception manager: coded faults and warnings, including
+#    those that never reach print_stats (Klipper shutdowns, idle faults).
+#  * print_stats layer info and file progress: first layer and milestones.
+#  * Power-loss recovery data after boot.
+#
+# Images are fetched before sending; when the camera or the thumbnail is not
+# available, the notification is sent without the image. A send that the
+# server answers with an error (or that can't connect) is retried after 6, 10
+# and 30 s; the last retry is without the image. Fault codes use Snapmaker's
+# format LLLL-IIII-XXXX-CCCC (level-id-index-code).
+#
+# Normally generated by notifications-config.py from extended2.cfg. Each
+# notification can go to a push service (`<notification>: ...`) and/or email
+# (`<notification>_email: ...`) and/or a webhook (`<notification>_webhook:
+# ...`), each `<render|snapshot|spool|none>, <apprise url>`;
+# notifications that are not listed are disabled. Each destination is sent
+# and retried on its own. Emails, Telegram and Discord get the links (Web UI, Live
+# Camera, Error Index) in the text, since they have no buttons:
+#
+#   [push_notifications]
+#   name: U1
+#   snapshot_url: http://127.0.0.1/webcam/snapshot.jpg
+#   layers_complete: 2               # first-layer row: after layer 1, 2 or 3
+#   timezone: Asia/Jerusalem         # for ETA clock times (printer runs UTC)
+#   web_ui_url: http://u1/           # links in the text (optional)
+#   camera_url: http://u1/webcam/webrtc
+#   started: render, ntfys://ntfy.example.com/u1?priority=default
+#   error: snapshot, ntfys://ntfy.example.com/u1?priority=max
+#   error_email: snapshot, mailtos://user:pass@smtp.example.com:587?...
+#
+# This file may be distributed under the terms of the GNU GPLv3 license.
+
+from __future__ import annotations
+import asyncio
+import datetime
+import html
+import http
+import json
+import logging
+import os
+import re
+import shutil
+import tempfile
+import time
+import urllib.request
+from typing import (
+    TYPE_CHECKING, Any, Awaitable, Dict, List, NamedTuple, Optional, Set,
+    Tuple
+)
+
+import apprise
+
+try:
+    from . import images
+except Exception as e:      # no Pillow: Spoolman notifications without images
+    logging.warning("[push_notifications] spool images unavailable: %s", e)
+    images = None  # type: ignore
+
+try:
+    from . import email_html
+except Exception as e:
+    logging.warning("[push_notifications] HTML email unavailable: %s", e)
+    email_html = None  # type: ignore
+
+try:
+    # Registers the discordhook:// and discorddm:// Apprise plugins
+    from . import discord
+except Exception as e:
+    logging.warning("[push_notifications] Discord unavailable: %s", e)
+    discord = None  # type: ignore
+
+from moonraker.common import JobEvent, KlippyState
+
+if TYPE_CHECKING:
+    from moonraker.confighelper import ConfigHelper
+    from moonraker.components.klippy_apis import KlippyAPI as APIComp
+
+EXCEPTION_EVENT = "snapmaker:exception_notification"
+REMOTE_METHOD = "push_notification"
+MILESTONES = (25, 50, 75)
+ROW_IDS = (
+    "started", "layer_started", "first_layer", "progress_25", "progress_50", "progress_75",
+    "paused", "file_pause", "resumed", "object_complete", "complete", "cancelled",
+    "calibration",
+    "chamber_waiting", "chamber_reached", "chamber_fault",
+    "filament_change",
+    "macro_min", "macro_low", "macro_default", "macro_high", "macro_max",
+    "error", "warning", "shutdown", "power_loss", "driver_hot",
+    "filament_short", "filament_low", "spool_switch", "slot_empty",
+)
+SPOOLMAN_ROWS = ("filament_short", "filament_low", "spool_switch")
+TITLES = {
+    "started": "▶️ {name} started",
+    "layer_started": "🎬 {name} first layer started",
+    "first_layer": "🔍 {name} {ordinal} layer complete",
+    "progress": "⏳ {name} {pct}%",
+    "paused": "⏸️ {name} paused",
+    "resumed": "▶️ {name} resumed",
+    "recovered": "▶️ {name} resumed after power loss",
+    "object_complete": "📦 {name} object complete",
+    "complete": "✅ {name} complete",
+    "cancelled": "🚫 {name} cancelled",
+    "calibration": "📐 {name} {what} complete",
+    "macro": "📣 {name} {title}",
+    "calibration_failed": "📐 {name} {what} failed",
+    "intervention": "👋 {name} user intervention needed",
+    "file_pause": "👋 {name} paused by the print job",
+    "chamber_waiting": "🌡️ {name} waiting for chamber temperature",
+    "chamber_reached": "🌡️ {name} chamber temperature reached",
+    "chamber_timeout": "⚠️ {name} timed out waiting for chamber "
+                       "temperature, printing anyway",
+    "chamber_stalled": "⚠️ {name} chamber not heating",
+    "chamber_fault": "⚠️ {name} chamber heater fault",
+    "chamber_disconnected": "⚠️ {name} chamber heater disconnected",
+    "error": "⚠️ {name} Error: {kind}",
+    "warning": "⚠️ {name} Warning",
+    "shutdown": "🛑 {name} Error: shutdown",
+    "power_loss": "⚡ {name} power loss",
+    "driver_hot": "🌡️ {name} driver running hot",
+    "filament_loaded": "🧵 {name} filament loaded",
+    "filament_unloaded": "🧵 {name} filament unloaded",
+    "filament_short": "🧵 {name} not enough filament",
+    "filament_close": "🧵 {name} filament may be insufficient",
+    "filament_unknown": "🧵 {name} filament amount unknown",
+    "filament_problems": "🧵 {name} filament problems on {n} toolheads",
+    "filament_low": "🧵 {name} spool running low",
+    "filament_lows": "🧵 {name} spools running low on {n} toolheads",
+    "spool_switch": "🔄 {name} switched to backup spool",
+    "slot_empty": "🧵 {name} ACE slot ran empty",
+}
+IMAGE_KINDS = ("render", "snapshot", "spool", "none")
+# machine_state_manager.main_state values of the manual calibrations run
+# from the touchscreen (klippy/extras/machine_state_manager.py); the
+# calibration is complete when the state goes back to IDLE (0; PRINTING
+# is 1, seen in the Moonraker log as "machine state: {...}")
+CALIBRATIONS = {2: "XYZ offset calibration", 3: "Bed levelling",
+                4: "Flow calibration", 5: "Input shaper calibration"}
+MSM_IDLE = 0
+MSM_ABNORMAL = 7
+# action_code values (same file) of the steps that wait for a person:
+# MANUAL_CLEAN_EXTRUDER..3 (brush the nozzle, then tap the screen)
+MANUAL_CLEAN = {192: 1, 193: 2, 194: 3, 195: 4}
+# ...and a calibration sitting at action IDLE (0) this long, with Klipper
+# idle too (idle_timeout "Ready": no moves, no heat-up running), is the
+# screen waiting for a tap (plate out / plate back in). Picking up and
+# heating a toolhead also runs at action IDLE, for longer than this, but
+# Klipper is "Printing" then, which restarts the count.
+INTERVENTION_HOLD = 15.
+# Filament loaded / unloaded: print_task_config.filament_exist per toolhead
+# (the toolhead's sensor, or the feeder's). It can flicker while filament
+# is fed, so a change is reported once it has held this long. Not during
+# a print job: runouts and refills have their own notifications.
+FILAMENT_CHANGE_SETTLE = 3.
+FAULT_ROWS = ("error", "warning", "shutdown")
+# Chamber temperature, whatever heats the chamber: a print job "waits" when,
+# before its first layer, there is a chamber target and the chamber is below
+# it. Targets come from any heater_generic (DragonBreath, Panda Breath,
+# others; M141/M191) or Snapmaker's own chamber wait (WAIT_CHAMBER_TEMP,
+# which only runs with Snapmaker's purifier connected and shows as action
+# PREHEAT_CHAMBER). M191 releases a few degrees short of the target
+# (DragonBreath: 5 °C), so within this of it counts as reached.
+CHAMBER_ROWS = ("chamber_waiting", "chamber_reached", "chamber_fault")
+CHAMBER_TOLERANCE = 5.
+# Waiting with no rise of this much for this long: "not heating"
+CHAMBER_STALL_RISE = 1.
+CHAMBER_STALL_TIME = 600.
+# A chamber wait counts once it has lasted this long: the printer's own
+# wait can end within seconds (it asks for 45 °C in keep-warm mode and
+# gives up at once with the lid off), and that is not worth two
+# notifications. Nothing is sent about a wait that ended sooner.
+CHAMBER_WAIT_MIN = 30.
+CHAMBER_SENSOR = "temperature_sensor cavity"
+ACTION_PREHEAT_CHAMBER = 3
+DRAGONBREATH = "dragonbreath"
+ERROR_INDEX_URL = ("https://wiki.snapmaker.com/en/snapmaker_u1/"
+                   "troubleshooting/u1_error_codes")
+ORDINALS = {1: "1st", 2: "2nd", 3: "3rd"}
+SNAPSHOT_TIMEOUT = 5.
+SNAPSHOT_MAX = 5 * 1024 * 1024
+# A pause is reported when it starts; the head moves away from the part
+# afterwards, so the snapshot waits (the bed doesn't lower on a pause).
+PAUSE_SNAPSHOT_DELAY = 3.
+# A runout pause on a toolhead the printer can refill from a backup spool:
+# the printer swaps toolheads within ~10 s and resumes by itself, so the
+# error is held this long and dropped if the refill happens (the "Switched
+# to backup spool" notification says it instead)
+REFILL_WAIT = 25.
+# multiACE (klipper/extras/ace.py): with Quad Replenish on, a runout on a
+# head fed by an ACE is reloaded from another slot of the ACE (a full load
+# takes ~90 s) and the print job resumes by itself: the error is held
+# this long instead. Status fields read from the `ace` object; indices in
+# it are 0-based, shown 1-based like multiACE's own messages.
+ACE_OBJECT = "ace"
+ACE_FIELDS = ["head_source", "aces", "mode", "head_ace",
+              "quad_replenish", "quad_first", "swap_in_progress"]
+ACE_REFILL_WAIT = 180.
+MACRO_PREFIX = "notify "
+MACRO_SEP = " || "
+MACRO_LEVELS = ("min", "low", "default", "high", "max")
+RUNOUT_EXCEPTION_ID = 523
+# Before each attempt, wait this long at most for the printer to have a
+# network (Wi-Fi is often not up yet right after boot). Waiting doesn't
+# count as an attempt; nothing has been sent, so it can't cause doubles.
+NETWORK_WAIT = 600.
+NETWORK_POLL = 5.
+# Spoolman notifications: how often to read the spools' remaining weight
+# during a print. A toolhead is "may be insufficient" (orange) when it has
+# enough by less than max(20 g, 5% of what it needs).
+FILAMENT_POLL = 60.
+FILAMENT_CLOSE = 0.05
+FILAMENT_CLOSE_G = 20.
+RANK = {"green": 0, "orange": 1, "red": 2}
+# Message length limits: (counted in characters?, limit). ntfy's is 4096
+# bytes; Pushover's 1024 characters. Longer messages are split between
+# toolheads, and names shortened with "…" only if one toolhead won't fit.
+# Telegram's is 4096 characters after HTML escaping and the links.
+# Discord's embed text is 4096 characters, after Markdown escaping and links.
+BODY_LIMITS = {"pushover": (True, 1024), "ntfy": (False, 4000),
+               "telegram": (True, 3500), "discord": (True, 3500)}
+# Discord's embed colour (Apprise notification type) for each notification
+NOTIFY_TYPES = {"complete": "success", "object_complete": "success",
+                "calibration": "success", "chamber_reached": "success",
+                "chamber_fault": "warning",
+                "driver_hot": "warning", "error": "failure",
+                "warning": "failure", "shutdown": "failure",
+                "power_loss": "failure", "filament_short": "failure",
+                "cancelled": "warning", "paused": "warning",
+                "file_pause": "warning",
+                "filament_low": "warning", "spool_switch": "warning",
+                "slot_empty": "warning"}
+FILE_CAP = 30
+# Emails about one print go in one thread (see _email_prepare). Faults
+# join it while printing and this long after the print ended.
+THREAD_ROWS = ("started", "layer_started", "first_layer",
+               "progress_25", "progress_50",
+               "progress_75", "paused", "file_pause", "resumed", "object_complete",
+               "complete", "cancelled",
+               "chamber_waiting", "chamber_reached", "chamber_fault",
+               "filament_change", "filament_short", "filament_low",
+               "spool_switch", "slot_empty")
+THREAD_FAULT_WINDOW = 120.
+NAME_CAP_MIN = 8
+PTC_FIELDS = ["extruder_map_table", "filament_spool_id", "extruders_used",
+              "auto_replenish_filament", "replenish_ignore_color",
+              "filament_exist", "filament_vendor", "filament_type",
+              "filament_sub_type", "filament_color_rgba",
+              "filament_color_multi"]
+# The printer refills only from a toolhead with the same nozzle
+EXTRUDERS = ["extruder", "extruder1", "extruder2", "extruder3"]
+NOZZLE_FIELDS = ["nozzle_diameter", "nozzle_volume_type"]
+# A job that starts this far into its file is a power-loss recovery
+RECOVERY_MIN_PROGRESS = 0.01
+# ...and either kept its print time, or is this far in (a small file's
+# start G-code alone is past 1 %)
+RECOVERY_MIN_TIME = 30.
+RECOVERY_SURE_PROGRESS = 0.10
+# Below this file progress, time left comes from the slicer estimate rather
+# than print time / progress (the first layer alone makes that ratio useless)
+EARLY_PROGRESS = 0.10
+SEND_RETRY_DELAYS = (6, 10, 30)
+# ntfy timestamps messages to the second and its app orders by that time:
+# two sends this far apart can't share a second and swap places
+SEND_GAP = {"ntfy": 2.}   # seconds before each retry of a failed send
+# Within one service (services never wait on each other), faults go ahead of
+# everything else, and these status notifications are dropped if they could
+# not be sent this long after they happened (e.g. a long outage): a 25%
+# notification an hour late is noise. Faults and complete never expire.
+URGENT_ROWS = ("error", "warning", "shutdown", "power_loss",
+               "chamber_fault")
+EXPIRING_ROWS = ("started", "layer_started", "first_layer", "progress_25",
+                 "progress_50", "progress_75", "object_complete",
+                 "chamber_waiting", "chamber_reached", "filament_change")
+STATUS_EXPIRY = 300.
+# Spoolman usage counts as tracked once spools lost this much; if nothing
+# was used by this far into the file, it isn't tracked and the filament
+# checks during the print job are skipped (the one at the start still runs)
+USAGE_MIN_G = 0.5
+USAGE_GRACE = 0.05
+# Wait this long for the server's answer (Apprise default: 4 s), so a slow
+# upload that the server accepted is not counted as failed and sent twice.
+SEND_READ_TIMEOUT = 60.
+# Apprise's default (4 s) is short for a slow or relayed connection
+SEND_CONNECT_TIMEOUT = 10.
+PL_ENV_PATHS = (
+    "/home/lava/printer_data/klippy/pl_print_file_env.json",
+    "/home/lava/printer_data/config/snapmaker/pl_print_file_env.json",
+)
+PL_WAIT_TIME = 60.
+BOOT_WINDOW = 600.
+# After boot the camera service may still be starting: the power-loss
+# snapshot is retried this long before sending without it.
+PL_CAMERA_WAIT = 45.
+PL_CAMERA_POLL = 5.
+
+FaultKey = Tuple[Any, Any, Any]
+GCODE_EXTS = (".gcode", ".gco", ".g")
+# The X and Y stepper drivers report their own temperature (TMC2240 ADC);
+# the alert goes once per print job, and again after a pause (so a print
+# job paused for the heat and resumed can warn a second time)
+DRIVERS = {"tmc2240 stepper_x": "X", "tmc2240 stepper_y": "Y"}
+DRIVER_HOT_DEFAULT = 105
+# Print-by-object (Orca "print_sequence = by object"): the slicer's config
+# block at the end of the file says so, and its EXCLUDE_OBJECT markers tell
+# Klipper which object is being printed. Layer numbers run on across the
+# objects, so an object's own layer is counted from the layer it began on.
+CONFIG_TAIL = 256 * 1024
+# Pauses the print job itself asks for, put there by the slicer ("add
+# pause", "change filament") or by hand: PAUSE, M601, M226, M0, M1, M600,
+# and Orca's ;PAUSE_PRINT marker (followed by the printer's pause G-code).
+# A marker and a command within PAUSE_MERGE bytes are one pause. The
+# pause is told from a person's by virtual_sdcard.file_position, which
+# sits just past the pause line when the file did it.
+RX_PAUSE_CMD = re.compile(rb"^(PAUSE|M601|M226|M0|M1|M600)\b[ \t]*([^;\r\n]*)"
+                          rb"(?:;[ \t]*([^\r\n]*))?", re.I)
+RX_PAUSE_MARK = re.compile(rb"^;[ \t]*PAUSE_PRINT\b", re.I)
+RX_LAYER = re.compile(rb"^;[ \t]*(LAYER_CHANGE|LAYER:[ \t]*(\d+))", re.I)
+RX_M117 = re.compile(rb"^M117[ \t]+([^\r\n]*)", re.I)
+PAUSE_MERGE = 400
+PAUSE_WINDOW = 2048
+RX_BY_OBJECT = re.compile(rb"^; *print_sequence *= *by object *$", re.M)
+RX_OBJECT_NAME = re.compile(r"^(.*?)_id_(\d+)_copy_(\d+)$")
+
+
+def shown(filename: str) -> str:
+    """File name as shown to people: without the G-code extension (Klipper
+    only prints .gcode, .gco and .g files)."""
+    low = filename.lower()
+    for ext in GCODE_EXTS:
+        if low.endswith(ext) and len(filename) > len(ext):
+            return filename[:-len(ext)]
+    return filename
+
+
+def format_code(ex: Dict[str, Any]) -> str:
+    try:
+        return "%04d-%04d-%04d-%04d" % (
+            int(ex["level"]), int(ex["id"]), int(ex["index"]),
+            int(ex["code"]))
+    except (KeyError, TypeError, ValueError):
+        return "-".join(str(ex.get(k)) for k in ("level", "id", "index",
+                                                  "code"))
+
+
+# Klipper's fault messages are internal ("detected noodle"). The printer's
+# screen shows its own text per code, from the firmware's exception text
+# file ("<id>-<index>-<code>": "<title>_<details>"); notifications use the
+# same. Faults it doesn't list keep Klipper's message.
+EXCEPTION_TEXT_PATHS = ("/home/lava/resource/text/exception_en-GB.json",)
+_exception_text: Optional[Dict[str, str]] = None
+
+
+def exception_text() -> Dict[str, str]:
+    global _exception_text
+    if _exception_text is None:
+        _exception_text = {}
+        for path in EXCEPTION_TEXT_PATHS:
+            try:
+                with open(path, encoding="utf-8") as f:
+                    data = json.load(f)
+                if isinstance(data, dict):
+                    _exception_text = {str(k): str(v) for k, v in data.items()}
+                    break
+            except Exception as e:
+                logging.info("[push_notifications] no exception texts in "
+                             "%s: %s", path, e)
+    return _exception_text
+
+
+# An emoji before the error code for some kinds of fault, by module id and
+# code (any toolhead), going by each code's text in exception_en-GB.json.
+# Codes not listed get none.
+def _codes(module: int, *codes: Any) -> Set[Tuple[int, int]]:
+    out: Set[Tuple[int, int]] = set()
+    for c in codes:
+        for n in (c if isinstance(c, range) else (c,)):
+            out.add((module, n))
+    return out
+
+
+FAULT_EMOJI: Dict[Tuple[int, int], str] = {}
+for _emoji, _set in (
+    # Temperature: heating module, nozzle, heated bed, chamber
+    ("🌡️", _codes(522, 15) | _codes(523, 1, 2, 3, 36) | _codes(526, 0, 1)
+     | _codes(527, 0) | _codes(533, 1)),
+    ("💾", _codes(531, 9)),                                # storage space
+    ("☁️", _codes(531, 7, 11, 12)),                        # cloud print file
+    # Calibration (vibration compensation, flow, XYZ offset, homing)
+    ("📐", _codes(522, 21) | _codes(523, 9000, 9001)
+     | _codes(530, range(0, 10), 18, 19, 20, 23, range(24, 29))),
+    ("🍝", _codes(532, 2)),                                # spaghetti
+    # Spool and filament: runout, filament info, feeder loading/unloading
+    ("🧵", _codes(523, 0, 39) | _codes(525, 0, 1, 2, 3, 5, 6, 8,
+                                         range(10, 16), range(30, 36), 70,
+                                         90)),
+    # Toolhead: swapping, picking, parking, detached, placement, Pogopin,
+    # maintenance
+    ("🔧", _codes(523, range(7, 36), range(37, 38), range(40, 48))
+     | _codes(528, 13, 14) | _codes(530, range(13, 17))),
+):
+    for _k in _set:
+        FAULT_EMOJI[_k] = _emoji
+
+
+def fault_emoji(ex: Dict[str, Any]) -> str:
+    try:
+        return FAULT_EMOJI.get((int(ex.get("id")), int(ex.get("code"))), "")
+    except (TypeError, ValueError):
+        return ""
+
+
+def describe(ex: Dict[str, Any]) -> str:
+    """Error code and the text the printer shows for it, e.g.
+    "0002-0532-0000-0002: Possible Spaghetti Defect Detected" and the
+    screen's advice on the next line."""
+    msg = str(ex.get("message") or "").strip()
+    try:
+        key = "%04d-%04d-%04d" % (int(ex.get("id")), int(ex.get("index")),
+                                  int(ex.get("code")))
+    except (TypeError, ValueError):
+        key = ""
+    text = exception_text().get(key, "")
+    title, _, details = text.partition("_")
+    emoji = fault_emoji(ex)
+    code = f"{emoji} {format_code(ex)}" if emoji else format_code(ex)
+    if not title.strip():
+        return f"{code}: {msg}"
+    return "\n".join(x for x in (f"{code}: {title.strip()}",
+                                 details.strip()) if x)
+
+
+def coded(ps: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """The Snapmaker fault recorded in print_stats, if any."""
+    ex = ps.get("exception") or {}
+    if isinstance(ex, dict) and ex.get("code") is not None:
+        return ex
+    return None
+
+
+def fault_key(ex: Dict[str, Any]) -> FaultKey:
+    return (ex.get("id"), ex.get("index"), ex.get("code"))
+
+
+def format_duration(seconds: float) -> str:
+    t = int(seconds or 0)
+    if t >= 3600:
+        return "%dh %02dm" % (t // 3600, (t % 3600) // 60)
+    return "%dm" % (t // 60)
+
+
+class ChannelGate:
+    """One service's send order. Each notification takes a ticket when it
+    happens: (urgency, sequence). A send attempt waits until its ticket is
+    the first one still pending and nothing else is sending, so
+    notifications arrive in the order they happened (resumed never before
+    paused), except that faults go ahead of status notifications. A ticket
+    is held until its notification is sent or given up, so one that is
+    waiting to retry holds the channel's later notifications back (they
+    would arrive out of order otherwise); faults, with a lower ticket, go
+    ahead of it. Services never wait on each other."""
+
+    def __init__(self) -> None:
+        self._seq = 0
+        self._tickets: Set[Tuple[int, int]] = set()
+        self._busy: Optional[Tuple[int, int]] = None
+        self._cond: Optional[asyncio.Condition] = None
+        self.last_sent = -1e9   # monotonic time the last attempt ended
+
+    def _condition(self) -> asyncio.Condition:
+        if self._cond is None:
+            self._cond = asyncio.Condition()
+        return self._cond
+
+    def ticket(self, urgent: bool) -> Tuple[int, int]:
+        self._seq += 1
+        t = (0 if urgent else 1, self._seq)
+        self._tickets.add(t)
+        return t
+
+    async def acquire(self, t: Tuple[int, int]) -> None:
+        cond = self._condition()
+        async with cond:
+            await cond.wait_for(
+                lambda: self._busy is None and min(self._tickets) == t)
+            self._busy = t
+
+    async def release(self, t: Tuple[int, int]) -> None:
+        cond = self._condition()
+        async with cond:
+            if self._busy == t:
+                self._busy = None
+            cond.notify_all()
+
+    async def done(self, t: Tuple[int, int]) -> None:
+        cond = self._condition()
+        async with cond:
+            self._tickets.discard(t)
+            if self._busy == t:
+                self._busy = None
+            cond.notify_all()
+
+
+class Ticket(NamedTuple):
+    gate: ChannelGate
+    ticket: Tuple[int, int]
+    created: float              # monotonic time the notification happened
+
+
+# Console lines (Fluidd/Mainsail): what was sent, to which services, and
+# each failed attempt with a few words on why. Failed attempts of one
+# notification with the same cause, at the same attempt, within this many
+# seconds are one line.
+CONSOLE_GROUP = 1.
+CHANNEL_NAMES = {"ntfy": "ntfy", "gotify": "Gotify", "pushover": "Pushover",
+                 "telegram": "Telegram", "discord": "Discord",
+                 "email": "email", "webhook": "webhook"}
+CHANNEL_ORDER = list(CHANNEL_NAMES)
+# Which service an Apprise log line is about: the file that logged it
+APPRISE_SOURCES = (("discord.py", "discord"),
+                   ("email", "email"), ("ntfy", "ntfy"),
+                   ("gotify", "gotify"), ("pushover", "pushover"),
+                   ("telegram", "telegram"), ("discord", "discord"),
+                   ("json", "webhook"))
+SMTP_PHRASES = {421: "server busy", 450: "mailbox busy", 451: "server busy",
+                530: "login required", 534: "login rejected",
+                535: "login rejected", 550: "rejected", 553: "rejected",
+                554: "rejected"}
+
+
+def short_cause(messages: List[str]) -> str:
+    """Why a send failed, in a few words, from what Apprise logged:
+    "401 Unauthorized", "timed out", "SSL error", "535 login rejected"."""
+    text = " | ".join(messages)
+    low = text.lower()
+    m = re.search(r"error=(\d{3})\b", text)
+    if m:
+        code = int(m.group(1))
+        try:
+            return f"{code} {http.HTTPStatus(code).phrase}"
+        except ValueError:
+            return f"HTTP {code}"
+    m = re.search(r"\((\d{3}), b['\"]", text)
+    if m:
+        code = int(m.group(1))
+        return f"{code} {SMTP_PHRASES.get(code, 'rejected by server')}"
+    if "timed out" in low or "timeout" in low:
+        return "timed out"
+    if "ssl" in low or "certificate" in low:
+        return "SSL error"
+    if any(k in low for k in ("name or service not known", "name resolution",
+                              "nodename nor servname", "getaddrinfo",
+                              "no address associated", "failed to resolve")):
+        return "server not found"
+    if "connection refused" in low:
+        return "connection refused"
+    if "connect" in low:
+        return "could not connect"
+    return "failed"
+
+
+class AppriseLog(logging.Handler):
+    """Apprise's messages per service (debug ones too), to say why a send
+    failed. Moonraker's log gets what it got before: Apprise's own logger
+    no longer passes records up, and this passes on those at the level it
+    logged at (debug lines can hold URLs with tokens)."""
+    installed: Optional["AppriseLog"] = None
+
+    def __init__(self, level: int) -> None:
+        super().__init__(logging.DEBUG)
+        self.forward_level = level
+        self.messages: Dict[str, List[str]] = {}
+
+    @classmethod
+    def install(cls) -> "AppriseLog":
+        if cls.installed is None:
+            log = logging.getLogger("apprise")
+            cls.installed = cls(log.getEffectiveLevel())
+            log.addHandler(cls.installed)
+            log.setLevel(logging.DEBUG)
+            log.propagate = False
+        return cls.installed
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if record.levelno >= self.forward_level:
+            logging.getLogger().handle(record)
+        path = (record.pathname or "").replace("\\", "/")
+        where = path.rsplit("/apprise/", 1)[-1] if "/apprise/" in path \
+            else os.path.basename(path)
+        for key, channel in APPRISE_SOURCES:
+            if key in where:
+                try:
+                    msgs = self.messages.setdefault(channel, [])
+                    msgs.append(record.getMessage()[:500])
+                    del msgs[:-20]
+                except Exception:
+                    pass
+                return
+
+    def take(self, channel: str) -> List[str]:
+        return self.messages.pop(channel, [])
+
+
+class Destination(NamedTuple):
+    channel: str             # "ntfy", "pushover", "email", ... (for logs)
+    ap: apprise.Apprise
+    email: bool
+
+
+def has_network() -> bool:
+    """True if any interface other than loopback has an active route.
+
+    Read from /proc, so it costs nothing and sends nothing. Unknown (no
+    /proc) counts as a network."""
+    try:
+        with open("/proc/net/route") as f:
+            next(f, None)
+            for line in f:
+                fields = line.split()
+                if len(fields) > 3 and fields[0] != "lo" and \
+                        int(fields[3], 16) & 0x1:
+                    return True
+        return False
+    except (OSError, ValueError):
+        return True
+
+
+class PushNotifications:
+    def __init__(self, config: ConfigHelper) -> None:
+        self.apprise_log = AppriseLog.install()
+        # Failed attempts waiting CONSOLE_GROUP to be joined into one line
+        self._console_pending: Dict[Tuple[Any, ...], List[str]] = {}
+        self.server = config.get_server()
+        self.eventloop = self.server.get_event_loop()
+        self.name: str = config.get("name", "U1")
+        self.snapshot_url: Optional[str] = config.get("snapshot_url", None)
+        # "Layer N complete" is reported when layer N + 1 starts
+        self.layers_complete: int = config.getint(
+            "layers_complete", 2, minval=1, maxval=3)
+        # Print-by-object: "layer N complete" for each object, or once
+        self.first_layer_objects: str = config.get(
+            "first_layer_objects", "each")
+        # Which of loaded / unloaded the Filament loaded / unloaded row sends
+        self.filament_change_events = {
+            e.strip() for e in config.get(
+                "filament_change_events", "loaded,unloaded").split(",")}
+        self.tz: Optional[datetime.tzinfo] = None
+        tz_name = config.get("timezone", "")
+        if tz_name:
+            try:
+                from zoneinfo import ZoneInfo
+                self.tz = ZoneInfo(tz_name)
+            except Exception as e:
+                logging.warning("[push_notifications] time zone %s "
+                                "unavailable, ETA shown as time left only: %s",
+                                tz_name, e)
+        self.min_level: int = config.getint("min_level", 1, minval=1)
+        self.settle_time: float = config.getfloat(
+            "settle_time", 3., minval=0.)
+        self.repeat_interval: float = config.getfloat(
+            "repeat_interval", 60., minval=0.)
+        self.spoolman_url: str = config.get("spoolman_url", "").rstrip("/")
+        self.filament_low_percent: float = config.getfloat(
+            "filament_low_percent", 10., minval=0., maxval=100.)
+        self.filament_low_grams: float = config.getfloat(
+            "filament_low_grams", 50., minval=0.)
+        # Warn at print start about a loaded spool Spoolman shows at 0 g
+        # ("amount unknown"); off for people who don't track weights
+        self.filament_unknown: bool = config.getboolean(
+            "filament_unknown", True)
+        # The option is driver_temp: driver_hot is the row
+        self.driver_hot: float = config.getfloat(
+            "driver_temp", DRIVER_HOT_DEFAULT, minval=40., maxval=150.)
+        self._driver_hot_sent = False
+        self._filament_job = 0      # bumped per job; stops an old watcher
+        self._job_map: List[Any] = []       # extruder_map_table at start
+        self._job_tools: Set[int] = set()   # slicer filaments the job uses
+        self._job_weights: Dict[int, float] = {}  # grams per slicer filament
+        self._switched_to: Set[int] = set() # channels refilled from
+        self._job_ptc: Dict[str, Any] = {}  # print_task_config at start
+        # Filament still needed is measured, not estimated: the slicer's
+        # total for each slicer filament minus what Spoolman says its spools
+        # used since the print job started (see _need_now)
+        self._job_progress0 = 0.            # file progress the watch began at
+        self._spool_start: Dict[int, float] = {}   # spool id -> g at start
+        self._spool_now: Dict[int, float] = {}     # spool id -> g, latest
+        self._tool_spools: Dict[int, Set[int]] = {}  # slicer filament -> spools
+        # Email thread of the current print: {"id", "file"}; kept across
+        # restarts so a power-loss recovery continues the same thread
+        self._thread: Optional[Dict[str, str]] = None
+        self._job_ended = -1e9   # monotonic time the last job finished
+        # Bumped when a job starts or ends: an await that outlives its job
+        # (seeding, the filament watch) checks it and gives up
+        self._job_gen = 0
+        # Klipper keeps print_stats.exception after a fault-pause is
+        # resumed; the fault is over, and must not colour a later pause or
+        # cancel. A new fault arrives as an exception event and clears this.
+        self._stale_fault: Optional[FaultKey] = None
+        self._pl_file = ""       # file of the print a power loss stopped
+        # Spools already reported as running low (spool id -> time)
+        self._low_sent: Optional[Dict[str, float]] = None
+        try:
+            data_path = self.server.get_app_args().get("data_path") or ""
+        except Exception:
+            data_path = ""
+        data_path = data_path or "/home/lava/printer_data"
+        self._low_path = os.path.join(data_path, ".push_notifications.json")
+        self.web_ui_url: str = config.get("web_ui_url", "")
+        self.camera_url: str = config.get("camera_url", "")
+        self.rows: Dict[str, Tuple[str, List[Destination]]] = {}
+        for rid in ROW_IDS:
+            image = ""
+            dests: List[Destination] = []
+            for key, email in ((rid, False), (f"{rid}_email", True),
+                               (f"{rid}_webhook", False)):
+                value = self._option(config, key)
+                if not value:
+                    continue
+                kind, _, url = value.partition(",")
+                kind, url = kind.strip(), url.strip()
+                if kind not in IMAGE_KINDS or not url:
+                    raise config.error(
+                        f"[{config.get_name()}] {key}: expected "
+                        "'<render|snapshot|spool|none>, <url>'")
+                ap = apprise.Apprise()
+                if not ap.add(url):
+                    raise config.error(f"[{config.get_name()}] {key}: "
+                                       "invalid notification URL")
+                for srv in ap:
+                    srv.socket_read_timeout = max(
+                        srv.socket_read_timeout, SEND_READ_TIMEOUT)
+                    srv.socket_connect_timeout = max(
+                        srv.socket_connect_timeout, SEND_CONNECT_TIMEOUT)
+                channel = "email" if email else url.split(":", 1)[0]
+                channel = {"ntfys": "ntfy", "pover": "pushover",
+                           "gotifys": "gotify",
+                           "tgram": "telegram", "discordhook": "discord",
+                           "discorddm": "discord", "json": "webhook",
+                           "jsons": "webhook"}.get(
+                    channel, channel)
+                image = image or kind
+                dests.append(Destination(channel, ap, email))
+            if dests:
+                self.rows[rid] = (image, dests)
+
+        self._tasks: Set[asyncio.Task] = set()
+        # Faults already reported: key -> monotonic time
+        self._faults_sent: Dict[FaultKey, float] = {}
+        # Send order per channel (see ChannelGate); channels are independent
+        self._gates: Dict[str, ChannelGate] = {}
+        self._faults_pending: Set[FaultKey] = set()
+        self._last_fault_send = 0.
+        self._ready_once = False
+        # Per-job state
+        self._job_active = False
+        self._job_done_sent = False
+        self._first_layer_sent = False
+        self._layer_started_sent = False
+        self._milestones_sent: Set[int] = set()
+        self._gcode_bytes: Tuple[Any, Any] = (None, None)
+        self._job_filename = ""
+        # Print-by-object: the object being printed, the layer each began
+        # on, and the objects already reported
+        self._by_object = False
+        # Pauses in the print job's file (see _scan_pauses) and the ones
+        # already reported, by index
+        self._job_pauses: List[Dict[str, Any]] = []
+        self._pauses_seen: Set[int] = set()
+        self._obj_cur: Optional[str] = None
+        self._obj_start: Dict[str, int] = {}
+        self._obj_first_sent: Set[str] = set()
+        self._status: Dict[str, Dict[str, Any]] = {
+            "print_stats": {}, "virtual_sdcard": {}, "print_task_config": {},
+            "exclude_object": {}, "machine_state_manager": {},
+            "idle_timeout": {}, ACE_OBJECT: {},
+            **{d: {} for d in DRIVERS}, **{e: {} for e in EXTRUDERS}}
+        self._cal_busy_at = 0.      # when Klipper was last seen busy
+        # Filament loaded / unloaded: last reported filament_exist per
+        # toolhead (None until seeded at klippy_ready), the filament each
+        # toolhead last had (to name what was unloaded), pending changes
+        self._exist_seen: Optional[List[bool]] = None
+        self._exist_names: Dict[int, str] = {}
+        self._exist_gen = 0
+        # Chamber: the printer's heater_generic objects, whether it has
+        # Snapmaker's chamber sensor / purifier / a DragonBreath (found at
+        # klippy_ready), and this job's chamber state (see _track_chamber)
+        self._ch_heaters: List[str] = []
+        self._ch_sensor = False
+        self._ch_purifier = False
+        self._ch_device = False
+        self._ch: Dict[str, Any] = {}
+        self._calibrating: Optional[int] = None  # main_state of a running one
+        self._refills = 0      # refills from a backup spool seen so far
+        # multiACE (see _track_ace): found at klippy_ready; the last
+        # head_source seen; heads with a runout being held; slots already
+        # reported empty this job
+        self._ace_on = False
+        self._ace_src: Dict[str, Any] = {}
+        self._ace_runouts: Set[int] = set()
+        self._slot_empty_sent: Set[Tuple[int, int]] = set()
+        self._cal_action: Optional[int] = None   # its last action_code
+        self._cal_hold = 0                       # bumps on every action change
+
+        self.server.register_event_handler(
+            "job_state:state_changed", self._on_job_event)
+        self.server.register_event_handler(
+            EXCEPTION_EVENT, self._on_exception)
+        self.server.register_event_handler(
+            "server:klippy_shutdown", self._on_klippy_shutdown)
+        self.server.register_event_handler(
+            "server:klippy_ready", self._on_klippy_ready)
+        self.server.register_remote_method(REMOTE_METHOD, self._on_remote)
+        # RESPOND PREFIX=notify MSG="title || message || priority"
+        self.macro_priority: str = config.get("macro_priority", "default")
+        self.server.register_event_handler(
+            "server:gcode_response", self._on_gcode_response)
+        logging.info("[push_notifications] enabled: %s", ", ".join(
+            f"{rid} ({'+'.join(d.channel for d in dests)})"
+            for rid, (_, dests) in self.rows.items()) or "none")
+
+    # ---- helpers -------------------------------------------------------
+
+    @staticmethod
+    def _option(config: ConfigHelper, key: str) -> Optional[str]:
+        """An option as a template: the URLs refer to their tokens and
+        passwords as {secrets.notifications.<name>}, kept in Moonraker's
+        secrets file (never served or logged) by notifications-config.py."""
+        if config.get(key, None) is None:
+            return None
+        try:
+            return str(config.gettemplate(key).render()).strip()
+        except Exception as e:
+            raise config.error(f"[{config.get_name()}] {key}: {e}")
+
+
+    def _spawn(self, coro: Awaitable) -> None:
+        task = self.eventloop.create_task(coro)
+        self._tasks.add(task)
+
+        def _done(t: asyncio.Task) -> None:
+            self._tasks.discard(t)
+            if not t.cancelled() and t.exception() is not None:
+                logging.error("[push_notifications] task failed: %s",
+                              t.exception(), exc_info=t.exception())
+        task.add_done_callback(_done)
+
+    async def _query(self, objects: Dict[str, Any]) -> Dict[str, Any]:
+        kapis: APIComp = self.server.lookup_component("klippy_apis")
+        try:
+            return await kapis.query_objects(objects, default={})
+        except Exception as e:
+            logging.error("[push_notifications] state query failed: %s", e)
+            return {}
+
+    def _klippy_shutdown(self) -> bool:
+        try:
+            kconn = self.server.lookup_component("klippy_connection")
+            return kconn.state == KlippyState.SHUTDOWN
+        except Exception:
+            return False
+
+    def _live_fault(self, ps: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """The fault in print_stats, unless it's the one a resume already
+        put behind us (Klipper doesn't clear it on RESUME)."""
+        ex = coded(ps)
+        if ex is not None and fault_key(ex) == self._stale_fault:
+            return None
+        return ex
+
+    def _fault_recent(self, key: FaultKey) -> bool:
+        last = self._faults_sent.get(key)
+        return last is not None and \
+            time.monotonic() - last < self.repeat_interval
+
+    def _mark_fault(self, key: FaultKey) -> None:
+        self._faults_sent[key] = time.monotonic()
+        self._last_fault_send = time.monotonic()
+
+    def _fault_row(self) -> Optional[str]:
+        """Where a fault that ended a print is reported."""
+        if "error" in self.rows:
+            return "error"
+        if "cancelled" in self.rows:
+            return "cancelled"
+        return None
+
+    def _fetch_snapshot_sync(self, quiet: bool = False) -> Optional[str]:
+        if not self.snapshot_url:
+            return None
+        try:
+            with urllib.request.urlopen(
+                    self.snapshot_url, timeout=SNAPSHOT_TIMEOUT) as resp:
+                data = resp.read(SNAPSHOT_MAX + 1)
+        except Exception as e:
+            if not quiet:
+                logging.warning("[push_notifications] no snapshot: %s", e)
+            return None
+        if not data.startswith(b"\xff\xd8") or len(data) > SNAPSHOT_MAX:
+            logging.warning("[push_notifications] snapshot is not a JPEG")
+            return None
+        tmpdir = tempfile.mkdtemp(prefix="push_notifications_")
+        path = os.path.join(tmpdir, "snapshot.jpg")
+        try:
+            with open(path, "wb") as f:
+                f.write(data)
+        except OSError as e:
+            shutil.rmtree(tmpdir, ignore_errors=True)
+            logging.warning("[push_notifications] snapshot not saved: %s", e)
+            return None
+        return path
+
+    async def _fetch_snapshot(self, quiet: bool = False) -> Optional[str]:
+        return await self.eventloop.run_in_thread(
+            self._fetch_snapshot_sync, quiet)
+
+    async def _wait_for_snapshot(self, timeout: float) -> Optional[str]:
+        """Snapshot, waiting up to `timeout` for the camera to come up."""
+        deadline = time.monotonic() + timeout
+        while True:
+            last = time.monotonic() + PL_CAMERA_POLL >= deadline
+            path = await self._fetch_snapshot(quiet=not last)
+            if path is not None or last:
+                return path
+            await asyncio.sleep(PL_CAMERA_POLL)
+
+    def _thumbnail(self, filename: str) -> Optional[str]:
+        try:
+            fm = self.server.lookup_component("file_manager")
+            meta = fm.get_metadata_storage().get(filename, {}) or {}
+            root = fm.get_directory("gcodes")
+        except Exception as e:
+            logging.warning("[push_notifications] metadata lookup failed: %s",
+                            e)
+            return None
+        thumbs = [t for t in meta.get("thumbnails") or []
+                  if t.get("relative_path")]
+        if not thumbs:
+            return None
+        best = max(thumbs, key=lambda t: t.get("width", 0) or 0)
+        rel = best["relative_path"]
+        for path in (os.path.join(root, os.path.dirname(filename), rel),
+                     os.path.join(root, rel)):
+            if os.path.isfile(path):
+                return path
+        return None
+
+    async def _send(
+        self, rid: str, title: str, body: str,
+        filename: str = "", snapshot: Optional[str] = None,
+        snapshot_ready: bool = False, delay: float = 0.,
+        camera_wait: float = 0.,
+    ) -> bool:
+        """Send one notification to each of its destinations; images are
+        optional and never block it.
+
+        `delay` postpones the snapshot (e.g. until the head has moved away
+        after a pause). Each channel sends one notification at a time, in
+        the order they happened, so one that is retrying or delayed is not
+        overtaken (e.g. resumed arriving before paused). `camera_wait`
+        gives the camera that long to come up (e.g. right after boot).
+        """
+        row = self.rows.get(rid)
+        if row is None:
+            return False
+        image, dests = row
+        # Take a place in each channel's queue now, before any waiting
+        tickets = [self._reserve(d.channel, rid) for d in dests]
+        try:
+            if delay:
+                await asyncio.sleep(delay)
+            if camera_wait and image == "snapshot" and not snapshot_ready:
+                path = await self._wait_for_snapshot(camera_wait)
+            else:
+                path = await self._image(image, filename, snapshot,
+                                         snapshot_ready)
+            named = self._named_copy(path, title, filename)
+            report: List[Dict[str, Any]] = []
+            try:
+                results = self._outcomes(rid, dests, await asyncio.gather(*(
+                    self._deliver(rid, d, t, [(title, body, named)], report)
+                    for d, t in zip(dests, tickets)), return_exceptions=True))
+                self._console_report(report)
+            finally:
+                if named is not None and named != path:
+                    shutil.rmtree(os.path.dirname(named), ignore_errors=True)
+                if path is not None and image == "snapshot":
+                    shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+        finally:
+            for t in tickets:
+                await t.gate.done(t.ticket)
+        return all(results)
+
+    @staticmethod
+    def _outcomes(rid: str, dests: List[Destination],
+                  results: List[Any]) -> List[bool]:
+        """gather(return_exceptions=True) hands back exception objects,
+        which are truthy: a delivery that crashed is logged and counts as
+        failed, not sent."""
+        out = []
+        for d, r in zip(dests, results):
+            if isinstance(r, BaseException):
+                logging.error("[push_notifications] %s (%s): send crashed: "
+                              "%r", rid, d.channel, r, exc_info=r)
+                out.append(False)
+            else:
+                out.append(bool(r))
+        return out
+
+    def _image_name(self, title: str, filename: str, ext: str) -> str:
+        """File name for a notification's picture, so saved or exported
+        images say what they were: time, printer, notification, file, e.g.
+        2026-10-22_17-05-03_U1-martha_50pct_Benchy.jpg. Letters, digits,
+        . _ - only (it is also the email's inline image reference)."""
+        now = datetime.datetime.now(self.tz) if self.tz else \
+            datetime.datetime.now()
+        # The notification as its title says it, without the emoji and the
+        # printer's name ("⏳ U1-martha 50%" -> "50%")
+        event = title.split(" ", 1)[1] if " " in title else title
+        if event.startswith(self.name + " "):
+            event = event[len(self.name) + 1:]
+        event = event.replace("%", "pct")
+
+        def clean(text: str, cap: int) -> str:
+            text = re.sub(r"[^A-Za-z0-9._-]+", "-", text).strip("-.")
+            return text[:cap].rstrip("-.")
+        parts = [now.strftime("%Y-%m-%d_%H-%M-%S"), clean(self.name, 32),
+                 clean(event, 48), clean(shown(filename), 64)]
+        return "_".join(p for p in parts if p) + ext
+
+    def _named_copy(
+        self, path: Optional[str], title: str, filename: str = ""
+    ) -> Optional[str]:
+        """A copy of the picture under its descriptive name, in its own
+        temporary folder (the original may be a Moonraker thumbnail, or
+        shared with another notification). The original on failure."""
+        if path is None:
+            return None
+        try:
+            name = self._image_name(title, filename or self._job_filename,
+                                    os.path.splitext(path)[1] or ".jpg")
+            tmpdir = tempfile.mkdtemp(prefix="push_notifications_")
+            dest = os.path.join(tmpdir, name)
+            shutil.copyfile(path, dest)
+            return dest
+        except Exception as e:
+            logging.warning("[push_notifications] image name: %s", e)
+            return path
+
+    def _reserve(self, channel: str, rid: str) -> Ticket:
+        """Place in a channel's send order, taken when the notification
+        happens."""
+        gate = self._gates.setdefault(channel, ChannelGate())
+        return Ticket(gate, gate.ticket(rid in URGENT_ROWS), time.monotonic())
+
+    def _prepare(
+        self, rid: str, dest: Destination, title: str, body: str,
+        path: Optional[str]
+    ) -> Tuple[str, str, Dict[str, str]]:
+        """Title, text and (email) headers for one destination: the same for
+        every kind of notification. Email: HTML card and thread headers;
+        Telegram: escaped HTML and named links; Discord: escaped Markdown and
+        links."""
+        if dest.email:
+            return self._email_prepare(rid, title, body, path)
+        if dest.channel == "telegram":
+            title, body = self._telegram_prepare(rid, title, body)
+        elif dest.channel == "gotify":
+            body = self._gotify_markdown(body.strip() or title)
+            links = " · ".join(f"[{self._md_escape(t)}]({u})"
+                               for t, u in self._links(rid))
+            if links:
+                body += "\n\n" + links
+        elif dest.channel == "discord" and discord is not None:
+            body = discord.escape(body.strip() or title)
+            links = " · ".join(discord.link(t, u) for t, u in self._links(rid))
+            if links:
+                body += "\n\n" + links
+        return title, body, {}
+
+    @staticmethod
+    def _md_escape(text: str) -> str:
+        return re.sub(r"([\\`*_\[\]<>#|~])", r"\\\1", text)
+
+    def _gotify_markdown(self, text: str) -> str:
+        """Gotify shows Markdown: escape it, and keep line breaks (a single
+        newline is a space in Markdown)."""
+        return "\n\n".join(
+            "  \n".join(self._md_escape(line) for line in para.split("\n"))
+            for para in text.split("\n\n"))
+
+    def _email_prepare(
+        self, rid: str, title: str, body: str, path: Optional[str] = None
+    ) -> Tuple[str, str, Dict[str, str]]:
+        """Emails about one print go in one thread: the same subject
+        (printer and file name; the notification's title moves into the
+        email) and References to the same thread id. Others keep their
+        title as subject. Sent as an HTML card (push_notifications_email)
+        with the image inline. The headers are set right before each attempt
+        (the channel sends one at a time)."""
+        thread = self._thread_for(rid)
+        headers: Dict[str, str] = {}
+        # Gmail hides text a thread already showed ("•••"), so a repeated
+        # notification (same fault twice) would look empty: the time at the
+        # top and bottom keeps every email distinct.
+        now = datetime.datetime.now(self.tz) if self.tz else \
+            datetime.datetime.now()
+        subject = title
+        if thread is not None:
+            subject = f"{self.name}: {shown(thread['file'])}"
+            ref = f"<{thread['id']}@push-notifications.u1>"
+            headers = {"In-Reply-To": ref, "References": ref}
+        text = body.strip() or title
+        if email_html is not None:
+            page = email_html.render(
+                title, text, self._links(rid), NOTIFY_TYPES.get(rid, "info"),
+                os.path.basename(path) if path else None, now, self.name)
+            return subject, page, headers
+        body = self._lines(text, "", *(f"{t}: {u}" for t, u in
+                                       self._links(rid)))
+        if thread is not None:
+            body = self._lines(f"{title} · {now:%H:%M}", "", body, "",
+                               f"Sent {now:%Y-%m-%d %H:%M:%S}")
+        return subject, body, headers
+
+    def _thread_for(self, rid: str) -> Optional[Dict[str, str]]:
+        self._low_load()          # restores the thread after a restart
+        th = self._thread
+        if th is None:
+            return None
+        if rid in THREAD_ROWS:
+            return th
+        if rid == "power_loss":
+            return th if self._pl_file and \
+                self._pl_file == os.path.basename(th["file"]) else None
+        # Faults: while printing, or right as the print ended
+        if self._job_active or (
+                time.monotonic() - self._job_ended < THREAD_FAULT_WINDOW):
+            return th
+        return None
+
+    def _thread_start(self, filename: str, recovered: bool) -> None:
+        self._low_load()
+        if recovered and self._thread and self._thread["file"] == filename:
+            return              # power-loss recovery: same thread
+        self._thread = {"id": f"{int(time.time())}.{os.getpid()}."
+                              f"{abs(hash(filename)) % 100000}",
+                        "file": filename}
+        self._low_save()
+
+    def _telegram_prepare(
+        self, rid: str, title: str, body: str
+    ) -> Tuple[str, str]:
+        """Telegram is sent as HTML: the text is escaped, and the links
+        are added as named links. Apprise joins blank lines in HTML, so a
+        blank line is kept as a line with a space."""
+        def esc(t: str) -> str:
+            return html.escape(t, quote=False)
+        text = esc(body.strip() or title)
+        links = " · ".join(f'<a href="{html.escape(u)}">{esc(t)}</a>'
+                           for t, u in self._links(rid))
+        if links:
+            text += "\n\n" + links
+        return esc(title), text.replace("\n\n", "\n \n")
+
+    def _links(self, rid: str) -> List[Tuple[str, str]]:
+        """(name, url) of the links added to emails and Telegram."""
+        out = []
+        if self.web_ui_url:
+            out.append(("Web UI", self.web_ui_url))
+        if self.camera_url:
+            out.append(("Live Camera", self.camera_url))
+        if rid in FAULT_ROWS:
+            out.append(("Error Index", ERROR_INDEX_URL))
+        return out
+
+    async def _image(
+        self, image: str, filename: str, snapshot: Optional[str],
+        snapshot_ready: bool
+    ) -> Optional[str]:
+        if image == "snapshot":
+            return snapshot if snapshot_ready else await self._fetch_snapshot()
+        if image == "render" and filename:
+            return self._thumbnail(filename)
+        return None
+
+    async def _wait_network(self, rid: str, title: str = "") -> None:
+        if has_network():
+            return
+        logging.info("[push_notifications] %s: no network, waiting up to "
+                     "%ds", rid, NETWORK_WAIT)
+        if title:
+            self._console_join(("wait", title), "")
+        deadline = time.monotonic() + NETWORK_WAIT
+        while time.monotonic() < deadline:
+            await asyncio.sleep(NETWORK_POLL)
+            if has_network():
+                logging.info("[push_notifications] %s: network is up", rid)
+                return
+        logging.warning("[push_notifications] %s: still no network, "
+                        "trying anyway", rid)
+
+    async def _deliver(
+        self, rid: str, dest: Destination, t: Ticket,
+        msgs: List[Tuple[str, str, Optional[str]]],
+        report: Optional[List[Dict[str, Any]]] = None
+    ) -> bool:
+        """Send one or more messages (title, text, image) to one
+        destination, in its channel's turn. Doesn't remove the images
+        (shared by destinations). Each outcome goes in `report`, for the
+        console."""
+        ok = True
+        for shown_title, body, path in msgs:
+            title, body, headers = self._prepare(rid, dest, shown_title,
+                                                 body, path)
+            result: Dict[str, Any] = dict(title=shown_title,
+                                          channel=dest.channel)
+            try:
+                ok = await self._attempts(rid, dest, t, title, body, headers,
+                                          path, result) and ok
+            except Exception as e:
+                # Reported on the console as a failure too (the caller
+                # logs it with its traceback)
+                result.update(ok=False, cause=f"error: {type(e).__name__}",
+                              attempts=result.get("attempts")
+                              or 1 + len(SEND_RETRY_DELAYS))
+                if report is not None:
+                    report.append(result)
+                raise
+            if report is not None:
+                report.append(result)
+        return ok
+
+    # -- console --
+
+    def _console(self, line: str) -> None:
+        try:
+            self.server.send_event("server:gcode_response", line)
+        except Exception as e:
+            logging.debug("[push_notifications] console: %s", e)
+
+    @staticmethod
+    def _services(channels: List[str]) -> str:
+        seen = sorted(set(channels), key=lambda c: CHANNEL_ORDER.index(c)
+                      if c in CHANNEL_ORDER else len(CHANNEL_ORDER))
+        return ", ".join(CHANNEL_NAMES.get(c, c) for c in seen)
+
+    def _console_join(self, key: Tuple[Any, ...], channel: str) -> None:
+        """A line that others like it (same notification, cause, attempt)
+        may join for CONSOLE_GROUP seconds before it's printed."""
+        first = key not in self._console_pending
+        self._console_pending.setdefault(key, []).append(channel)
+        if first:
+            self._spawn(self._console_flush(key))
+
+    async def _console_flush(self, key: Tuple[Any, ...]) -> None:
+        await asyncio.sleep(CONSOLE_GROUP)
+        channels = self._console_pending.pop(key, [])
+        if key[0] == "wait":
+            self._console(f"Waiting up to {NETWORK_WAIT / 60:.0f} minutes "
+                          f"for network to return, to send notification "
+                          f"\"{key[1]}\"")
+            return
+        _kind, title, cause, attempt, attempts, retry = key
+        self._console(f"!! Failed to send notification \"{title}\" to "
+                      f"{self._services(channels)} ({cause}), attempt "
+                      f"{attempt}/{attempts}, will retry in {retry} seconds")
+
+    def _console_report(self, report: List[Dict[str, Any]]) -> None:
+        """After a notification's sends: what went where, then what
+        failed for good (one line per cause)."""
+        titles: List[str] = []
+        for r in report:
+            if r["title"] not in titles:
+                titles.append(r["title"])
+        for title in titles:
+            mine = [r for r in report if r["title"] == title]
+            sent = [r for r in mine if r.get("ok")]
+            if sent:
+                pic = [r["channel"] for r in sent if r.get("picture")]
+                text = [r["channel"] for r in sent if not r.get("picture")]
+                parts = []
+                if pic:
+                    parts.append(f"{self._services(pic)}, with picture")
+                if text:
+                    parts.append(self._services(text))
+                self._console(f"Sent notification \"{title}\" to "
+                              + ", and to ".join(parts))
+            causes: Dict[Tuple[str, int], List[str]] = {}
+            for r in mine:
+                if not r.get("ok") and r.get("attempts"):
+                    causes.setdefault((r.get("cause") or "failed",
+                                       r["attempts"]), []).append(r["channel"])
+            for (cause, n), channels in causes.items():
+                self._console(f"!! Failed to send notification \"{title}\" "
+                              f"to {self._services(channels)} ({cause}), "
+                              f"attempt {n}/{n}")
+
+    def _expired(self, rid: str, t: Ticket) -> bool:
+        return rid in EXPIRING_ROWS and \
+            time.monotonic() - t.created > STATUS_EXPIRY
+
+    async def _attempts(
+        self, rid: str, dest: Destination, t: Ticket, title: str, body: str,
+        headers: Dict[str, str], path: Optional[str],
+        result: Optional[Dict[str, Any]] = None
+    ) -> bool:
+        """One message with retries. The channel is busy only during an
+        attempt, but this notification's ticket keeps the channel's later
+        (non-fault) notifications waiting until it is sent or given up,
+        so they arrive in order; a fault can go ahead between attempts."""
+        what = f"{rid} ({dest.channel})"
+        ap = dest.ap
+        body = body.strip() or title
+        if dest.channel == "gotify":
+            path = None         # Gotify messages can't carry attachments
+        ok = False
+        attempts = 1 + len(SEND_RETRY_DELAYS)
+        kind = NOTIFY_TYPES.get(rid, "info")
+        result = {} if result is None else result
+        shown_title = result.get("title", title)
+        pictured = False
+        for attempt in range(attempts):
+            if attempt:
+                await asyncio.sleep(SEND_RETRY_DELAYS[attempt - 1])
+            await self._wait_network(what, shown_title)
+            await t.gate.acquire(t.ticket)
+            try:
+                if self._expired(rid, t):
+                    self._skip(what, "too old (sent more than %d min after "
+                               "it happened)" % (STATUS_EXPIRY // 60))
+                    return False
+                gap = SEND_GAP.get(dest.channel, 0.)
+                if gap:
+                    # Holding the channel: the next one waits behind this
+                    wait = t.gate.last_sent + gap - time.monotonic()
+                    if wait > 0:
+                        await asyncio.sleep(wait)
+                if dest.email:
+                    # Thread headers for email only: a webhook's own
+                    # +Header parameters would be wiped
+                    for srv in ap:
+                        if hasattr(srv, "headers"):
+                            srv.headers = dict(headers)
+                # Each attempt waits for the server's answer before the next
+                # is scheduled. The last one is text only, in case the image
+                # is what the server rejects (e.g. no attachments allowed).
+                self.apprise_log.take(dest.channel)
+                if attempt < attempts - 1 or path is None:
+                    pictured = path is not None
+                    ok = await ap.async_notify(
+                        body=body, title=title, attach=path, notify_type=kind)
+                else:
+                    pictured = False
+                    if email_html is not None and email_html.is_page(body):
+                        last = email_html.without_image(body)
+                    else:
+                        last = body + "\n(image could not be attached)"
+                    ok = await ap.async_notify(
+                        body=last, title=title, notify_type=kind)
+            finally:
+                t.gate.last_sent = time.monotonic()
+                await t.gate.release(t.ticket)
+            if ok:
+                break
+            cause = short_cause(self.apprise_log.take(dest.channel))
+            result.update(cause=cause, attempts=attempts)
+            if attempt < attempts - 1:
+                self._console_join(
+                    ("fail", shown_title, cause, attempt + 1, attempts,
+                     SEND_RETRY_DELAYS[attempt]), dest.channel)
+                logging.warning(
+                    "[push_notifications] %s: attempt %d failed, "
+                    "retrying in %ds%s", what, attempt + 1,
+                    SEND_RETRY_DELAYS[attempt],
+                    " without the image"
+                    if attempt == attempts - 2 and path is not None
+                    else "")
+        result.update(ok=bool(ok), picture=bool(ok) and pictured)
+        if ok:
+            logging.info("[push_notifications] %s: sent", what)
+        else:
+            logging.error("[push_notifications] %s: send failed after %d "
+                          "attempts", what, attempts)
+        return bool(ok)
+
+    @staticmethod
+    def _skip(what: str, why: str) -> None:
+        logging.info("[push_notifications] %s: not sent, %s", what, why)
+
+    def _clock(self, seconds_from_now: float) -> str:
+        if self.tz is None:
+            return ""
+        now = datetime.datetime.now(self.tz)
+        at = now + datetime.timedelta(seconds=seconds_from_now)
+        fmt = "%H:%M" if at.date() == now.date() else "%a %H:%M"
+        return at.strftime(fmt)
+
+    def _time_left(self) -> str:
+        """Time left like Fluidd's default ("file") estimate:
+        print time / file progress - print time. Snapmaker's power-loss
+        recovery keeps the print time, so this holds for recovered jobs
+        too. Early in the job that ratio is far off (heating, purge and the
+        slow first layer are most of the time so far), so until
+        EARLY_PROGRESS the slicer's estimate minus the time printed is used
+        when there is one."""
+        pd = float(self._status["print_stats"].get("print_duration") or 0.)
+        progress = self._progress()
+        if progress <= 0. or progress >= 1.:
+            return ""
+        est = self._estimated_time(self._job_filename)
+        if est > 0. and (pd <= 0. or progress < EARLY_PROGRESS):
+            left = max(est - pd, est * (1. - progress) * 0.5)
+        elif pd > 0.:
+            left = pd / progress - pd
+        else:
+            return ""
+        clock = self._clock(left)
+        # "~": time left is an estimate (the slicer estimate is labelled)
+        return f"~{format_duration(left)} left" + (f", ETA {clock}" if clock
+                                                   else "")
+
+    def _estimated_time(self, filename: str) -> float:
+        try:
+            fm = self.server.lookup_component("file_manager")
+            meta = fm.get_metadata_storage().get(filename, {}) or {}
+            return float(meta.get("estimated_time") or 0.)
+        except Exception:
+            return 0.
+
+    def _slicer_estimate(self, filename: str) -> str:
+        est = self._estimated_time(filename)
+        if est <= 0.:
+            return ""
+        clock = self._clock(est)
+        return f"Estimated print time {format_duration(est)}" + (
+            f", ETA {clock}" if clock else "")
+
+    @staticmethod
+    def _lines(*parts: str) -> str:
+        return "\n".join(p for p in parts if p)
+
+    def _title(self, key: str, **kw: Any) -> str:
+        return TITLES[key].format(name=self.name, **kw)
+
+    # ---- job events ----------------------------------------------------
+
+    async def _on_job_event(
+        self, job_event: JobEvent, prev_stats: Dict[str, Any],
+        new_stats: Dict[str, Any]
+    ) -> None:
+        ps = new_stats
+        filename = ps.get("filename") or ""
+        ex = self._live_fault(ps)
+        if job_event == JobEvent.STARTED:
+            self._stale_fault = None
+            self._job_gen += 1
+            gen = self._job_gen
+            progress = await self._start_job(filename)
+            if gen != self._job_gen:
+                self._job_active = False    # it ended while being seeded
+                return
+            # Snapmaker resumes a power-loss print as a new job, part-way
+            # into the file with its print time kept. A small file's start
+            # G-code alone is past 1 %, so the print time decides there.
+            recovered = progress >= RECOVERY_MIN_PROGRESS and (
+                float(ps.get("print_duration") or 0.) > RECOVERY_MIN_TIME
+                or progress >= RECOVERY_SURE_PROGRESS)
+            self._thread_start(filename, recovered)
+            if recovered:
+                # Snapmaker resumes a power-loss print as a new job
+                self._spawn(self._send(
+                    "resumed", self._title("recovered"),
+                    self._lines(shown(filename), self._time_left())))
+            else:
+                self._spawn(self._send(
+                    "started", self._title("started"),
+                    self._lines(shown(filename),
+                                self._slicer_estimate(filename),
+                                self._queue_line(filename, starting=True),
+                                self._pauses_line()),
+                    filename=filename))
+            # After the started notification has taken its place in the
+            # queues, so filament warnings always arrive after it
+            self._start_filament_watch(filename, progress, check_start=True)
+        elif job_event == JobEvent.PAUSED:
+            if ex is not None and "error" in self.rows and \
+                    self._refill_expected(ex):
+                self._mark_fault(fault_key(ex))
+                self._spawn(self._runout_hold(filename, ex))
+            elif ex is not None and "error" in self.rows:
+                self._mark_fault(fault_key(ex))
+                self._spawn(self._send(
+                    "error", self._title("error", kind="paused"),
+                    f"{shown(filename)}\n{describe(ex)}",
+                    delay=PAUSE_SNAPSHOT_DELAY))
+            elif "paused" in self.rows and self._job_pauses:
+                self._spawn(self._file_pause_alert(filename))
+            else:
+                self._spawn(self._send(
+                    "paused", self._title("paused"), shown(filename),
+                    delay=PAUSE_SNAPSHOT_DELAY))
+        elif job_event == JobEvent.RESUMED:
+            self._driver_hot_sent = False   # a hot driver may warn again
+            if ex is not None:
+                self._stale_fault = fault_key(ex)
+            self._status["print_stats"].update(
+                {k: ps[k] for k in ("print_duration",) if k in ps})
+            self._spawn(self._send(
+                "resumed", self._title("resumed"),
+                self._lines(shown(filename), self._time_left())))
+        elif job_event == JobEvent.ERROR:
+            # A Klipper shutdown ends the job with an error too: that goes
+            # to the shutdown row (the exception handler would otherwise
+            # find it already reported here)
+            shutdown = self._klippy_shutdown()
+            rid = "shutdown" if shutdown else "error"
+            if self._job_done_sent or \
+                    (ex is not None and self._fault_recent(fault_key(ex))):
+                self._skip(rid, "already reported")
+            elif rid in self.rows:
+                if ex is not None:
+                    self._mark_fault(fault_key(ex))
+                    detail = f"{describe(ex)}"
+                else:
+                    detail = ps.get("message") or "Print failed"
+                if shutdown:
+                    self._last_fault_send = time.monotonic()
+                self._spawn(self._send(
+                    rid, self._title("shutdown") if shutdown
+                    else self._title("error", kind="error"),
+                    f"{shown(filename)}\n{detail}"))
+        elif job_event in (JobEvent.COMPLETE, JobEvent.CANCELLED):
+            if self._job_done_sent:
+                self._skip(str(job_event), "already reported by the print hook")
+            else:
+                # The print hooks did not report it (e.g. no PRINT_END)
+                logging.info("[push_notifications] %s: no print hook "
+                             "report, sending from the job event", job_event)
+                self._spawn(self._report_end(
+                    "complete" if job_event == JobEvent.COMPLETE
+                    else "cancelled", ps))
+        if job_event.finished:
+            self._job_active = False
+            self._job_ended = time.monotonic()
+            self._job_gen += 1
+            self._filament_job += 1
+
+    async def _start_job(self, filename: str, query: bool = True) -> float:
+        """Reset per-job state. Progress already made (power-loss resume,
+        Moonraker restart) is treated as already notified. The job is only
+        marked active once seeded, so status updates arriving meanwhile
+        can't report old progress."""
+        self._job_active = False
+        self._job_done_sent = False
+        if query:
+            state = await self._query(
+                {"print_stats": ["info"], "virtual_sdcard": ["file_position"]})
+            for obj in self._status:
+                self._status[obj].update(state.get(obj) or {})
+        self._gcode_bytes = self._get_gcode_bytes(filename)
+        self._job_filename = filename
+        layer = ((self._status["print_stats"].get("info") or {})
+                 .get("current_layer") or 0)
+        self._first_layer_sent = int(layer) > self.layers_complete
+        self._layer_started_sent = int(layer) >= 1
+        self._driver_hot_sent = False
+        # Chamber: a job joined past its first layer has no wait to report
+        self._ch = {"phase": "done" if int(layer) >= 1 else "none",
+                    "target": 0., "source": "", "ref": None, "ref_time": 0.,
+                    "stall_sent": False, "used": False, "faults": set(),
+                    "fault": None, "connected": None,
+                    "wait_start": 0., "announced": False, "gen": 0}
+        self._by_object = await self.eventloop.run_in_thread(
+            self._is_by_object, filename)
+        self._job_pauses = await self.eventloop.run_in_thread(
+            self._scan_pauses, filename)
+        self._pauses_seen = set()
+        self._obj_start = {}
+        self._obj_first_sent = set()
+        self._obj_cur = self._status["exclude_object"].get("current_object")
+        if self._obj_cur:
+            # Joined part-way through this object (power loss, Moonraker
+            # restart): its layers so far are unknown, so don't report them
+            self._obj_start[self._obj_cur] = -10 ** 6
+            self._obj_first_sent.add(self._obj_cur)
+        if self._by_object:
+            logging.info("[push_notifications] %s is printed by object",
+                         shown(filename))
+        pct = self._progress() * 100.
+        self._milestones_sent = {m for m in MILESTONES if m <= pct}
+        if self._first_layer_sent or self._milestones_sent:
+            self._skip("progress", f"job already at layer {layer}, {pct:.0f}%")
+        self._job_active = True
+        return pct / 100.
+
+    # ---- print hooks ---------------------------------------------------
+
+    async def _on_remote(self, event: str = "", **_kw: Any) -> None:
+        if event in ("complete", "cancelled"):
+            self._job_done_sent = True
+            state = await self._query({"print_stats": None})
+            ps = state.get("print_stats") or {}
+            ex = self._live_fault(ps)
+            reported = ex is not None and self._fault_recent(fault_key(ex))
+            if event == "cancelled" and ex is not None and not reported:
+                # Mark now, so the job 'error' event that follows a
+                # fault-cancel is not reported a second time
+                self._mark_fault(fault_key(ex))
+            self._spawn(self._report_end(event, ps, from_hook=True,
+                                         fault_reported=reported))
+        else:
+            logging.warning("[push_notifications] unknown hook event: %s",
+                            event)
+
+    async def _report_end(
+        self, event: str, ps: Dict[str, Any], from_hook: bool = False,
+        fault_reported: bool = False
+    ) -> None:
+        """`fault_reported`: the fault behind this cancel was already sent
+        with its pause, so this is a plain cancel that names it."""
+        self._job_done_sent = True
+        filename = ps.get("filename") or ""
+        ex = self._live_fault(ps)
+        if event == "complete":
+            rid, title = "complete", self._title("complete")
+            body = self._lines(
+                shown(filename),
+                "Print time: "
+                f"{format_duration(ps.get('print_duration', 0))}",
+                self._queue_line(filename, starting=False))
+        elif ex is not None and fault_reported:
+            rid, title = "cancelled", self._title("cancelled")
+            body = f"{shown(filename)}\nAfter: {describe(ex)}"
+        elif ex is not None:
+            rid = self._fault_row()
+            if rid is None:
+                return
+            if self._fault_recent(fault_key(ex)) and rid == "error" \
+                    and not from_hook:
+                self._skip("error", f"{format_code(ex)} already reported")
+                return
+            self._mark_fault(fault_key(ex))
+            title = self._title("error", kind="cancelled") \
+                if rid == "error" else self._title("cancelled")
+            body = f"{shown(filename)}\n{describe(ex)}"
+        else:
+            rid, title, body = "cancelled", self._title("cancelled"), shown(filename)
+        row = self.rows.get(rid)
+        if row is None:
+            return
+        # Grab the snapshot right away: the hook reports once the toolhead
+        # has lifted, and the stock macro keeps raising it from there
+        snapshot = await self._fetch_snapshot() if row[0] == "snapshot" \
+            else None
+        await self._send(rid, title, body, snapshot=snapshot,
+                         snapshot_ready=True)
+
+    # ---- job queue -----------------------------------------------------
+
+    def _queue_line(self, filename: str, starting: bool) -> str:
+        """Moonraker's job queue, if it has jobs: "5 prints remaining in
+        queue (total 9h 12m)". At print start the count and the time
+        include the print that just started; when a print ends they are
+        what is still queued. Nothing when the queue is empty."""
+        try:
+            jq = self.server.lookup_component("job_queue", None)
+        except Exception:
+            jq = None
+        if jq is None:
+            return ""
+        files = [str(j) for j in list(getattr(jq, "queued_jobs", {})
+                                      .values())]
+        state = getattr(jq, "queue_state", "")
+        # The queue starts its next job before taking it off the list
+        if starting and files and state in ("loading", "starting") and \
+                files[0] == filename:
+            files = files[1:]
+        if not files:
+            return ""
+        if starting:
+            files = [filename] + files
+        total = sum(self._estimated_time(f) for f in files)
+        n = len(files)
+        line = (f"Print 1/{n} remaining in queue" if starting
+                else f"{n} print{'s' if n != 1 else ''} remaining in queue")
+        return line + (f" (total {format_duration(total)})" if total > 0
+                       else "")
+
+    # ---- exceptions ----------------------------------------------------
+
+    # Event handlers must return quickly; do the waiting in a task.
+    def _on_gcode_response(self, response: str) -> None:
+        """Notifications from G-code and macros: a console line
+        "notify <title> || <message> || <priority>" (RESPOND
+        PREFIX=notify MSG=...). The title is everything before the first
+        " || ", the priority the last field if it is one of min..max, the
+        message everything in between. On printers without this component
+        the line is only console output."""
+        for line in str(response or "").splitlines():
+            if not line.startswith(MACRO_PREFIX):
+                continue
+            parts = line[len(MACRO_PREFIX):].split(MACRO_SEP)
+            priority = self.macro_priority
+            if len(parts) > 1 and parts[-1].strip().lower() in MACRO_LEVELS:
+                priority = parts.pop().strip().lower()
+            title = parts[0].strip()
+            message = MACRO_SEP.join(parts[1:]).strip()
+            rid = f"macro_{priority}"
+            if not title or rid not in self.rows:
+                if title:
+                    self._skip("macro", f"{priority} notifications are off")
+                continue
+            self._spawn(self._send(
+                rid, self._title("macro", title=title), message,
+                filename=self._job_filename if self._job_active else ""))
+
+    def _track_calibration(self) -> None:
+        """Manual calibrations (touchscreen: bed levelling, XYZ offset,
+        flow, input shaper), one row: "<which> complete" when its machine
+        state ends (idle, or straight into the next queued calibration),
+        and "user intervention needed" when it reaches a step that waits
+        for a person. The bed mesh inside a print job's start routine sets
+        the same state, so nothing is reported while a print job is
+        active."""
+        if "calibration" not in self.rows:
+            return
+        msm = self._status["machine_state_manager"]
+        try:
+            state = int(msm.get("main_state"))
+            action = int(msm.get("action_code") or 0)
+        except (TypeError, ValueError):
+            return
+        if self._job_active:
+            self._calibrating = self._cal_action = None
+            return
+        if state != self._calibrating:
+            done, self._calibrating = self._calibrating, None
+            self._cal_action = None
+            self._cal_hold += 1
+            if done is not None and state == MSM_ABNORMAL:
+                self._spawn(self._send(
+                    "calibration",
+                    self._title("calibration_failed",
+                                what=CALIBRATIONS[done]),
+                    "The printer reports an abnormal state; check the "
+                    "screen.", camera_wait=0.))
+            elif done is not None and (state == MSM_IDLE
+                                       or state in CALIBRATIONS):
+                self._spawn(self._send(
+                    "calibration",
+                    self._title("calibration", what=CALIBRATIONS[done]),
+                    "Printer is idle." if state == MSM_IDLE else
+                    f"{CALIBRATIONS[state]} starts next.", camera_wait=0.))
+            if state in CALIBRATIONS:
+                self._calibrating = state
+            else:
+                return
+        if action == self._cal_action:
+            return
+        self._cal_action = action
+        self._cal_hold += 1
+        what = CALIBRATIONS[state]
+        if action in MANUAL_CLEAN:
+            self._spawn(self._send(
+                "calibration", self._title("intervention"),
+                self._lines(what, f"Brush the nozzle of Toolhead "
+                            f"{MANUAL_CLEAN[action]}, then tap the screen."),
+                camera_wait=0.))
+        elif action == 0:
+            self._spawn(self._intervention_hold(self._cal_hold, what))
+
+    # ---- chamber temperature -------------------------------------------
+
+    def _chamber_now(self) -> Tuple[float, Optional[float], str]:
+        """(target, chamber temperature, source) right now: the first
+        heater_generic with a target, else Snapmaker's chamber wait while it
+        runs. No target: (0, None, "")."""
+        for h in self._ch_heaters:
+            st = self._status.get(h) or {}
+            try:
+                target = float(st.get("target") or 0.)
+                temp = st.get("temperature")
+                if target > 0:
+                    return target, (None if temp is None else float(temp)), h
+            except (TypeError, ValueError):
+                continue
+        pur = self._status.get("purifier") or {}
+        msm = self._status["machine_state_manager"]
+        try:
+            target = float(pur.get("desired_chamber_temp") or 0.)
+            action = int(msm.get("action_code") or 0)
+        except (TypeError, ValueError):
+            return 0., None, ""
+        if pur.get("power_detected") and target > 0:
+            temp = (self._status.get(CHAMBER_SENSOR) or {}).get("temperature")
+            waiting = action == ACTION_PREHEAT_CHAMBER
+            return target, (None if temp is None else float(temp)), \
+                "purifier" if waiting else "purifier_idle"
+        return 0., None, ""
+
+    def _track_chamber(self) -> None:
+        """Before the first layer: waiting / reached / timed out / not
+        heating. Through the whole job: DragonBreath faults and losing it."""
+        ch = self._ch
+        ps = self._status["print_stats"]
+        filename = shown(ps.get("filename") or self._job_filename)
+        layer = (ps.get("info") or {}).get("current_layer")
+        try:
+            layer = int(layer or 0)
+        except (TypeError, ValueError):
+            layer = 0
+        target, temp, source = self._chamber_now()
+        if source == DRAGONBREATH or source.endswith(" " + DRAGONBREATH):
+            ch["used"] = True
+        now = time.monotonic()
+        deg = lambda t: f"{t:.0f} °C"
+        state = lambda t, T: f"Chamber {deg(t)}, target {deg(T)}."
+        if ch["phase"] in ("none", "waiting") and temp is not None:
+            if layer >= 1:
+                if ch["phase"] == "waiting" and ch["announced"]:
+                    T = ch["target"]
+                    if temp >= T - CHAMBER_TOLERANCE:
+                        self._chamber_send("chamber_reached", "chamber_reached",
+                                           filename, state(temp, T),
+                                           "Printing…")
+                    else:
+                        self._chamber_send("chamber_fault", "chamber_timeout",
+                                           filename, state(temp, T),
+                                           "Printing below target chamber "
+                                           "temperature…")
+                ch["phase"] = "done"
+            elif ch["phase"] == "none" and target > 0 and \
+                    source != "purifier_idle" and (
+                        temp < target if source == "purifier"
+                        else temp < target - CHAMBER_TOLERANCE):
+                ch.update(phase="waiting", target=target, source=source,
+                          ref=temp, ref_time=now, wait_start=now,
+                          announced=False, gen=ch["gen"] + 1)
+                self._spawn(self._chamber_announce(ch["gen"], filename))
+            elif ch["phase"] == "waiting":
+                if target > 0 and source != "purifier_idle":
+                    ch["target"] = target
+                T = ch["target"]
+                purifier_done = ch["source"] == "purifier" and \
+                    source != "purifier"
+                if temp >= T or purifier_done:
+                    if not ch["announced"]:
+                        pass    # over before it counted as a wait: silent
+                    elif temp >= T:
+                        self._chamber_send("chamber_reached",
+                                           "chamber_reached", filename,
+                                           state(temp, T), "Printing…")
+                    else:
+                        # Snapmaker's wait gave up (no rise for its TIMEOUT)
+                        self._chamber_send("chamber_fault", "chamber_timeout",
+                                           filename, state(temp, T),
+                                           "Printing below target chamber "
+                                           "temperature…")
+                    ch["phase"] = "done"
+                elif ch["ref"] is None or \
+                        temp >= ch["ref"] + CHAMBER_STALL_RISE:
+                    ch.update(ref=temp, ref_time=now)
+                elif not ch["stall_sent"] and \
+                        now - ch["ref_time"] >= CHAMBER_STALL_TIME:
+                    ch["stall_sent"] = True
+                    self._chamber_send(
+                        "chamber_fault", "chamber_stalled", filename,
+                        f"No rise in {CHAMBER_STALL_TIME / 60:.0f} min.",
+                        f"Printer still waiting for {deg(T)} "
+                        f"(currently {deg(temp)})…")
+        if not self._ch_device:
+            return
+        dev = self._status.get(DRAGONBREATH) or {}
+        if not ch["used"]:
+            ch["connected"] = dev.get("connected")
+            return
+
+        def next_line() -> str:
+            t = (self._status.get(f"heater_generic {DRAGONBREATH}") or {}) \
+                .get("temperature")
+            t = temp if t is None else float(t)
+            if ch["phase"] == "waiting":
+                return (f"Printer still waiting for {deg(ch['target'])}"
+                        + (f" (currently {deg(t)})…" if t is not None
+                           else "…"))
+            return ("Print job continuing"
+                    + (f", chamber {deg(t)}…" if t is not None else "…"))
+        connected = dev.get("connected")
+        if ch["connected"] and connected is False:
+            self._chamber_send(
+                "chamber_fault", "chamber_disconnected", filename,
+                "DragonBreath heater not responding, should shut off when "
+                "disconnected from printer.", next_line())
+        ch["connected"] = connected
+        reason = str(dev.get("fault_reason") or "fault").strip()
+        if dev.get("fault"):
+            if ch["fault"] != reason and reason not in ch["faults"]:
+                ch["faults"].add(reason)
+                self._chamber_send(
+                    "chamber_fault", "chamber_fault", filename,
+                    f"DragonBreath heater fault: {reason}.", next_line())
+            ch["fault"] = reason
+        else:
+            ch["fault"] = None
+
+    async def _chamber_announce(self, gen: int, filename: str) -> None:
+        """"Waiting for chamber temperature", once the wait has lasted
+        CHAMBER_WAIT_MIN (a wait that ended sooner sends nothing)."""
+        await asyncio.sleep(CHAMBER_WAIT_MIN)
+        ch = self._ch
+        if not self._job_active or ch.get("gen") != gen or \
+                ch["phase"] != "waiting":
+            return
+        ch["announced"] = True
+        _target, temp, _source = self._chamber_now()
+        if temp is None:
+            temp = ch["ref"] or 0.
+        self._chamber_send("chamber_waiting", "chamber_waiting", filename,
+                           f"Chamber {temp:.0f} °C, target "
+                           f"{ch['target']:.0f} °C.", "Printer waiting…")
+
+    def _chamber_send(self, rid: str, title: str, filename: str,
+                      *lines: str) -> None:
+        if rid not in self.rows:
+            return
+        self._spawn(self._send(rid, self._title(title),
+                               self._lines(filename, *lines)))
+
+    # ---- filament loaded / unloaded ----------------------------------
+
+    def _track_filament_change(self) -> None:
+        ptc = self._status["print_task_config"]
+        exist = [bool(x) for x in (ptc.get("filament_exist") or [])]
+        if not exist:
+            return
+        for ch in range(len(exist)):
+            name = self._printer_filament(ptc, ch)
+            if name:
+                self._exist_names[ch] = name
+        if self._exist_seen is None or len(self._exist_seen) != len(exist):
+            self._exist_seen = exist        # seed: nothing to report yet
+            return
+        for ch, (was, now) in enumerate(zip(self._exist_seen, exist)):
+            if was != now:
+                self._exist_gen += 1
+                self._spawn(self._filament_change(ch, now, self._exist_gen))
+
+    async def _filament_change(self, ch: int, now: bool, gen: int) -> None:
+        await asyncio.sleep(FILAMENT_CHANGE_SETTLE)
+        if gen != self._exist_gen:
+            return      # changed again meanwhile: the newer wait reports
+        ptc = self._status["print_task_config"]
+        exist = [bool(x) for x in (ptc.get("filament_exist") or [])]
+        if ch >= len(exist) or exist[ch] != now or self._exist_seen is None:
+            return
+        if self._exist_seen[ch] == now:
+            return      # already reported (e.g. the same change twice)
+        self._exist_seen[ch] = now
+        if self._job_active or "filament_change" not in self.rows or \
+                ("loaded" if now else "unloaded") \
+                not in self.filament_change_events:
+            return      # a print job's runouts and refills say it instead
+        # Loaded: the printer's filament info arrives shortly after the
+        # sensor; unloaded: what it had (the info may be cleared by now)
+        ids = list(ptc.get("filament_spool_id") or [])
+        sid = ids[ch] if ch < len(ids) else 0
+        spool = await self._spool(sid) if now and self._spoolman_active() \
+            else None
+        remaining = self._remaining(spool)
+        name = self._spool_name(spool) or self._printer_filament(ptc, ch) \
+            or self._exist_names.get(ch, "")
+        if name:
+            self._exist_names[ch] = name
+        title = self._title("filament_loaded" if now else "filament_unloaded")
+        body = self._lines(
+            f"{self._toolhead(ch)}: {name}" if name else self._toolhead(ch),
+            f"{remaining:.0f} g left" if remaining is not None
+            and remaining > 0 else "")
+        # The spool picture: its colour from Spoolman or the printer, the
+        # amount only when Spoolman knows it
+        row = dict(toolhead=self._toolhead(ch), word="", status="ink",
+                   needs="", remaining=remaining, full=self._full_weight(spool),
+                   colour=self._spool_colour(spool, ch), name=name)
+        await self._send_parts("filament_change", [(title, body, [row])])
+
+    async def _intervention_hold(self, hold: int, what: str) -> None:
+        start = time.monotonic()
+        while True:
+            now = time.monotonic()
+            if self._status["idle_timeout"].get("state") == "Printing":
+                self._cal_busy_at = now
+            due = max(start, self._cal_busy_at) + INTERVENTION_HOLD
+            if now >= due:
+                break
+            await asyncio.sleep(min(due - now, 1.))
+            if hold != self._cal_hold or self._job_active:
+                return      # the calibration moved on (or ended) meanwhile
+        await self._send("calibration", self._title("intervention"),
+                         self._lines(what, "The screen is waiting for you."),
+                         camera_wait=0.)
+
+    async def _on_exception(self, excep: Dict[str, Any]) -> None:
+        if fault_key(excep) == self._stale_fault:
+            self._stale_fault = None    # it happened again
+        self._spawn(self._handle_exception(dict(excep)))
+
+    async def _on_klippy_shutdown(self) -> None:
+        self._spawn(self._handle_shutdown())
+
+    async def _handle_exception(self, excep: Dict[str, Any]) -> None:
+        key = fault_key(excep)
+        level = int(excep.get("level") or 0)
+        if level < self.min_level:
+            return
+        if key in self._faults_pending or self._fault_recent(key):
+            self._skip("fault", f"{format_code(excep)} already reported")
+            return
+        self._faults_pending.add(key)
+        try:
+            # Let a pause/cancel caused by this fault report it first
+            await asyncio.sleep(self.settle_time)
+            if self._fault_recent(key):
+                self._skip("fault", f"{format_code(excep)} reported with the pause or cancel")
+                return
+            state = await self._query({"print_stats": None, "webhooks": None})
+            ps = state.get("print_stats") or {}
+            shutdown = (state.get("webhooks") or {}).get("state") == "shutdown"
+            if shutdown:
+                rid, title = "shutdown", self._title("shutdown")
+            elif level <= 1:
+                rid, title = "warning", self._title("warning")
+            else:
+                rid, title = "error", self._title("error", kind="fault")
+            if rid not in self.rows:
+                return
+            details = describe(excep)
+            filename = ps.get("filename") or ""
+            if filename and ps.get("state") in ("printing", "paused"):
+                details = f"{shown(filename)}\n{details}"
+            self._mark_fault(key)
+            await self._send(rid, title, details.strip())
+        finally:
+            self._faults_pending.discard(key)
+
+    async def _handle_shutdown(self) -> None:
+        # Fallback for shutdowns that never produced a coded exception.
+        if "shutdown" not in self.rows:
+            return
+        await asyncio.sleep(self.settle_time + 2.)
+        if time.monotonic() - self._last_fault_send < self.settle_time + 10.:
+            self._skip("shutdown", "already reported with its error code")
+            return
+        state = await self._query({"print_stats": None, "webhooks": None})
+        wh = state.get("webhooks") or {}
+        if wh.get("state") != "shutdown":
+            return
+        ps = state.get("print_stats") or {}
+        msg = (wh.get("state_message") or "").strip()
+        msg = msg.splitlines()[0] if msg else "Klipper shutdown"
+        # print_stats keeps the last file name after the job: name it only
+        # if the shutdown interrupted it
+        filename = ps.get("filename") or "" \
+            if ps.get("state") in ("printing", "paused") else ""
+        self._last_fault_send = time.monotonic()
+        await self._send("shutdown", self._title("shutdown"),
+                         f"{shown(filename)}\n{msg}" if filename else msg)
+
+    # ---- print progress ------------------------------------------------
+
+    async def _on_klippy_ready(self) -> None:
+        first_ready = not self._ready_once
+        self._ready_once = True
+        kapis: APIComp = self.server.lookup_component("klippy_apis")
+        chamber = {}
+        try:
+            objs = await kapis.get_object_list(default=[])
+        except Exception:
+            objs = []
+        self._ace_on = ACE_OBJECT in objs
+        if any(r in self.rows for r in CHAMBER_ROWS):
+            self._ch_heaters = [o for o in objs
+                                if o.startswith("heater_generic ")]
+            self._ch_sensor = CHAMBER_SENSOR in objs
+            self._ch_purifier = "purifier" in objs
+            self._ch_device = DRAGONBREATH in objs
+            chamber = dict(
+                {h: ["temperature", "target"] for h in self._ch_heaters},
+                **({CHAMBER_SENSOR: ["temperature"]}
+                   if self._ch_sensor else {}),
+                **({"purifier": ["power_detected", "desired_chamber_temp"]}
+                   if self._ch_purifier else {}),
+                **({DRAGONBREATH: ["fault", "fault_reason", "connected"]}
+                   if self._ch_device else {}))
+            for obj in chamber:
+                self._status.setdefault(obj, {})
+        try:
+            status = await kapis.subscribe_objects(
+                dict({"print_stats": ["state", "filename", "info",
+                                      "print_duration"],
+                      "virtual_sdcard": ["progress", "file_position"],
+                      "exclude_object": ["objects", "current_object",
+                                         "excluded_objects"],
+                      **{d: ["temperature"] for d in DRIVERS},
+                      # Always: the runout hold and the backup-spool switch
+                      # read the toolhead map and the refill settings from
+                      # it, with or without Spoolman
+                      "print_task_config": PTC_FIELDS,
+                      **{e: NOZZLE_FIELDS for e in EXTRUDERS}},
+                     **({"machine_state_manager": ["main_state",
+                                                   "action_code"]}
+                        if "calibration" in self.rows
+                        or self._ch_purifier else {}),
+                     **({"idle_timeout": ["state"]}
+                        if "calibration" in self.rows else {}),
+                     **({ACE_OBJECT: ACE_FIELDS} if self._ace_on else {}),
+                     **chamber),
+                self._on_status_update, default={})
+        except Exception as e:
+            logging.error("[push_notifications] subscribe failed: %s", e)
+            status = {}
+        for obj in self._status:
+            self._status[obj].update(status.get(obj) or {})
+        self._calibrating = self._cal_action = None   # Klipper restarted
+        self._ace_src = self._ace_sources()
+        self._exist_seen = None
+        self._exist_gen += 1
+        self._track_filament_change()
+        self._cal_hold += 1
+        ps = self._status["print_stats"]
+        if ps.get("state") in ("printing", "paused"):
+            # Started before Moonraker: track it without re-notifying
+            await self._start_job(ps.get("filename") or "", query=False)
+            self._start_filament_watch(ps.get("filename") or "",
+                                       self._progress(), check_start=False)
+        else:
+            self._job_active = False
+        if first_ready and "power_loss" in self.rows and self._booted_recently():
+            self._spawn(self._check_power_loss())
+
+    async def _on_status_update(
+        self, data: Dict[str, Any], _eventtime: float
+    ) -> None:
+        for obj, values in data.items():
+            if obj in self._status and isinstance(values, dict):
+                self._status[obj].update(values)
+        ps = self._status["print_stats"]
+        if "print_task_config" in data and self._job_active:
+            self._check_spool_switch()
+        if (data.get("idle_timeout") or {}).get("state") == "Printing":
+            self._cal_busy_at = time.monotonic()
+        if "machine_state_manager" in data:
+            self._track_calibration()
+        if "filament_exist" in (data.get("print_task_config") or {}):
+            self._track_filament_change()
+        if ACE_OBJECT in data:
+            self._track_ace()
+        if self._job_active and self._ch:
+            self._track_chamber()
+        if not self._job_active or ps.get("state") != "printing":
+            return
+        filename = ps.get("filename") or ""
+        if "driver_hot" in self.rows and not self._driver_hot_sent and \
+                any(d in data for d in DRIVERS):
+            temps = {axis: self._status[d].get("temperature")
+                     for d, axis in DRIVERS.items()}
+            hot = [a for a, t in temps.items()
+                   if t is not None and float(t) >= self.driver_hot]
+            if hot:
+                self._driver_hot_sent = True
+                self._spawn(self._send(
+                    "driver_hot", self._title("driver_hot"),
+                    self._lines(shown(filename), *(
+                        f"{a} driver: {temps[a]:.0f} °C"
+                        + (f" (alert at {self.driver_hot:.0f} °C)"
+                           if a in hot else "")
+                        for a in DRIVERS.values()
+                        if temps[a] is not None))))
+        if self._by_object and not self._objects():
+            # No EXCLUDE_OBJECT markers (label objects off): nothing to
+            # track per object, so it's reported like a by-layer job
+            self._by_object = False
+            logging.info("[push_notifications] no object markers in %s: "
+                         "reported as one job", shown(filename))
+        if "layer_started" in self.rows and not self._layer_started_sent:
+            # Layer 1 begins once the start routine (homing, bed mesh,
+            # flow calibration) is over: time to watch the first layer
+            layer = (ps.get("info") or {}).get("current_layer")
+            if layer is not None and int(layer) >= 1:
+                self._layer_started_sent = True
+                self._spawn(self._send(
+                    "layer_started", self._title("layer_started"),
+                    self._lines(shown(filename), self._time_left())))
+        if self._by_object:
+            self._track_objects(filename)
+        elif "first_layer" in self.rows and not self._first_layer_sent:
+            layer = (ps.get("info") or {}).get("current_layer")
+            if layer is not None and int(layer) > self.layers_complete:
+                self._first_layer_sent = True
+                self._spawn(self._send(
+                    "first_layer", self._title(
+                        "first_layer",
+                        ordinal=ORDINALS[self.layers_complete]),
+                    self._lines(shown(filename), self._time_left())))
+        pct = self._progress() * 100.
+        crossed = [m for m in MILESTONES
+                   if m <= pct and m not in self._milestones_sent]
+        if crossed:
+            # Only report the highest one if several were crossed at once
+            self._milestones_sent.update(crossed)
+            for m in sorted(crossed, reverse=True):
+                if f"progress_{m}" in self.rows:
+                    self._spawn(self._send(
+                        f"progress_{m}", self._title("progress", pct=m),
+                        self._lines(shown(filename), self._time_left())))
+                    break
+
+    def _is_by_object(self, filename: str) -> bool:
+        """Whether the slicer's config block (at the end of the file) says
+        the print job is by object. Runs in a thread: it reads the file."""
+        if not filename:
+            return False
+        try:
+            fm = self.server.lookup_component("file_manager")
+            path = os.path.join(fm.get_directory("gcodes"), filename)
+            with open(path, "rb") as f:
+                f.seek(max(0, os.path.getsize(path) - CONFIG_TAIL))
+                return RX_BY_OBJECT.search(f.read()) is not None
+        except Exception as e:
+            logging.warning("[push_notifications] could not read %s: %s",
+                            shown(filename), e)
+            return False
+
+    def _scan_pauses(self, filename: str) -> List[Dict[str, Any]]:
+        """The pauses the print job's file asks for: [{offset, layer,
+        message, kind}], in file order. Runs in a thread: it reads the
+        file."""
+        if not filename:
+            return []
+        out: List[Dict[str, Any]] = []
+        try:
+            fm = self.server.lookup_component("file_manager")
+            path = os.path.join(fm.get_directory("gcodes"), filename)
+            layer = 0
+            m117 = (b"", -10 ** 9)   # last M117 text and where
+            with open(path, "rb") as f:
+                pos = 0
+                for line in f:
+                    at, pos = pos, pos + len(line)
+                    if not line.startswith((b";", b"P", b"p", b"M", b"m")):
+                        continue
+                    m = RX_LAYER.match(line)
+                    if m:
+                        layer = int(m.group(2)) + 1 if m.group(2) else layer + 1
+                        continue
+                    m = RX_M117.match(line)
+                    if m:
+                        m117 = (m.group(1).strip(), at)
+                        continue
+                    if RX_PAUSE_MARK.match(line):
+                        if out and at - out[-1]["offset"] <= PAUSE_MERGE:
+                            continue
+                        out.append(dict(offset=at, layer=layer, message="",
+                                        kind=""))
+                        continue
+                    m = RX_PAUSE_CMD.match(line)
+                    if not m:
+                        continue
+                    kind = ("filament change"
+                            if m.group(1).upper() == b"M600" else "")
+                    msg = (m.group(3) or b"").strip()
+                    if not msg and at - m117[1] <= PAUSE_MERGE:
+                        msg = m117[0]
+                    text = msg.decode("utf-8", "replace")
+                    if out and at - out[-1]["offset"] <= PAUSE_MERGE \
+                            and not out[-1]["kind"]:
+                        out[-1].update(message=out[-1]["message"] or text,
+                                       kind=kind)
+                        continue
+                    out.append(dict(offset=at, layer=layer, kind=kind,
+                                    message=text))
+        except Exception as e:
+            logging.warning("[push_notifications] could not read %s: %s",
+                            shown(filename), e)
+        if out:
+            logging.info("[push_notifications] %s has %d pause(s) in the "
+                         "file: %s", shown(filename), len(out),
+                         ", ".join(f"layer {p['layer']} @{p['offset']}"
+                                   for p in out))
+        return out
+
+    def _pauses_line(self) -> str:
+        """For the started notification: how many pauses the file has."""
+        ps = self._job_pauses
+        if not ps:
+            return ""
+        layers = [p["layer"] for p in ps if p["layer"]]
+        where = ""
+        if len(layers) == len(ps):
+            where = (f" (layer {layers[0]})" if len(layers) == 1 else
+                     " (layers " + ", ".join(str(n) for n in layers[:-1])
+                     + f" and {layers[-1]})")
+        return ("\nPrint job contains a pause" if len(ps) == 1 else
+                f"\nPrint job contains {len(ps)} pauses") + where + "."
+
+    def _file_pause(self, position: Any) -> Optional[int]:
+        """Index of the file's pause the print job stopped at, if the file
+        position is just past one of them and it hasn't been reported."""
+        try:
+            pos = int(position)
+        except (TypeError, ValueError):
+            return None
+        for i, p in enumerate(self._job_pauses):
+            if i not in self._pauses_seen and \
+                    p["offset"] <= pos <= p["offset"] + PAUSE_WINDOW:
+                return i
+        return None
+
+    async def _file_pause_alert(self, filename: str) -> None:
+        state = await self._query({"virtual_sdcard": ["file_position"]})
+        pos = (state.get("virtual_sdcard") or {}).get("file_position")
+        i = self._file_pause(pos)
+        if i is None:
+            await self._send("paused", self._title("paused"), shown(filename),
+                             delay=PAUSE_SNAPSHOT_DELAY)
+            return
+        self._pauses_seen.add(i)
+        p = self._job_pauses[i]
+        n = len(self._job_pauses)
+        what = (f"Pause {i + 1} of {n}" if n > 1 else "Pause") + (
+            f" at layer {p['layer']}" if p["layer"] else "") + (
+            " for a filament change" if p["kind"] else "")
+        line = f"{what}, as planned in the print job."
+        if p["message"]:
+            line += f' "{p["message"]}"'
+        # The Paused row's destinations at the highest priority (the
+        # file_pause row the config writes next to paused)
+        await self._send("file_pause" if "file_pause" in self.rows
+                         else "paused", self._title("file_pause"),
+                         self._lines(shown(filename), line,
+                                     "Waiting for you to resume…"),
+                         delay=PAUSE_SNAPSHOT_DELAY)
+
+    def _objects(self) -> List[str]:
+        return [str(o.get("name") or "") for o in
+                self._status["exclude_object"].get("objects") or []]
+
+    def _object_line(self, name: str) -> str:
+        """'Object 2 of 3: Assembly' for a notification body."""
+        objects = self._objects()
+        n = objects.index(name) + 1 if name in objects else 0
+        # Orca names objects <model>_id_<n>_copy_<m>; show the model, and
+        # a number when the same model is on the plate more than once
+        pretty = name
+        m = RX_OBJECT_NAME.match(name)
+        if m:
+            base = m.group(1)
+            same = [o for o in objects
+                    if (RX_OBJECT_NAME.match(o) or m).group(1) == base]
+            pretty = f"{base} #{same.index(name) + 1}" if len(same) > 1 \
+                else base
+        where = f"Object {n} of {len(objects)}" if n else "Object"
+        return f"{where}: {pretty}"
+
+    def _track_objects(self, filename: str) -> None:
+        """Print-by-object: report an object's first layers and its
+        completion. Layer numbers run on across the objects (Orca), so an
+        object's layer is counted from the layer it began on; a new object
+        beginning means the previous one is complete."""
+        ex = self._status["exclude_object"]
+        cur = ex.get("current_object") or None
+        layer = int((self._status["print_stats"].get("info") or {})
+                    .get("current_layer") or 0)
+        if cur and cur != self._obj_cur:
+            prev = self._obj_cur
+            self._obj_cur = cur
+            self._obj_start.setdefault(cur, layer)
+            if prev is not None and prev != cur and \
+                    prev not in (ex.get("excluded_objects") or []):
+                self._object_done(prev, filename)
+        cur = self._obj_cur
+        if not cur or "first_layer" not in self.rows or \
+                cur in self._obj_first_sent or \
+                cur in (ex.get("excluded_objects") or []):
+            return
+        if self.first_layer_objects != "each" and self._first_layer_sent:
+            return
+        if layer - self._obj_start.get(cur, layer) >= self.layers_complete:
+            self._obj_first_sent.add(cur)
+            self._first_layer_sent = True
+            self._spawn(self._send(
+                "first_layer",
+                self._title("first_layer",
+                            ordinal=ORDINALS[self.layers_complete]),
+                self._lines(shown(filename), self._object_line(cur),
+                            self._time_left())))
+
+    def _object_done(self, name: str, filename: str) -> None:
+        if "object_complete" not in self.rows:
+            return
+        self._spawn(self._send(
+            "object_complete", self._title("object_complete"),
+            self._lines(shown(filename), self._object_line(name),
+                        self._time_left())))
+
+    def _get_gcode_bytes(self, filename: str) -> Tuple[Any, Any]:
+        if not filename:
+            return (None, None)
+        try:
+            fm = self.server.lookup_component("file_manager")
+            meta = fm.get_metadata_storage().get(filename, {}) or {}
+            return (meta.get("gcode_start_byte"), meta.get("gcode_end_byte"))
+        except Exception as e:
+            logging.warning("[push_notifications] metadata lookup failed: %s",
+                            e)
+            return (None, None)
+
+    def _progress(self) -> float:
+        # Same calculation as Fluidd's default ("file relative"), which is
+        # also what the Snapmaker app shows.
+        sd = self._status["virtual_sdcard"]
+        start, end = self._gcode_bytes
+        pos = sd.get("file_position")
+        if start is not None and end is not None and pos is not None:
+            if pos <= start:
+                return 0.
+            if pos >= end:
+                return 1.
+            if end > start:
+                return (pos - start) / (end - start)
+        return float(sd.get("progress") or 0.)
+
+    # ---- power loss ----------------------------------------------------
+
+    @staticmethod
+    def _booted_recently() -> bool:
+        try:
+            with open("/proc/uptime") as f:
+                return float(f.read().split()[0]) < BOOT_WINDOW
+        except Exception:
+            return False
+
+    async def _check_power_loss(self) -> None:
+        # pl_env_valid is set once the MCUs have reported their saved
+        # state, which can take a while after klippy_ready.
+        deadline = time.monotonic() + PL_WAIT_TIME
+        while time.monotonic() < deadline:
+            result = await self._query({"virtual_sdcard": ["pl_env_valid"]})
+            if (result.get("virtual_sdcard") or {}).get("pl_env_valid"):
+                break
+            await asyncio.sleep(2.)
+        else:
+            return
+        filename = ""
+        env_path = next((p for p in PL_ENV_PATHS if os.path.isfile(p)), None)
+        if env_path is not None:
+            try:
+                with open(env_path, "r") as f:
+                    filename = os.path.basename(
+                        json.load(f).get("file_path") or "")
+            except Exception as e:
+                logging.warning("[push_notifications] power-loss file "
+                                "unreadable: %s", e)
+        self._pl_file = filename
+        details = "Print interrupted by power loss. " \
+            "Resume is available on the touchscreen."
+        await self._send("power_loss", self._title("power_loss"),
+                         f"{shown(filename)}\n{details}" if filename else details,
+                         camera_wait=PL_CAMERA_WAIT)
+
+    # ---- Spoolman: filament checks ----------------------------------------
+    #
+    # Toolheads are numbered 1-4 for people; channels are 0-3. The slicer's
+    # filaments (T0..) are mapped to channels by print_task_config's
+    # extruder_map_table, and each channel's Spoolman spool is in
+    # filament_spool_id. Only toolheads the print uses are checked.
+    #
+    #  * filament_short: a toolhead has not enough filament for the rest of
+    #    the print (red), or only just enough (orange, within FILAMENT_CLOSE).
+    #    Checked at print start (one notification for all toolheads at risk)
+    #    and every FILAMENT_POLL during the print (only when a toolhead gets
+    #    worse than already reported). Nothing is sent when all is fine.
+    #  * filament_low: a spool is down to filament_low_percent of a full
+    #    spool or filament_low_grams, whichever comes first. Once per spool
+    #    (remembered across restarts) until it is refilled or replaced.
+    #  * spool_switch: the printer refilled from another toolhead.
+
+    def _spoolman_active(self) -> bool:
+        return bool(self.spoolman_url) and any(
+            r in self.rows for r in SPOOLMAN_ROWS)
+
+    def _start_filament_watch(
+        self, filename: str, progress: float, check_start: bool
+    ) -> None:
+        self._job_map = list(
+            self._status["print_task_config"].get("extruder_map_table") or [])
+        self._job_ptc = dict(self._status["print_task_config"])
+        self._job_tools = set()
+        self._job_weights = {}
+        self._switched_to = set()
+        self._slot_empty_sent = set()
+        self._job_progress0 = progress
+        self._spool_start = {}
+        self._spool_now = {}
+        self._tool_spools = {}
+        self._filament_job += 1
+        self._spawn(self._filament_watch(
+            self._filament_job, filename, progress, check_start))
+
+    async def _spool(self, spool_id: int) -> Optional[Dict[str, Any]]:
+        if not spool_id:
+            return None
+        try:
+            http = self.server.lookup_component("http_client")
+            resp = await http.get(
+                f"{self.spoolman_url}/api/v1/spool/{spool_id}",
+                enable_cache=False)
+            if resp.status_code == 200:
+                return resp.json()
+            logging.warning("[push_notifications] Spoolman spool %d: HTTP "
+                            "%s", spool_id, resp.status_code)
+        except Exception as e:
+            logging.warning("[push_notifications] Spoolman spool %d: %s",
+                            spool_id, e)
+        return None
+
+    @staticmethod
+    def _remaining(spool: Optional[Dict[str, Any]]) -> Optional[float]:
+        r = (spool or {}).get("remaining_weight")
+        return float(r) if isinstance(r, (int, float)) else None
+
+    @staticmethod
+    def _full_weight(spool: Optional[Dict[str, Any]]) -> Optional[float]:
+        """A full spool's filament weight: the spool's own initial weight,
+        else the filament's net weight."""
+        sp = spool or {}
+        for w in (sp.get("initial_weight"),
+                  (sp.get("filament") or {}).get("weight")):
+            if isinstance(w, (int, float)) and w > 0:
+                return float(w)
+        return None
+
+    @staticmethod
+    def _toolhead(channel: int) -> str:
+        return f"Toolhead {channel + 1}"
+
+    @staticmethod
+    def _spool_name(spool: Optional[Dict[str, Any]]) -> str:
+        fil = (spool or {}).get("filament") or {}
+        vendor = (fil.get("vendor") or {}).get("name") or ""
+        fname = fil.get("name") or fil.get("material") or ""
+        # Spoolman filament names often already start with the vendor
+        if vendor and fname.lower().startswith(vendor.lower()):
+            vendor = ""
+        return " ".join(x for x in (vendor, fname) if x)
+
+    def _spool_colour(self, spool: Optional[Dict[str, Any]],
+                      ch: int) -> Any:
+        """The filament's colour for the picture: one RGB, or a list of
+        them for a multi-colour filament (Spoolman's multi_color_hexes,
+        else the printer's filament_color_multi), falling back to the
+        single colour (Spoolman's color_hex, the printer's rgba)."""
+        if images is None:
+            return None
+        fil = (spool or {}).get("filament") or {}
+        multi = [images.parse_hex(v) for v in
+                 str(fil.get("multi_color_hexes") or "").split(",") if v]
+        multi = [c for c in multi if c]
+        if len(multi) > 1:
+            return multi
+        single = images.parse_hex(fil.get("color_hex"))
+        if single:
+            return single
+        if multi:
+            return multi[0]
+        ptc = self._job_ptc or self._status["print_task_config"]
+        pm = list(ptc.get("filament_color_multi") or [])
+        if ch < len(pm) and isinstance(pm[ch], dict):
+            cols = [images.parse_hex(v) for v in (pm[ch].get("colors") or [])]
+            cols = [c for c in cols if c]
+            if len(cols) > 1:
+                return cols
+            if cols:
+                return cols[0]
+        cols = list(ptc.get("filament_color_rgba") or [])
+        if ch < len(cols):
+            return images.parse_hex(cols[ch])
+        return None
+
+    @staticmethod
+    def _cap(text: str, cap: Optional[int]) -> str:
+        if cap is None or len(text) <= cap:
+            return text
+        return text[:max(1, cap - 1)].rstrip() + "…"
+
+    @staticmethod
+    def _printer_filament(ptc: Dict[str, Any], ch: int) -> str:
+        """The filament as the printer knows it (no Spoolman): vendor and
+        type, e.g. "Elegoo PLA"."""
+        parts = []
+        for k in ("filament_vendor", "filament_type"):
+            v = list(ptc.get(k) or [])
+            val = str(v[ch]).strip() if ch < len(v) else ""
+            if val and val.upper() != "NONE":
+                parts.append(val)
+        return " ".join(parts)
+
+    def _desc(self, ch: int, name: str, sid: int,
+              cap: Optional[int] = None) -> str:
+        inner = ", ".join(x for x in (self._cap(name, cap),
+                                      f"spool #{sid}" if sid else "") if x)
+        return f"{self._toolhead(ch)} ({inner})" if inner \
+            else self._toolhead(ch)
+
+    def _needed_grams(self, filename: str) -> Dict[int, float]:
+        """Slicer filament weight per slicer filament (T0..)."""
+        try:
+            fm = self.server.lookup_component("file_manager")
+            meta = fm.get_metadata_storage().get(filename, {}) or {}
+        except Exception:
+            return {}
+        weights = meta.get("filament_weight")
+        if isinstance(weights, (int, float)):
+            weights = [weights]
+        if not isinstance(weights, list):
+            total = meta.get("filament_weight_total")
+            weights = [total] if total else []
+        return {i: float(w) for i, w in enumerate(weights)
+                if isinstance(w, (int, float)) and w > 0}
+
+    def _nozzle(self, ch: int) -> Tuple[Any, Any]:
+        st = self._status.get(EXTRUDERS[ch] if ch < len(EXTRUDERS)
+                              else "") or {}
+        return st.get("nozzle_diameter"), st.get("nozzle_volume_type")
+
+    @staticmethod
+    def _colour_multi(src: Dict[str, Any], c: int) -> Any:
+        """The printer compares colours on filament_color_multi (the whole
+        set, for multi-colour filaments); older firmware has only
+        filament_color_rgba."""
+        multi = list(src.get("filament_color_multi") or [])
+        if c < len(multi) and isinstance(multi[c], dict) and multi[c]:
+            return multi[c]
+        rgba = list(src.get("filament_color_rgba") or [])
+        return {"colors": [str(rgba[c])[:6].upper()]} if c < len(rgba) \
+            else None
+
+    def _refill_check(self, ptc: Dict[str, Any], ch: int, c: int,
+                      src: Dict[str, Any]) -> Tuple[bool, str]:
+        """Whether the printer may refill `ch` from `c`, as
+        print_task_config.py (cmd_INNER_AUTO_REPLENISH_FILAMENT) decides
+        it, and if not, why, in words for the notification ("" when `c`
+        isn't even the same material, which isn't worth a line)."""
+        def field(d: Dict[str, Any], k: str, i: int) -> str:
+            v = list(d.get(k) or [])
+            return str(v[i]).strip() if i < len(v) else ""
+        exist = list(ptc.get("filament_exist") or [])
+        if c < len(exist) and not exist[c]:
+            return False, ""
+        same_type = field(ptc, "filament_type", c).lower() == \
+            field(src, "filament_type", ch).lower() != ""
+        nd, nv = self._nozzle(ch)
+        cd, cv = self._nozzle(c)
+        if nd is not None and cd is not None and (nd != cd or nv != cv):
+            return False, (f"nozzle {cd} vs {nd} mm" if nd != cd
+                           else f"{cv or 'other'} nozzle vs {nv or 'other'}"
+                           ) if same_type else ""
+        if field(ptc, "filament_vendor", c).upper() in ("", "NONE"):
+            return False, ("no filament info set on the printer (vendor "
+                           "NONE)" if same_type else "")
+        for k, what in (("filament_vendor", "vendor"),
+                        ("filament_type", "type"),
+                        ("filament_sub_type", "sub-type")):
+            if field(ptc, k, c).lower() != field(src, k, ch).lower():
+                return False, (f"different {what} ({field(ptc, k, c) or 'none'}"
+                               f" vs {field(src, k, ch) or 'none'})"
+                               if same_type else "")
+        if not ptc.get("replenish_ignore_color") and \
+                self._colour_multi(ptc, c) != self._colour_multi(src, ch):
+            return False, "colour differs (refill needs an exact match)"
+        return True, ""
+
+    def _backups(self, ptc: Dict[str, Any], ch: int,
+                 attrs_from: Optional[Dict[str, Any]] = None) -> List[int]:
+        """Channels the printer can refill `ch` from, in the order it would
+        use them (each one refilled from in turn as the one before runs
+        out). `attrs_from` gives `ch`'s own filament (e.g. as it was at
+        print start, before it ran out).
+
+        print_task_config.py (cmd_INNER_AUTO_REPLENISH_FILAMENT): same
+        nozzle, a vendor set (not NONE), vendor, type and sub-type equal.
+        Of those, the first exact colour match (filament_color_multi) in
+        toolhead order; else, with "ignore colour", the nearest first
+        colour (Rec. 601 weighted RGB distance). When that spool runs out,
+        the next is chosen the same way from it."""
+        if not ptc.get("auto_replenish_filament"):
+            return []
+        ignore = bool(ptc.get("replenish_ignore_color"))
+
+        def first_colour(src: Dict[str, Any], c: int) -> str:
+            m = self._colour_multi(src, c) or {}
+            cols = list(m.get("colors") or [])
+            return str(cols[0]).upper()[:6] if cols else ""
+
+        def distance(a: str, b: str) -> float:
+            try:
+                d = [int(a[i:i + 2], 16) - int(b[i:i + 2], 16)
+                     for i in (0, 2, 4)]
+            except ValueError:
+                return float("inf")
+            return ((0.299 * d[0]) ** 2 + (0.587 * d[1]) ** 2
+                    + (0.114 * d[2]) ** 2) ** 0.5
+        ids = list(ptc.get("filament_spool_id") or [])
+        src = attrs_from or ptc
+        relaxed = dict(ptc, replenish_ignore_color=True)
+        left = [c for c in range(len(ids)) if c != ch
+                and self._refill_check(relaxed, ch, c, src)[0]]
+        order: List[int] = []
+        cur_src, cur = src, ch
+        while left:
+            exact = [c for c in left if self._colour_multi(ptc, c)
+                     == self._colour_multi(cur_src, cur)]
+            if exact:
+                pick = exact[0]
+            elif ignore:
+                tc = first_colour(cur_src, cur)
+                pick = min(left, key=lambda c: (
+                    distance(first_colour(ptc, c), tc), c))
+            else:
+                break
+            order.append(pick)
+            left.remove(pick)
+            cur_src, cur = ptc, pick
+        return order
+
+    def _refill_blockers(self, ptc: Dict[str, Any], ch: int,
+                         attrs_from: Optional[Dict[str, Any]] = None
+                         ) -> List[Tuple[int, str]]:
+        """Toolheads with the same material as `ch` that the printer will
+        not refill from, and why: the moment to fix it is now."""
+        src = attrs_from or ptc
+        ids = list(ptc.get("filament_spool_id") or [])
+        out = []
+        for c in range(len(ids)):
+            if c == ch:
+                continue
+            ok, why = self._refill_check(ptc, ch, c, src)
+            if not ok and why:
+                out.append((c, why))
+        return out
+
+    @staticmethod
+    def _status_of(remaining: float, need: float) -> str:
+        """red: not enough; orange: enough, but only just; green: fine."""
+        if remaining < need:
+            return "red"
+        if remaining < need + max(FILAMENT_CLOSE_G, need * FILAMENT_CLOSE):
+            return "orange"
+        return "green"
+
+    def _seen(self, sid: int, remaining: Optional[float]) -> None:
+        """Spoolman's weight for a spool, as read during the job."""
+        if not sid or remaining is None or remaining <= 0:
+            return
+        self._spool_start.setdefault(sid, remaining)
+        self._spool_now[sid] = remaining
+
+    def _used(self) -> Optional[Dict[int, float]]:
+        """Grams each spool lost since the job started, or None if Spoolman
+        isn't tracking usage (nothing used yet well into the print)."""
+        used = {sid: max(0., g - self._spool_now.get(sid, g))
+                for sid, g in self._spool_start.items()}
+        if sum(used.values()) < USAGE_MIN_G and \
+                self._progress() > USAGE_GRACE:
+            return None
+        return used
+
+    def _need_now(self, ch: int) -> Optional[float]:
+        """Grams the rest of the print job still needs from channel `ch`:
+        the slicer's total for the slicer filaments on it now, minus what
+        their spools (including refill spools they moved from) used since
+        the job started, per Spoolman. None when that can't be measured:
+        no slicer weights, Spoolman not tracking usage, or the watch began
+        partway through the job (e.g. power-loss recovery)."""
+        if not self._job_weights or \
+                self._job_progress0 > RECOVERY_MIN_PROGRESS:
+            return None
+        used = self._used()
+        if used is None:
+            return None
+        emap = self._job_map or []
+        tools = [t for t in self._job_weights
+                 if (emap[t] if t < len(emap) else t) == ch]
+        if not tools:
+            return None
+        total = sum(self._job_weights[t] for t in tools)
+        spools: Set[int] = set()
+        for t in tools:
+            spools |= self._tool_spools.get(t, set())
+        return max(0., total - sum(used.get(sid, 0.) for sid in spools))
+
+    # -- low-spool memory (once per spool until it is refilled) --
+
+    def _low_load(self) -> Dict[str, float]:
+        if self._low_sent is None:
+            try:
+                with open(self._low_path) as f:
+                    data = json.load(f)
+                self._low_sent = {str(k): float(v) for k, v in
+                                  (data.get("low_sent") or {}).items()}
+                th = data.get("thread")
+                if self._thread is None and isinstance(th, dict) and \
+                        th.get("id") and "file" in th:
+                    self._thread = {"id": str(th["id"]),
+                                    "file": str(th["file"])}
+            except Exception:
+                self._low_sent = {}
+        return self._low_sent
+
+    def _low_save(self) -> None:
+        try:
+            tmp = self._low_path + ".tmp"
+            state = {"low_sent": self._low_sent or {}}
+            if self._thread:
+                state["thread"] = self._thread
+            with open(tmp, "w") as f:
+                json.dump(state, f)
+            os.replace(tmp, self._low_path)
+        except Exception as e:
+            logging.warning("[push_notifications] can't save %s: %s",
+                            self._low_path, e)
+
+    def _low_threshold(self, full: Optional[float]) -> float:
+        """Whichever comes first: % of a full spool, or grams."""
+        pct = (self.filament_low_percent / 100. * full
+               if self.filament_low_percent and full else 0.)
+        return max(pct, self.filament_low_grams or 0.)
+
+    def _low_mark(self, sid: int) -> None:
+        self._low_load()[str(sid)] = time.time()
+        self._low_save()
+
+    async def _check_low(
+        self, ptc: Dict[str, Any], ch: int, sid: int,
+        spool: Optional[Dict[str, Any]], remaining: float,
+        needs: Dict[int, float]
+    ) -> Optional[Dict[str, Any]]:
+        """The spool if it just went below the running-low threshold (sent
+        together with the others from the same check, see _low_alert)."""
+        if remaining <= 0:
+            return None         # amount unknown
+        sent = self._low_load()
+        thr = self._low_threshold(self._full_weight(spool))
+        key = str(sid)
+        if key in sent and (not thr or remaining > thr):
+            # Refilled, re-weighed or replaced: may alert again later
+            del sent[key]
+            self._low_save()
+            return None
+        if not thr or remaining > thr or key in sent:
+            return None
+        self._low_mark(sid)
+        if "filament_low" not in self.rows:
+            return None
+        # With refill on, the spools the printer would refill it from
+        return await self._issue(ptc, ch, sid, spool, remaining,
+                                 needs.get(ch) or 0., needs)
+
+    def _low_text(self, it: Dict[str, Any], cap: Optional[int]) -> str:
+        left = (f"{it['rem']:.0f} of {it['full']:.0f} g left" if it["full"]
+                else f"{it['rem']:.0f} g left")
+        lines = [f"{self._desc(it['ch'], it['name'], it['sid'], cap)}: "
+                 f"{left}.",
+                 f"This print needs ~{it['need']:.0f} g more."
+                 if it["need"] else ""]
+        if it["refill_on"] and it["backups"]:
+            for b in it["backups"]:
+                lines.append(
+                    f"Refill is on: "
+                    f"{self._desc(b['ch'], b['name'], b['sid'], cap)}"
+                    + (f", {b['rem']:.0f} g left" if b["rem"] > 0
+                       else ", amount left unknown")
+                    + f", is {self._match_text(b)}.")
+        elif it["refill_on"]:
+            lines.append("Refill is on. " + (
+                "No exact match spool for refill found on printer."
+                if it["exact"] else
+                "No compatible spool for refill found on printer."))
+        lines.extend(self._blocker_lines(it))
+        return self._lines(*lines)
+
+    @staticmethod
+    def _match_text(b: Dict[str, Any]) -> str:
+        return ("an exact match" if b.get("exact") else
+                "an inexact match (same filament, different colour)")
+
+    def _blocker_lines(self, it: Dict[str, Any]) -> List[str]:
+        return [f"Won't refill from {self._toolhead(c)}: {why}."
+                for c, why in it.get("blockers") or []]
+
+    def _low_row(self, it: Dict[str, Any]) -> Dict[str, Any]:
+        """Like the not-enough picture (with the refill spool, or a note
+        that there is none), worded as running low."""
+        row = self._issue_row(dict(it, status="orange"))
+        row.update(word="Running low.",
+                   needs=(f"Needs ~{it['need']:.0f} g more." if it["need"]
+                          else ""))
+        for r in row.get("refills") or []:
+            r["status"] = "ink" if not it["need"] else r["status"]
+        return row
+
+    async def _low_alert(self, items: List[Optional[Dict[str, Any]]]) -> None:
+        """Spools that went below the threshold in the same check: one
+        notification, in toolhead order (split only if the service's
+        length limit requires it)."""
+        lows = sorted((it for it in items if it), key=lambda i: i["ch"])
+        if not lows:
+            return
+        title = self._title("filament_low") if len(lows) == 1 else \
+            self._title("filament_lows", n=len(lows))
+        await self._send_parts("filament_low", None, packer=(
+            title, "", lows, self._low_text, self._low_row))
+
+    # -- not enough filament --
+
+    async def _issue(
+        self, ptc: Dict[str, Any], ch: int, sid: int,
+        spool: Optional[Dict[str, Any]], remaining: float, need: float,
+        needs: Dict[int, float]
+    ) -> Dict[str, Any]:
+        """Everything a not-enough notification says about one toolhead,
+        including the spools the printer could refill it from."""
+        ids = list(ptc.get("filament_spool_id") or [])
+        it: Dict[str, Any] = dict(
+            ch=ch, sid=sid, name=self._spool_name(spool), rem=remaining,
+            full=self._full_weight(spool), colour=self._spool_colour(spool, ch),
+            need=need, status=self._status_of(remaining, need),
+            refill_on=bool(ptc.get("auto_replenish_filament")),
+            exact=not ptc.get("replenish_ignore_color"), backups=[])
+        unknown_backup = False
+        total = max(0., remaining)
+
+        own_colour = self._colour_multi(self._job_ptc or ptc, ch)
+        it["blockers"] = self._refill_blockers(ptc, ch, self._job_ptc or None) \
+            if it["refill_on"] else []
+        for c in self._backups(ptc, ch, self._job_ptc or None):
+            b_sid = ids[c] if c < len(ids) else 0
+            b = await self._spool(b_sid)
+            b_rem = self._remaining(b)
+            if b_rem is None:
+                continue
+            own = needs.get(c, 0.)
+            if b_rem <= 0:
+                # Loaded, but Spoolman thinks it's empty: amount unknown
+                unknown_backup = True
+            elif b_rem - own <= 0:
+                # The print needs all of it itself: nothing to spare
+                continue
+            else:
+                total += b_rem - own
+            it["backups"].append(dict(
+                ch=c, sid=b_sid, name=self._spool_name(b), rem=b_rem,
+                full=self._full_weight(b), colour=self._spool_colour(b, c),
+                own=own, exact=self._colour_multi(ptc, c) == own_colour))
+        # multiACE: the slots Quad Replenish would reload from, before the
+        # other toolheads (quad_first, the default) or after them. Their
+        # amounts are not known here.
+        ace_backups = self._ace_backups(ch)
+        if ace_backups:
+            unknown_backup = True
+            it["backups"] = (ace_backups + it["backups"]
+                             if self._ace().get("quad_first", True)
+                             else it["backups"] + ace_backups)
+        it["total"] = total
+        it["together"] = self._status_of(total, need)
+        it["unknown_backup"] = unknown_backup
+        if unknown_backup and it["together"] != "green":
+            it["together"] = "orange"
+        if remaining <= 0:
+            it["status"] = "unknown"
+        return it
+
+    def _issue_text(self, it: Dict[str, Any], cap: Optional[int]) -> str:
+        desc = self._desc(it['ch'], it['name'], it['sid'], cap)
+        if it["status"] == "unknown":
+            lines = [f"{desc}: amount of filament left is unknown (Spoolman "
+                     f"shows {it['rem']:.0f} g). Needs ~{it['need']:.0f} g."]
+        else:
+            what = ("not enough filament." if it["status"] == "red"
+                    else "remaining filament may be insufficient.")
+            lines = [f"{desc}: {what} Needs ~{it['need']:.0f} g, "
+                     f"{it['rem']:.0f} g left."]
+        if it["backups"]:
+            for b in it["backups"]:
+                if b.get("ace"):
+                    lines.append(f"Quad Replenish is on: "
+                                 f"{self._bdesc(b, cap)}, is an exact match.")
+                    continue
+                lines.append(
+                    f"Refill is on: {self._bdesc(b, cap)}"
+                    + (f", {b['rem']:.0f} g left" if b["rem"] > 0
+                       else ", amount left unknown")
+                    + f", is {self._match_text(b)}." + (
+                        f" This print also needs ~{b['own']:.0f} g from it."
+                        if b["own"] and b["rem"] > 0 else ""))
+            unknown = it["unknown_backup"] or it["status"] == "unknown"
+            if unknown and it["together"] == "green":
+                lines.append(f"Together at least {it['total']:.0f} g: "
+                             "enough for this print.")
+            elif unknown:
+                lines.append(f"Together {it['total']:.0f} g plus an unknown "
+                             "amount: may be insufficient.")
+            else:
+                lines.append(f"Together {it['total']:.0f} g: " + {
+                    "green": "enough for this print.",
+                    "orange": "may be insufficient.",
+                    "red": "still not enough."}[it["together"]])
+        elif it["refill_on"]:
+            lines.append("Refill is on. " + (
+                "No exact match spool for refill found on printer."
+                if it["exact"] else
+                "No compatible spool for refill found on printer."))
+        if not it["backups"]:
+            lines.extend(self._ace_none_lines(it["ch"]))
+        lines.extend(self._blocker_lines(it))
+        return "\n".join(lines)
+
+    def _issue_row(self, it: Dict[str, Any]) -> Dict[str, Any]:
+        row = dict(toolhead=self._toolhead(it["ch"]),
+                   word={"red": "Not enough.", "orange": "May be insufficient.",
+                         "unknown": "Amount unknown."}[it["status"]],
+                   status=it["status"], needs=f"Needs ~{it['need']:.0f} g.",
+                   remaining=it["rem"], full=it["full"], colour=it["colour"],
+                   name=it["name"], unknown=it["status"] == "unknown")
+        if it["backups"]:
+            # The whole chain, in the order the printer would use it
+            row["refills"] = [dict(
+                toolhead=self._blabel(b), remaining=b["rem"],
+                full=b["full"], colour=b["colour"], name=b["name"],
+                status=it["together"],
+                unknown=b["rem"] is not None and b["rem"] <= 0,
+                match="Exact match" if b.get("exact") else "Inexact match")
+                for b in it["backups"]]
+        elif it["refill_on"]:
+            blockers = it.get("blockers") or []
+            if blockers:
+                c, why = blockers[0]
+                row["note"] = ["Refill is on.", f"Won't refill from "
+                               f"{self._toolhead(c)}:", why]
+            else:
+                row["note"] = ["Refill is on.",
+                               "No exact match spool for" if it["exact"]
+                               else "No compatible spool for",
+                               "refill found on printer."]
+        elif self._ace_head(it["ch"]) is not None:
+            row["note"] = self._ace_none_lines(it["ch"])
+        return row
+
+    def _short_title(self, issues: List[Dict[str, Any]]) -> str:
+        if len(issues) == 1:
+            return self._title({"red": "filament_short",
+                                "orange": "filament_close",
+                                "unknown": "filament_unknown"}[
+                                    issues[0]["status"]])
+        return self._title("filament_problems", n=len(issues))
+
+    async def _short_alert(
+        self, filename: str, issues: List[Dict[str, Any]]
+    ) -> None:
+        """One notification (or as few as the service's length limit
+        allows) for all toolheads at risk, in toolhead order."""
+        issues = sorted(issues, key=lambda i: i["ch"])
+        title = self._short_title(issues)
+        await self._send_parts("filament_short", None, packer=(
+            title, shown(filename), issues, self._issue_text,
+            self._issue_row))
+
+    async def _filament_watch(
+        self, job: int, filename: str, progress: float, check_start: bool
+    ) -> None:
+        ptc = (await self._query({"print_task_config": PTC_FIELDS})
+               ).get("print_task_config") or {}
+        self._status["print_task_config"].update(ptc)
+        self._job_ptc = dict(ptc)
+        ids = list(ptc.get("filament_spool_id") or [])
+        emap = list(ptc.get("extruder_map_table") or [])
+        self._job_map = emap
+        weights = self._needed_grams(filename)
+        self._job_weights = weights
+        self._job_tools = set(weights) or {
+            t for t, c in enumerate(emap[:len(ids)]) if isinstance(c, int)}
+        if not self._spoolman_active():
+            return      # seeded for the runout hold and the backup switch
+        need: Dict[int, float] = {}
+        for tool, grams in weights.items():
+            ch = emap[tool] if tool < len(emap) else tool
+            if isinstance(ch, int) and 0 <= ch < len(ids):
+                # Started partway (power-loss recovery): what's left of the
+                # job can't be measured, so only the spools are watched
+                need[ch] = need.get(ch, 0.) + (
+                    grams if progress <= RECOVERY_MIN_PROGRESS else 0.)
+                if ids[ch]:
+                    self._tool_spools.setdefault(tool, set()).add(ids[ch])
+        if not need:
+            used = list(ptc.get("extruders_used") or [])
+            need = {ch: 0. for ch, u in enumerate(used) if u}
+        # channel -> {sid, reported: 0 nothing, 1 orange, 2 red}
+        track: Dict[int, Dict[str, Any]] = {}
+        issues = []
+        spools: Dict[int, Tuple[Optional[Dict[str, Any]], float]] = {}
+        for ch in sorted(need):
+            sid = ids[ch] if ch < len(ids) else 0
+            if not sid:
+                self._skip(f"filament ({self._toolhead(ch)})",
+                           "no Spoolman spool assigned")
+                continue
+            spool = await self._spool(sid)
+            remaining = self._remaining(spool)
+            if remaining is None:
+                self._skip(f"filament (spool #{sid})",
+                           "Spoolman has no remaining weight for it")
+                continue
+            track[ch] = dict(sid=sid, reported=0)
+            spools[ch] = (spool, remaining)
+            self._seen(sid, remaining)
+            # Spoolman at 0 g (or less) for a loaded spool: amount unknown
+            if remaining <= 0 and not self.filament_unknown:
+                continue
+            if need[ch] > 0 and (remaining <= 0 or self._status_of(
+                    remaining, need[ch]) != "green"):
+                it = await self._issue(ptc, ch, sid, spool, remaining,
+                                       need[ch], need)
+                # Unknown amounts are only reported at print start
+                track[ch]["reported"] = RANK.get(it["status"], 0)
+                issues.append(it)
+        if issues and check_start and "filament_short" in self.rows:
+            # One warning at print start: a spool that is not enough (or
+            # only just) is not also reported as running low
+            for it in issues:
+                self._low_mark(it["sid"])
+            await self._short_alert(filename, issues)
+        await self._low_alert([
+            await self._check_low(ptc, ch, track[ch]["sid"], spool,
+                                  remaining, need)
+            for ch, (spool, remaining) in spools.items()])
+        if not track:
+            return
+        logging.info("[push_notifications] filament: watching %s", ", ".join(
+            f"{self._toolhead(ch)} spool #{t['sid']}"
+            for ch, t in track.items()))
+        while True:
+            await asyncio.sleep(FILAMENT_POLL)
+            if job != self._filament_job or not self._job_active:
+                return
+            if self._status["print_stats"].get("state") != "printing":
+                continue
+            await self._poll_spools(filename, track)
+
+    async def _poll_spools(
+        self, filename: str, track: Dict[int, Dict[str, Any]]
+    ) -> None:
+        ptc = self._status["print_task_config"]
+        ids = list(ptc.get("filament_spool_id") or [])
+        # Toolheads the printer switched to (refill) are watched too
+        for ch in self._switched_to - set(track):
+            if ch < len(ids) and ids[ch]:
+                track[ch] = dict(sid=ids[ch], reported=0)
+        fetched: Dict[int, Tuple[int, Optional[Dict[str, Any]],
+                                 Optional[float]]] = {}
+        for ch, t in track.items():
+            sid = ids[ch] if ch < len(ids) and ids[ch] else t["sid"]
+            spool = await self._spool(sid)
+            remaining = self._remaining(spool)
+            self._seen(sid, remaining)
+            fetched[ch] = (sid, spool, remaining)
+        needs = {ch: self._need_now(ch) or 0. for ch in track}
+        issues = []
+        lows = []
+        for ch, t in track.items():
+            sid, spool, remaining = fetched[ch]
+            if remaining is None:
+                continue
+            if sid != t["sid"]:
+                logging.info("[push_notifications] filament: %s now spool "
+                             "#%d (%.0f g)", self._toolhead(ch), sid,
+                             remaining)
+                t.update(sid=sid, reported=0)
+            need = needs.get(ch) or 0.
+            if remaining <= 0:
+                continue        # amount unknown: nothing to compare
+            status = self._status_of(remaining, need) if need > 0 \
+                else "green"
+            # Only when it got worse than already reported; then it isn't
+            # also reported as running low
+            if RANK[status] > t["reported"] and "filament_short" in self.rows:
+                t["reported"] = RANK[status]
+                issues.append(await self._issue(
+                    ptc, ch, sid, spool, remaining, need, needs))
+                self._low_mark(sid)
+            else:
+                lows.append(await self._check_low(ptc, ch, sid, spool,
+                                                  remaining, needs))
+        if issues:
+            await self._short_alert(filename, issues)
+        await self._low_alert(lows)
+
+    def _refill_expected(self, ex: Dict[str, Any]) -> bool:
+        """A filament runout on a toolhead with a backup spool the printer
+        will refill from by itself. Only when the refill would be reported
+        (the Switched to backup spool row): a held-and-dropped error with
+        nothing in its place would make the refill invisible."""
+        if "spool_switch" not in self.rows:
+            return False
+        try:
+            # 523 is the whole toolhead module (tangles, pickup and park
+            # failures too); code 0 with "runout" is the runout itself
+            runout = int(ex.get("id", -1)) == RUNOUT_EXCEPTION_ID and \
+                int(ex.get("code", -1)) == 0 and \
+                "runout" in str(ex.get("message", "")).lower()
+            ch = int(ex.get("index", -1))
+        except (TypeError, ValueError):
+            return False
+        ptc = self._status["print_task_config"]
+        return runout and ch >= 0 and bool(
+            self._backups(ptc, ch, self._job_ptc or None)
+            or self._ace_candidates(ch))
+
+    async def _runout_hold(self, filename: str, ex: Dict[str, Any]) -> None:
+        refills = self._refills
+        ch = int(ex.get("index", -1))
+        ace = self._ace_head(ch) is not None
+        if ace:
+            self._ace_runouts.add(ch)
+        deadline = time.monotonic() + (ACE_REFILL_WAIT if ace else REFILL_WAIT)
+        try:
+            while time.monotonic() < deadline:
+                await asyncio.sleep(0.5)
+                if self._refills != refills:
+                    self._skip("error", "runout refilled from a backup "
+                               "spool (reported as Switched to backup spool)")
+                    return
+                if self._status["print_stats"].get("state") != "paused":
+                    break   # resumed or ended without a refill being seen
+        finally:
+            self._ace_runouts.discard(ch)
+        await self._send("error", self._title("error", kind="paused"),
+                         f"{shown(filename)}\n{describe(ex)}")
+
+    def _check_spool_switch(self) -> None:
+        """A slicer filament moved to another toolhead mid-print: the
+        printer refilled from a backup spool."""
+        ptc = self._status["print_task_config"]
+        new = list(ptc.get("extruder_map_table") or [])
+        old = self._job_map or []
+        if not new or new == old:
+            return
+        self._job_map = new
+        if not old:
+            return
+        logging.info("[push_notifications] filament: toolhead map changed "
+                     "%s -> %s", old[:4], new[:4])
+        # The printer refills while the print job is paused (it pauses on
+        # the runout, swaps the map, then resumes), and resets the map when
+        # the job ends: only a change during the job counts, and only one
+        # that looks like a refill: every moved slicer filament leaves the
+        # same (empty) toolhead, for a toolhead the printer is allowed to
+        # refill it from. The reset comes ~10 s after the print-end hook,
+        # while print_stats still says "printing", so the hook report
+        # counts as the end too.
+        if (self._job_done_sent or self._status["print_stats"].get("state")
+                not in ("printing", "paused")):
+            return
+        moved = [t for t in range(min(len(old), len(new)))
+                 if old[t] != new[t] and t in self._job_tools]
+        if not moved or len(set(old[t] for t in moved)) != 1:
+            return
+        for tool in moved:
+            if new[tool] not in self._backups(ptc, old[tool],
+                                              self._job_ptc or None):
+                logging.info("[push_notifications] filament: toolhead %d -> "
+                             "%d is not a refill, ignored",
+                             old[tool] + 1, new[tool] + 1)
+                continue
+            self._switched_to.add(new[tool])
+            self._refills += 1
+            ids = list(ptc.get("filament_spool_id") or [])
+            if new[tool] < len(ids) and ids[new[tool]]:
+                self._tool_spools.setdefault(tool, set()).add(ids[new[tool]])
+            if "spool_switch" in self.rows:
+                self._spawn(self._switch_alert(tool, old[tool], new[tool]))
+
+    async def _switch_alert(self, tool: int, frm: int, to: int) -> None:
+        ptc = self._status["print_task_config"]
+        ids = list(ptc.get("filament_spool_id") or [])
+        f_sid = ids[frm] if frm < len(ids) else 0
+        t_sid = ids[to] if to < len(ids) else 0
+        if not f_sid:
+            # The emptied toolhead's spool is unassigned on runout (SpoolLink
+            # clears it before the refill): name the spool it had at start
+            start = list((self._job_ptc or {}).get("filament_spool_id") or [])
+            f_sid = start[frm] if frm < len(start) else 0
+        f_spool, t_spool = await self._spool(f_sid), await self._spool(t_sid)
+        f_rem = self._remaining(f_spool) or 0.
+        t_rem = self._remaining(t_spool)
+        need = self._need_now(to)
+        filename = self._status["print_stats"].get("filename") or ""
+        f_name = self._spool_name(f_spool) or \
+            self._printer_filament(self._job_ptc or ptc, frm)
+        t_name = self._spool_name(t_spool) or self._printer_filament(ptc, to)
+        body = self._lines(
+            shown(filename),
+            f"From {self._desc(frm, f_name, f_sid)}.",
+            f"To {self._desc(to, t_name, t_sid)}"
+            + (f", {t_rem:.0f} g left" if t_rem is not None else "") + ".")
+        row = dict(toolhead=self._toolhead(frm), word="Switched to refill.",
+                   status="red", needs="", remaining=f_rem,
+                   full=self._full_weight(f_spool),
+                   colour=self._spool_colour(f_spool, frm), name=f_name,
+                   refills=[dict(
+                       toolhead=self._toolhead(to), remaining=t_rem or 0.,
+                       full=self._full_weight(t_spool),
+                       colour=self._spool_colour(t_spool, to), name=t_name,
+                       status=(self._status_of(t_rem, need)
+                               if need and t_rem is not None else "ink"))])
+        await self._send_parts("spool_switch", [(
+            self._title("spool_switch"), body, [row])])
+
+    # -- multiACE --
+    #
+    # klipper/extras/ace.py exposes an `ace` object: head_source (the ACE
+    # and slot feeding each head), aces[].slots[] (status, material,
+    # brand, colour), mode, head_ace, quad_replenish, quad_first. Quad
+    # Replenish (ace.py _quad_replenish_candidate) reloads a head that ran
+    # out from the first slot whose gate has filament and whose declared
+    # material equals the head's (colour too, when both declare one):
+    # head mode, the other slots of the head's own ACE in slot order;
+    # otherwise the same slot of the other ACEs. Nothing in the status
+    # says "refilled": head_source changing while the runout is held is
+    # the signal. Indices are 0-based, shown 1-based as multiACE does.
+
+    def _ace(self) -> Dict[str, Any]:
+        return self._status.get(ACE_OBJECT) or {}
+
+    def _ace_sources(self) -> Dict[str, Tuple[int, int]]:
+        """head_source as {head: (ace, slot)} for the heads an ACE feeds."""
+        out: Dict[str, Tuple[int, int]] = {}
+        for h, src in (self._ace().get("head_source") or {}).items():
+            if isinstance(src, dict) and src.get("ace_index") is not None \
+                    and src.get("slot") is not None:
+                out[str(h)] = (int(src["ace_index"]), int(src["slot"]))
+        return out
+
+    def _ace_head(self, ch: int) -> Optional[Tuple[int, int]]:
+        return self._ace_sources().get(str(ch))
+
+    def _ace_slot(self, a: int, s: int) -> Dict[str, Any]:
+        for i, unit in enumerate(self._ace().get("aces") or []):
+            if int(unit.get("idx", i)) == a:
+                slots = list(unit.get("slots") or [])
+                return slots[s] if 0 <= s < len(slots) else {}
+        return {}
+
+    def _ace_ident(self, a: int, s: int) -> Optional[Tuple[str, str]]:
+        """A slot's declared identity, (material, colour): material in
+        lower case, colour as 6 hex digits or "" when not declared; None
+        when the slot declares no material."""
+        slot = self._ace_slot(a, s)
+        mat = str(slot.get("material") or "").strip().lower()
+        if not mat:
+            return None
+        col = slot.get("color")
+        if isinstance(col, (list, tuple)) and len(col) == 3:
+            try:
+                hexcol = "%02X%02X%02X" % tuple(int(c) for c in col)
+            except (TypeError, ValueError):
+                hexcol = ""
+        else:
+            hexcol = str(col or "").strip().lstrip("#").upper()[:6]
+        return mat, hexcol
+
+    def _ace_candidates(self, ch: int) -> List[Tuple[int, int]]:
+        """The slots Quad Replenish would reload head `ch` from, in the
+        order it tries them (ace.py _quad_replenish_candidate)."""
+        ace = self._ace()
+        if not ace.get("quad_replenish"):
+            return []
+        src = (ace.get("head_source") or {}).get(str(ch))
+        if not isinstance(src, dict) or src.get("ace_index") is None \
+                or src.get("slot") is None:
+            return []
+        sa, ss = int(src["ace_index"]), int(src["slot"])
+        want_t = str(src.get("type") or "").strip().lower()
+        want_c = str(src.get("color") or "").strip().lstrip("#").upper()[:6]
+        if not want_t:
+            ident = self._ace_ident(sa, ss)
+            if ident is None:
+                return []
+            want_t, want_c = ident
+        if ace.get("mode") == "head":
+            try:
+                wired = int((ace.get("head_ace") or {}).get(str(ch), ch))
+            except (TypeError, ValueError):
+                wired = ch
+            lanes = [(wired, s) for s in range(4)
+                     if not (wired == sa and s == ss)]
+        else:
+            idxs = sorted(int(u.get("idx", i)) for i, u in
+                          enumerate(ace.get("aces") or []))
+            lanes = [(a, ch) for a in idxs if a != sa]
+        out = []
+        for a, s in lanes:
+            if self._ace_slot(a, s).get("status") != "ready":
+                continue    # gate empty, or busy
+            ident = self._ace_ident(a, s)
+            if ident is None:
+                continue
+            mat, col = ident
+            if mat != want_t or (want_c and col and col != want_c):
+                continue
+            out.append((a, s))
+        return out
+
+    @staticmethod
+    def _ace_label(a: int, s: int) -> str:
+        return f"ACE {a + 1} slot {s + 1}"
+
+    def _ace_name(self, a: int, s: int, ch: int) -> str:
+        """Brand and material of a slot ("Generic PLA"), falling back to
+        what head `ch` captured when it loaded from it."""
+        slot = self._ace_slot(a, s)
+        parts = [str(slot.get(k) or "").strip() for k in ("brand", "material")]
+        name = " ".join(x for x in parts if x)
+        if name:
+            return name
+        src = (self._ace().get("head_source") or {}).get(str(ch)) or {}
+        parts = [str(src.get(k) or "").strip() for k in ("brand", "type")]
+        return " ".join(x for x in parts if x)
+
+    def _ace_colour(self, a: int, s: int, ch: int) -> Any:
+        if images is None:
+            return None
+        ident = self._ace_ident(a, s)
+        if ident and ident[1]:
+            return images.parse_hex(ident[1])
+        src = (self._ace().get("head_source") or {}).get(str(ch)) or {}
+        return images.parse_hex(src.get("color"))
+
+    def _ace_backups(self, ch: int) -> List[Dict[str, Any]]:
+        """Quad Replenish's slots for head `ch` as backup entries (like
+        _issue's toolhead backups; amounts unknown)."""
+        return [dict(ch=ch, ace=(a, s), sid=0, name=self._ace_name(a, s, ch),
+                     rem=None, full=None, colour=self._ace_colour(a, s, ch),
+                     own=0., exact=True)
+                for a, s in self._ace_candidates(ch)]
+
+    def _ace_none_lines(self, ch: int) -> List[str]:
+        """Why Quad Replenish has nothing for head `ch` (an ACE-fed head
+        only)."""
+        src = self._ace_head(ch)
+        if src is None:
+            return []
+        if not self._ace().get("quad_replenish"):
+            return ["Quad Replenish is off."]
+        where = f"ACE {src[0] + 1}" if self._ace().get("mode") == "head" \
+            else "the other ACEs"
+        return ["Quad Replenish is on.",
+                f"No matching slot on {where}."]
+
+    def _blabel(self, b: Dict[str, Any]) -> str:
+        return self._ace_label(*b["ace"]) if b.get("ace") \
+            else self._toolhead(b["ch"])
+
+    def _bdesc(self, b: Dict[str, Any], cap: Optional[int] = None) -> str:
+        if b.get("ace"):
+            name = self._cap(b["name"], cap)
+            return f"{self._ace_label(*b['ace'])} ({name})" if name \
+                else self._ace_label(*b["ace"])
+        return self._desc(b["ch"], b["name"], b["sid"], cap)
+
+    def _job_channels(self) -> Set[int]:
+        emap = self._job_map or []
+        chs = {emap[t] for t in self._job_tools
+               if t < len(emap) and isinstance(emap[t], int)}
+        return chs or set(range(len(EXTRUDERS)))
+
+    def _track_ace(self) -> None:
+        """head_source changing for a head whose runout is being held: a
+        Quad Replenish reload (the print job resumes by itself). A slot
+        feeding a toolhead of the job going empty: the toolhead is on the
+        last of that spool (the filament path between the ACE and the
+        nozzle), reported once per slot."""
+        new = self._ace_sources()
+        old, self._ace_src = self._ace_src, new
+        state = self._status["print_stats"].get("state")
+        if not self._job_active or state not in ("printing", "paused"):
+            return
+        for h in list(self._ace_runouts):
+            o, n = old.get(str(h)), new.get(str(h))
+            if n is not None and n != o:
+                self._ace_runouts.discard(h)
+                self._refills += 1
+                logging.info("[push_notifications] filament: Toolhead %d "
+                             "reloaded from %s", h + 1, self._ace_label(*n))
+                if "spool_switch" in self.rows:
+                    self._spawn(self._ace_switch_alert(h, o, n))
+        if "slot_empty" not in self.rows or state != "printing":
+            return
+        for h, (a, s) in new.items():
+            ch = int(h)
+            if ch not in self._job_channels() or (a, s) in self._slot_empty_sent:
+                continue
+            if self._ace_slot(a, s).get("status") == "empty":
+                self._slot_empty_sent.add((a, s))
+                self._spawn(self._slot_empty_alert(ch, a, s))
+
+    def _ace_next_lines(self, ch: int, runs_out: str) -> List[str]:
+        nxt = self._ace_candidates(ch)
+        if nxt:
+            return [f"Next: {self._bdesc(b)}, an exact match."
+                    for b in self._ace_backups(ch)]
+        none = self._ace_none_lines(ch)
+        if none:
+            none[-1] = none[-1].rstrip(".") + f": {runs_out}"
+        return none
+
+    def _ace_row(self, ch: int, a: int, s: int, word: str,
+                 remaining: Optional[float], status: str,
+                 refills: List[Dict[str, Any]]) -> Dict[str, Any]:
+        row = dict(toolhead=self._ace_label(a, s), word=word, status=status,
+                   needs="", remaining=remaining, full=None,
+                   colour=self._ace_colour(a, s, ch),
+                   name=self._ace_name(a, s, ch))
+        if refills:
+            row["refills"] = [dict(
+                toolhead=self._blabel(b), remaining=None, full=None,
+                colour=b["colour"], name=b["name"], status="ink",
+                match="Exact match") for b in refills]
+        elif self._ace_none_lines(ch):
+            row["note"] = self._ace_none_lines(ch)
+        return row
+
+    async def _slot_empty_alert(self, ch: int, a: int, s: int) -> None:
+        filename = self._status["print_stats"].get("filename") or ""
+        th = self._toolhead(ch)
+        body = self._lines(
+            shown(filename),
+            f"{self._ace_label(a, s)} ({self._ace_name(a, s, ch)}), feeding "
+            f"{th}, has run out. {th} is printing what is left in the "
+            "filament path.",
+            *self._ace_next_lines(
+                ch, f"the print job will pause when {th} runs out."))
+        row = self._ace_row(ch, a, s, "Ran empty.", 0., "red",
+                            self._ace_backups(ch))
+        await self._send_parts("slot_empty", [(
+            self._title("slot_empty"), body, [row])])
+
+    async def _ace_switch_alert(self, ch: int, old: Optional[Tuple[int, int]],
+                                new: Tuple[int, int]) -> None:
+        filename = self._status["print_stats"].get("filename") or ""
+        frm = (f"{self._ace_label(*old)} ({self._ace_name(*old, ch)})"
+               if old else "an empty slot")
+        body = self._lines(
+            shown(filename),
+            f"From {frm} on {self._toolhead(ch)}.",
+            f"To {self._ace_label(*new)} ({self._ace_name(*new, ch)}).",
+            *self._ace_next_lines(
+                ch, f"the print job will pause when it runs out."))
+        row = self._ace_row(ch, *(old or new), "Switched to refill.", 0.,
+                            "red", [dict(ace=new, ch=ch,
+                                         name=self._ace_name(*new, ch),
+                                         colour=self._ace_colour(*new, ch))]
+                            + self._ace_backups(ch))
+        await self._send_parts("spool_switch", [(
+            self._title("spool_switch"), body, [row])])
+
+    # -- sending, split to fit the service --
+
+    @staticmethod
+    def _fits(channel: str, text: str) -> bool:
+        limit = BODY_LIMITS.get(channel)
+        if limit is None:
+            return True
+        chars, n = limit
+        return (len(text) if chars else len(text.encode())) <= n
+
+    def _pack(
+        self, channel: str, header: str, issues: List[Dict[str, Any]],
+        text_fn: Any
+    ) -> List[Tuple[List[int], str]]:
+        """Split the issues into as few messages as fit the channel. One
+        toolhead's text is never split: if it doesn't fit on its own, the
+        file name and then the spool names are shortened (all names to the
+        same length, just enough)."""
+        def body(head: str, blocks: List[str]) -> str:
+            return "\n\n".join([head + "\n" + blocks[0]] + blocks[1:]) \
+                if head else "\n\n".join(blocks)
+
+        def fitted(i: int) -> Tuple[str, str]:
+            for head in (header, self._cap(header, FILE_CAP)):
+                block = text_fn(issues[i], None)
+                if self._fits(channel, body(head, [block])):
+                    return head, block
+            head = self._cap(header, FILE_CAP)
+            longest = max([len(issues[i]["name"])] +
+                          [len(b["name"]) for b in issues[i]["backups"]])
+            lo, hi = NAME_CAP_MIN, max(NAME_CAP_MIN, longest)
+            while lo < hi:      # longest cap that fits
+                mid = (lo + hi + 1) // 2
+                if self._fits(channel, body(head, [text_fn(issues[i], mid)])):
+                    lo = mid
+                else:
+                    hi = mid - 1
+            return head, text_fn(issues[i], lo)
+
+        out: List[Tuple[List[int], str]] = []
+        idx: List[int] = []
+        blocks: List[str] = []
+        head_cur = header
+        for i in range(len(issues)):
+            head, block = fitted(i)
+            if idx:
+                for h in (head_cur, self._cap(header, FILE_CAP)):
+                    if self._fits(channel, body(h, blocks + [block])):
+                        head_cur = h
+                        idx.append(i)
+                        blocks.append(block)
+                        break
+                else:
+                    out.append((idx, body(head_cur, blocks)))
+                    idx, blocks, head_cur = [i], [block], head
+            else:
+                idx, blocks, head_cur = [i], [block], head
+        if idx:
+            out.append((idx, body(head_cur, blocks)))
+        return out
+
+    def _render_rows(self, rows: List[Dict[str, Any]]) -> Optional[str]:
+        if images is None:
+            return None
+        tmpdir = tempfile.mkdtemp(prefix="push_notifications_")
+        try:
+            return images.render(rows, os.path.join(tmpdir, "spools.jpg"))
+        except Exception as e:
+            shutil.rmtree(tmpdir, ignore_errors=True)
+            logging.warning("[push_notifications] spool image failed: %s", e)
+            return None
+
+    async def _send_parts(
+        self, rid: str,
+        messages: Optional[List[Tuple[str, str, List[Dict[str, Any]]]]],
+        packer: Optional[Tuple[Any, ...]] = None
+    ) -> bool:
+        """Send one or more messages, each with its own spool picture, to
+        each of the row's destinations, in their channels' turn. Either
+        fixed `messages` (title, body, image rows), or `packer` = (title,
+        header, issues, text_fn, row_fn), split per channel to fit."""
+        row = self.rows.get(rid)
+        if row is None:
+            return False
+        kind, dests = row
+        tickets = [self._reserve(d.channel, rid) for d in dests]
+        paths: Dict[Tuple[int, ...], Optional[str]] = {}
+        try:
+            per_dest: List[List[Tuple[str, str, Optional[str]]]] = []
+            for d in dests:
+                if packer is None:
+                    msgs = [(t, b, rows) for t, b, rows in messages or []]
+                    keyed = [((k,), m) for k, m in enumerate(msgs)]
+                else:
+                    title, header, issues, text_fn, row_fn = packer
+                    parts = self._pack(d.channel, header, issues, text_fn)
+                    keyed = []
+                    for n, (idx, body) in enumerate(parts, 1):
+                        t = title if len(parts) == 1 \
+                            else f"{title} ({n}/{len(parts)})"
+                        keyed.append((tuple(idx), (
+                            t, body, [row_fn(issues[i]) for i in idx])))
+                out = []
+                for key, (t, b, rows) in keyed:
+                    path = None
+                    if kind == "spool":
+                        if key not in paths:
+                            drawn = await self.eventloop.run_in_thread(
+                                self._render_rows, rows)
+                            paths[key] = self._named_copy(drawn, t)
+                            if drawn and paths[key] != drawn:
+                                shutil.rmtree(os.path.dirname(drawn),
+                                              ignore_errors=True)
+                        path = paths[key]
+                    out.append((t, b, path))
+                per_dest.append(out)
+            report: List[Dict[str, Any]] = []
+            results = self._outcomes(rid, dests, await asyncio.gather(*(
+                self._deliver(rid, d, t, msgs, report)
+                for d, t, msgs in zip(dests, tickets, per_dest)),
+                return_exceptions=True))
+            self._console_report(report)
+        finally:
+            for t in tickets:
+                await t.gate.done(t.ticket)
+            for p in paths.values():
+                if p:
+                    shutil.rmtree(os.path.dirname(p), ignore_errors=True)
+        return all(results)
+
+
+def load_component(config: ConfigHelper) -> PushNotifications:
+    return PushNotifications(config)