[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8},"actionData","errors","root",{"_102":103,"_104":105},"routes/embed.x.$handle.$name.$",{"_9":10,"_11":12,"_13":14,"_15":16,"_17":18,"_19":20,"_21":-5},"handle","buddyd","name","trmnldevicemonitor","path","main.ts","project",{"_22":45,"_11":12,"_33":46,"_47":-5,"_48":42,"_49":50,"_51":50,"_52":53,"_54":-5,"_55":56,"_57":-5,"_58":42,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":42},"file",{"_22":23,"_11":14,"_24":25,"_26":-5,"_27":28,"_29":30,"_31":32,"_33":34,"_35":36,"_37":38,"_39":40,"_41":42,"_43":-5,"_13":44},"permalink","https://www.val.town/x/buddyd/trmnldevicemonitor/code/main.ts","extension","id","53218ca7-920d-41f6-8bf1-3ebdbd5f7dc2","fileId","f0dcdcd0-a2df-11f1-8a32-1607ee4eb77e","parentId","branchId","89a1c79c-a287-4436-ba23-147afbd718e8","branchVersion",11,"latest",true,"createdAt",["D",1789154121161],"version",10,"fileType","interval","content","/**\n * TRMNL Device Liveness Monitor — Val Town CRON val\n * ---------------------------------------------------------------------------\n * Emails only when something is worth acting on — plus one all-clear a week\n * so that its silence can be trusted.\n *\n * ⚠️ THE SCHEDULE IS NOT IN THIS FILE. It is set on the val in Val Town's UI\n * (currently every 15 minutes). Nothing here reads it, so if you change it,\n * the \"~15 min\" figures in the guide go stale silently. At 15 min this is\n * 96 runs/day against Val Town's 100,000/day free allowance — an allowance\n * quoted from Val Town's pricing page and not re-verified since 2026-08-28.\n *\n * SETUP\n * Cron val, every 15 minutes. Environment variables on the val:\n * TRMNL_API_KEY = \n * TRMNL_DEVICES = :,:\n * TRMNL_TZ = America/Denver (must match the TRMNL account timezone)\n * TRMNL_API_KEY is never printed, never emailed, and is not in this source.\n * Free-plan vals are PUBLIC, which is why device ids and labels live in\n * TRMNL_DEVICES instead of in the code.\n *\n * WHY THERE IS NO HTTP ENDPOINT\n * Val Town HTTP endpoints are reachable by anyone who knows the URL in EVERY\n * privacy mode — private only hides the code. A route returning device status\n * would publish a presence signal, and protecting it would need a shared token\n * the caller must store. Cron needs no inbound request.\n *\n * ===========================================================================\n * ALERT POLICY (rewritten 2026-09-09 — read this before changing thresholds)\n * ===========================================================================\n * The first version alerted on anything out of range, including Wi-Fi signal\n * strength. That produced repeated emails about a device that was working, and\n * it had a worse failure hiding inside it — see THE MASKING BUG below.\n *\n * Three tiers now:\n *\n * TIER 1 — ALERTS. Emails you. Every one is actionable. TWO must be\n * SUSTAINED past ALERT_AFTER_HOURS first, because they self-heal:\n * - down: a device silent that long\n * - blind this monitor unable to reach the TRMNL API that long\n * The rest fire on the FIRST run that sees them, because none of them\n * self-heals and waiting only delays the fix:\n * - battery: battery at or below BATTERY_ALERT_PCT (go plug it in)\n * - missing: the device is gone from the TRMNL account\n * - never: the device has never checked in (usually never paired)\n * - api:auth TRMNL rejected the key (401/403) — probably rotated\n * - config:key, config:devices this val is not configured, so it is\n * checking nothing at all while looking exactly like coverage\n *\n * TIER 2 — CONTEXT. Never emails on its own. Wi-Fi RSSI, battery above the\n * alert floor, firmware, band. These ride along inside a Tier 1 email so the\n * alert arrives with diagnostics attached, which is where they are useful.\n *\n * TIER 3 — HEARTBEAT. One short all-clear every HEARTBEAT_DAYS, and only when\n * nothing is wrong. See WHY A HEARTBEAT below.\n *\n * WHY A HEARTBEAT\n * A quiet monitor and a DEAD monitor look identical from the inbox. That is\n * the same failure this monitor was built to catch — a thing that has stopped\n * working while continuing to look normal — pointed at the monitor itself. So\n * a weekly all-clear goes out. Its arrival means nothing; its ABSENCE is the\n * signal. It also carries the Tier 2 readings, so a battery trending down or\n * Wi-Fi degrading month over month is visible long before either alerts.\n * Any email at all is proof of life, so the heartbeat clock resets on every\n * send — an active problem re-nagging daily suppresses it, correctly.\n *\n * WHY A BLIND MONITOR ESCALATES\n * A single failed API call is transient and is ignored. But if the TRMNL API\n * keeps failing, the monitor is not \"fine\", it is BLIND — it cannot tell a\n * healthy fleet from a dark one, and it stays silent either way. blindSince\n * tracks how long that has lasted; past ALERT_AFTER_HOURS it becomes a real\n * alert, held to the same 3-hour bar as a dark device.\n *\n * WHY RSSI NO LONGER ALERTS\n * RSSI is a continuously fluctuating radio measurement, not a state. Published\n * guidance puts -70 dBm at \"reliable packet delivery\" and -80 dBm at \"basic\n * connectivity\", and these devices fetch a few KB every five minutes — the\n * least demanding traffic there is. A device sitting near the threshold\n * crosses it constantly, and each crossing was firing an email. Worse, every\n * one of those alerts was about a device that was checking in perfectly well,\n * so there was nothing to do about it. The old -75 dBm threshold was not\n * derived from anything; it was asserted.\n * The signal that actually matters is the SYMPTOM — the screen stopped\n * updating — and that is Tier 1. Weak Wi-Fi is a possible CAUSE, so it now\n * appears in the alert body where it helps diagnose, rather than paging on\n * its own.\n *\n * THE MASKING BUG (the real reason this rewrite was necessary)\n * The old code reduced everything to one flag: `status = problems.length ?\n * \"bad\" : \"ok\"`, and emailed only when that flag flipped. So while RSSI held\n * the monitor at \"bad\", a device going genuinely dark did NOT flip anything —\n * and sent NO email until the 24-hour re-nag. The noisy signal was suppressing\n * the important one. Alerts are now tracked as a SET of active condition keys\n * and an email fires whenever that set changes, so a new problem always\n * announces itself even if another was already open.\n *\n * SLEEP HANDLING\n * VERIFIED against a live HTTP 200: the device array sits under a \"data\" key,\n * and devices report sleep_start_time / sleep_end_time as integers.\n * ASSUMED, because TRMNL documents neither: that those are minutes past\n * midnight, and that they are in the ACCOUNT's timezone (the device object\n * carries no timezone field at all).\n * Because both are assumptions, sleep can only ever SUPPRESS an alert for a\n * bounded period — past the window plus SLEEP_GRACE_HOURS a quiet device\n * alerts regardless. If the assumptions are wrong the failure mode is a late\n * alert, never a silent one.\n * WAKE_GRACE_MIN exists because a healthy device is still several hours stale\n * in the first minutes after its window ends — it has not had a chance to ping\n * yet. Without that grace the monitor would fire a false alarm every morning.\n */\n\nimport { email } from \"https://esm.town/v/std/email\";\nimport { blob } from \"https://esm.town/v/std/blob/main.ts\";\n\n// ---------------------------------------------------------------- config ----\n\n/** Timezone the sleep window is read in. Must match trmnl.com/account. */\nconst TZ = Deno.env.get(\"TRMNL_TZ\") ?? \"America/Denver\";\n\n/** How long a device must be silent before it is worth an email.\n * Set to 3h on 2026-09-09: a stale quote screen is not urgent, and shorter\n * windows turn ordinary Wi-Fi hiccups into mail. Checks still run every 15\n * minutes, so the alert lands within ~15 min of the 3 hours elapsing. */\nconst ALERT_AFTER_HOURS = 3;\n\n/** Battery low enough to be worth walking over and docking it. */\nconst BATTERY_ALERT_PCT = 10;\n\n/** Beyond the sleep window plus this, a silent device alerts even if we think\n * it is asleep. The backstop over the two unverified sleep assumptions. */\nconst SLEEP_GRACE_HOURS = 2;\n\n/** Quiet period after a sleep window ends, before staleness counts again.\n * A device that just woke has not pinged yet and is legitimately stale. */\nconst WAKE_GRACE_MIN = 20;\n\n/** Re-send while an alert is still unresolved. */\nconst RENAG_HOURS = 24;\n\n/** Heartbeat. \"Silence means healthy\" has one hole: a monitor that has DIED is\n * also silent, and that is indistinguishable from everything being fine — the\n * exact failure this monitor exists to prevent, turned on itself. So once a\n * week it sends a short all-normal digest. Its ARRIVAL is unremarkable; its\n * ABSENCE is the signal. The digest also carries the readings that no longer\n * alert (RSSI, battery), so slow degradation over weeks is still visible. */\nconst HEARTBEAT_DAYS = 7;\n\n/** How often to test the quote counter. Each test spends TWO counter positions\n * (three if the first two collide), so this is deliberately 2-hourly:\n * 24 positions/day against ~576 device polls/day, about 4%. No quote leaves the\n * pool — the endpoint reshuffles every cycle — and the 5-minute display\n * rotation is untouched. Only WHICH quote each screen lands on shifts. */\nconst QUOTE_CHECK_MIN = 120;\n\n/** DELIBERATELY ABSENT: a \"free\" read of the endpoint's counter blob.\n * An earlier version tried blob.getJSON(\"trmnl_quote_counter\") first and fell\n * back to HTTP, on the reasoning that trying costs nothing. That reasoning was\n * wrong, and the bug it hid is worth spelling out so nobody re-adds it.\n * This check works by sampling BACK-TO-BACK and expecting the value to MOVE.\n * Only an HTTP request moves it — the endpoint increments the counter as a side\n * effect of serving. Reading the blob does not. So if that read ever succeeded\n * (Val Town changes blob scoping, or that key appears in this val), three reads\n * in a row would return the same number for the most ordinary reason there is,\n * and this monitor would email \"the counter is NOT advancing\" every two hours\n * while the endpoint was perfectly healthy. A sample that costs nothing proves\n * nothing. Found by audit 2026-09-11 before it ever fired; do not restore it. */\n\nconst STATE_KEY = \"trmnl_liveness_state_v2\";\n\n/** \":,:\" — kept out of the source because vals are public. */\nfunction parseDevices(raw: string): Record {\n const out: Record = {};\n for (const pair of raw.split(\",\").map((x) => x.trim()).filter(Boolean)) {\n const i = pair.indexOf(\":\");\n if (i > 0) out[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();\n }\n return out;\n}\n\n// ----------------------------------------------------------------- utils ----\n\n/** Minutes past midnight in TZ. Intl handles DST. */\nfunction minutesOfDayInTz(d: Date, tz: string): number {\n const parts = new Intl.DateTimeFormat(\"en-US\", {\n timeZone: tz,\n hour: \"2-digit\",\n minute: \"2-digit\",\n hour12: false,\n }).formatToParts(d);\n const h = Number(parts.find((p) => p.type === \"hour\")?.value ?? \"0\") % 24;\n const m = Number(parts.find((p) => p.type === \"minute\")?.value ?? \"0\");\n return h * 60 + m;\n}\n\n/** Windows wrap midnight when start > end (e.g. 1320..240). */\nfunction inWindow(start: number, end: number, now: number): boolean {\n return start <= end\n ? (now >= start && now < end)\n : (now >= start || now < end);\n}\n\nfunction windowLengthMin(start: number, end: number): number {\n return start <= end ? end - start : 1440 - start + end;\n}\n\nfunction fmtAge(min: number): string {\n if (!Number.isFinite(min)) return \"an unknown time\";\n if (min < 60) return `${Math.round(min)}m`;\n const h = Math.floor(min / 60);\n return `${h}h ${Math.round(min - h * 60)}m`;\n}\n\ntype Alert = { key: string; text: string };\n\ntype QuoteObs = { mode: \"http\"; value: string } | {\n mode: \"none\";\n why: string;\n};\n\n/** Observe the quote counter WITHOUT judging it. One way only: fetch the\n * endpoint and use the quote text as a proxy for the counter. That costs one\n * counter position per call, and that cost is the point — see DELIBERATELY\n * ABSENT in the config block for why there is no cheaper path.\n * Returns mode:\"none\" with a reason rather than throwing — a check that cannot\n * run must say so, never look like a pass. */\nasync function observeQuoteCounter(): Promise {\n const url = Deno.env.get(\"TRMNL_QUOTE_URL\");\n if (!url) {\n return {\n mode: \"none\",\n why: \"TRMNL_QUOTE_URL is not set on this val\",\n };\n }\n try {\n const res = await fetch(url, {\n headers: { \"Cache-Control\": \"no-store\" },\n signal: AbortSignal.timeout(20_000),\n });\n if (!res.ok) {\n return {\n mode: \"none\",\n why: `quote endpoint returned HTTP ${res.status}`,\n };\n }\n const cc = res.headers.get(\"cache-control\") ?? \"\";\n const j = await res.json();\n const text = typeof j?.text === \"string\" ? j.text : \"\";\n if (!text) {\n return { mode: \"none\", why: \"quote endpoint response had no text field\" };\n }\n if (!/no-store/i.test(cc)) {\n return {\n mode: \"none\",\n why: \"quote endpoint is missing its no-store header\",\n };\n }\n return { mode: \"http\", value: text };\n } catch (e) {\n return {\n mode: \"none\",\n why: `quote endpoint fetch failed: ${String(e).slice(0, 120)}`,\n };\n }\n}\n\n// ------------------------------------------------------------------ main ----\n\nexport async function trmnlLiveness(_interval: { lastRunAt?: Date }) {\n const now = new Date();\n const alerts: Alert[] = []; // Tier 1 — these email\n const context: string[] = []; // Tier 2 — these never email alone\n const notes: string[] = [];\n\n const EXPECTED = parseDevices(Deno.env.get(\"TRMNL_DEVICES\") ?? \"\");\n if (Object.keys(EXPECTED).length === 0) {\n alerts.push({\n key: \"config:devices\",\n text:\n \"TRMNL_DEVICES is not set on this val, so nothing is being checked. \" +\n 'Set it to \":,:\" in Environment Variables.',\n });\n return await settle(now, alerts, context, notes, \"unconfigured\");\n }\n\n const KEY = Deno.env.get(\"TRMNL_API_KEY\");\n if (!KEY) {\n // A monitor that quietly does nothing is worse than none: it looks like coverage.\n alerts.push({\n key: \"config:key\",\n text:\n \"TRMNL_API_KEY is not set on this val, so no device check ran at all.\",\n });\n return await settle(now, alerts, context, notes, \"unconfigured\");\n }\n\n // ---- fetch -------------------------------------------------------------\n let payload: any;\n try {\n const res = await fetch(\"https://trmnl.com/api/devices\", {\n headers: { Authorization: `Bearer ${KEY}` },\n signal: AbortSignal.timeout(20_000),\n });\n if (res.status === 401 || res.status === 403) {\n alerts.push({\n key: \"api:auth\",\n text:\n `TRMNL rejected the API key (HTTP ${res.status}). If it was regenerated, ` +\n `update TRMNL_API_KEY on this val.`,\n });\n return await settle(now, alerts, context, notes, \"auth\");\n }\n if (!res.ok) {\n // Transient server-side errors are common and self-heal. Do not alert on\n // a single one; the next run in 15 minutes will decide. But a monitor that\n // cannot check is BLIND, and a blind monitor is as bad as a dead device —\n // so settle() escalates once this has persisted past ALERT_AFTER_HOURS.\n notes.push(\n `TRMNL API returned HTTP ${res.status}; deferring to next run.`,\n );\n return await settle(now, [], context, notes, `http_${res.status}`, true);\n }\n payload = await res.json();\n } catch (e) {\n notes.push(`Transient fetch error: ${String(e).slice(0, 200)}`);\n return await settle(now, [], context, notes, \"fetch_error\", true);\n }\n\n const devices: any[] = Array.isArray(payload)\n ? payload\n : Array.isArray(payload?.data)\n ? payload.data\n : [];\n if (!Array.isArray(payload) && !Array.isArray(payload?.data)) {\n notes.push(\n \"Response shape differed from the documented { data: [...] } — \" +\n `top-level keys: ${Object.keys(payload ?? {}).join(\", \") || \"(none)\"}`,\n );\n }\n\n const nowMin = minutesOfDayInTz(now, TZ);\n const ALERT_AFTER_MIN = ALERT_AFTER_HOURS * 60;\n\n for (const [id, label] of Object.entries(EXPECTED)) {\n const d = devices.find((x) => String(x?.id) === id);\n if (!d) {\n alerts.push({\n key: `missing:${id}`,\n text: `${label}: not present in the TRMNL response.`,\n });\n continue;\n }\n\n const pingRaw = d.hardware_last_ping_at ?? null;\n if (!pingRaw) {\n alerts.push({\n key: `never:${id}`,\n text: `${label}: has never checked in.`,\n });\n continue;\n }\n\n const ageMin = (now.getTime() - new Date(pingRaw).getTime()) / 60000;\n\n // --- Tier 1: sustained silence -----------------------------------------\n if (ageMin > ALERT_AFTER_MIN) {\n const hasWindow = d.sleep_mode_enabled === true &&\n Number.isFinite(d.sleep_start_time) &&\n Number.isFinite(d.sleep_end_time);\n\n // Extend the window past its end so a just-woken device is not counted\n // stale before it has had a chance to ping.\n const quiet = hasWindow &&\n inWindow(\n d.sleep_start_time,\n (d.sleep_end_time + WAKE_GRACE_MIN) % 1440,\n nowMin,\n );\n\n const graceMin = hasWindow\n ? windowLengthMin(d.sleep_start_time, d.sleep_end_time) +\n SLEEP_GRACE_HOURS * 60\n : 0;\n\n if (quiet && ageMin <= graceMin) {\n notes.push(\n `${label}: quiet ${\n fmtAge(ageMin)\n }, inside its sleep window — expected, not flagged.`,\n );\n } else {\n alerts.push({\n key: `down:${id}`,\n text: `${label}: no check-in for ${fmtAge(ageMin)}` +\n (quiet\n ? ` — longer than its sleep window plus ${SLEEP_GRACE_HOURS}h, so it is not just asleep`\n : \"\") +\n `. Its screen is frozen on an old quote and looks completely normal.`,\n });\n }\n }\n\n // --- Tier 1: battery low enough to act on ------------------------------\n if (\n typeof d.percent_charged === \"number\" &&\n d.percent_charged <= BATTERY_ALERT_PCT\n ) {\n alerts.push({\n key: `battery:${id}`,\n text: `${label}: battery at ${d.percent_charged}% — dock it to charge.`,\n });\n }\n\n // --- Tier 2: context only. Never emails on its own. --------------------\n const bits: string[] = [`last ping ${fmtAge(ageMin)} ago`];\n if (typeof d.percent_charged === \"number\") {\n bits.push(`battery ${d.percent_charged}%`);\n }\n if (typeof d.rssi === \"number\") bits.push(`Wi-Fi ${d.rssi} dBm`);\n if (d.wifi_band) bits.push(`${d.wifi_band} GHz`);\n if (d.firmware_version) bits.push(`fw ${d.firmware_version}`);\n context.push(`${label}: ${bits.join(\", \")}`);\n }\n\n let quoteWrite: QuoteWrite = null;\n // --- Quote-counter check. Wrapped so it can NEVER break device monitoring:\n // the device alerts above are the load-bearing ones, and a bug here must not\n // cost us those. Any unexpected throw degrades to a note, not a lost run.\n try {\n quoteWrite = await quoteCounterCheck(now, alerts, notes);\n } catch (e) {\n notes.push(\n `Quote-counter check errored (device checks unaffected): ${\n String(e).slice(0, 140)\n }`,\n );\n }\n\n return await settle(\n now,\n alerts,\n context,\n notes,\n \"checked\",\n false,\n quoteWrite,\n );\n}\n\n/** Decide whether the shared quote counter is advancing.\n * It is the guard against the obvious false alarm: overnight both devices are\n * asleep, nobody polls, and the counter legitimately does not move. Judging\n * staleness then would fire an alert every single night. */\ntype QuoteWrite = {\n quoteAt: string;\n quoteMode: string;\n /** Standing quote alert, or null. MUST be carried across runs where the check\n * is not due — see the comment inside quoteCounterCheck. */\n quoteAlert: Alert | null;\n} | null;\n\n/** Is the shared quote counter advancing?\n *\n * THE TEST: two back-to-back requests. The endpoint consumes one counter\n * position per request and each position is a different quote within a cycle,\n * so two requests seconds apart MUST return different text if the per-request\n * counter is alive. If they match it is not — and a third sample rules out the\n * single coincidence (a cycle boundary repeating a quote, roughly 1 in 297).\n *\n * WHY NOT \"compare against the previous check an hour ago\": that cannot see the\n * endpoint's time-based fail-safe. On that path the blob counter is dead and the\n * index is Math.floor(Date.now()/5min), so samples an hour apart ALWAYS differ\n * and the monitor would report \"advancing\" while both screens sat on the same\n * quote with the stagger gone. Back-to-back sampling catches that. It also needs\n * no assumption about devices polling, so it works correctly overnight. */\nasync function quoteCounterCheck(\n now: Date,\n alerts: Alert[],\n notes: string[],\n): Promise {\n const prev = (await blob.getJSON(STATE_KEY).catch(() => null)) as any ?? {};\n const lastAt = prev.quoteAt ? new Date(prev.quoteAt).getTime() : 0;\n const sinceMin = Number.isFinite(lastAt) && lastAt > 0\n ? (now.getTime() - lastAt) / 60000\n : Infinity;\n\n if (sinceMin < QUOTE_CHECK_MIN) {\n // NOT DUE — but a standing alert must be RE-ASSERTED, not dropped.\n // settle() emails on any change to the SET of active alert keys, so a\n // condition that silently disappears on the runs where this check is skipped\n // reads as RECOVERY and sends a false \"back to normal\" while the fault is\n // still live. That bug shipped 2026-09-11 and was caught by audit the same\n // day; this line is the fix. Do not remove it.\n if (prev.quoteAlert) alerts.push(prev.quoteAlert as Alert);\n return null;\n }\n\n const mark = (a: Alert | null): QuoteWrite => ({\n quoteAt: now.toISOString(),\n quoteMode: \"http\",\n quoteAlert: a,\n });\n\n const unusable = (why: string): QuoteWrite => {\n const a: Alert = {\n key: \"quote:unchecked\",\n text: `The quote counter is NOT being checked — ${why}. ` +\n `That matters because a counter that stops advancing freezes BOTH screens ` +\n `while every device keeps checking in normally, so nothing else here would ` +\n `notice. Fix: check TRMNL_QUOTE_URL on this val, and the endpoint itself.`,\n };\n alerts.push(a);\n // Record the attempt even though it produced nothing usable, so the 2-hourly\n // rate limit still applies. Without this, an endpoint that merely lost its\n // no-store header would be re-fetched on EVERY run.\n return mark(a);\n };\n\n const s1 = await observeQuoteCounter();\n if (s1.mode === \"none\") return unusable(s1.why);\n const s2 = await observeQuoteCounter();\n if (s2.mode === \"none\") return unusable(s2.why);\n\n if (s1.value !== s2.value) {\n notes.push(\"Quote counter: advancing (two back-to-back samples differed).\");\n return mark(null);\n }\n\n // Identical. Almost certainly not advancing — confirm, to rule out a cycle boundary.\n const s3 = await observeQuoteCounter();\n if (s3.mode === \"http\" && s3.value !== s1.value) {\n notes.push(\n \"Quote counter: two samples matched but a third differed — treated as a \" +\n \"cycle-boundary coincidence, not a fault.\",\n );\n return mark(null);\n }\n\n const stuck: Alert = {\n key: \"quote:notadvancing\",\n text:\n `Three back-to-back requests to the quote endpoint returned the SAME quote, ` +\n `so its per-request counter is NOT advancing. Two ways that looks on the wall: ` +\n `if the counter is frozen, BOTH screens are stuck on one quote and look completely ` +\n `normal; if the endpoint has fallen back to its time-based index, the screens still ` +\n `change every 5 minutes but BOTH show the SAME quote and the stagger is gone. ` +\n `Either way, look at the quote endpoint val — not at the devices, which are fine.`,\n };\n alerts.push(stuck);\n return mark(stuck);\n}\n\n// --------------------------------------------------- state + notification ----\n\nasync function settle(\n now: Date,\n alertsIn: Alert[],\n context: string[],\n notes: string[],\n kind: string,\n transient = false,\n quoteWrite: QuoteWrite = null,\n) {\n const prev = (await blob.getJSON(STATE_KEY).catch(() => null)) as any ?? {\n sig: \"\",\n since: now.toISOString(),\n lastEmailAt: null,\n kind: \"init\",\n };\n\n let alerts = alertsIn;\n\n // A single transient failure does not email — but it IS tracked. blindSince\n // persists across runs while the API keeps failing and is cleared (set null in\n // the state write at the bottom) by any run that actually reached the devices.\n let blindSince: string | null = null;\n if (transient) {\n const since: string = (prev.blindSince as string | undefined) ??\n now.toISOString();\n blindSince = since;\n const blindMin = (now.getTime() - new Date(since).getTime()) / 60000;\n if (blindMin <= ALERT_AFTER_HOURS * 60) {\n await blob.setJSON(STATE_KEY, {\n ...prev,\n blindSince,\n lastNote: notes.join(\" | \"),\n lastSeenAt: now.toISOString(),\n });\n return { sig: prev.sig ?? \"\", emailed: false, transient: true, notes };\n }\n // Blind longer than a device is allowed to be dark. This REPLACES the alert\n // list rather than adding to it: there are no device readings to report,\n // which is precisely the problem being reported.\n alerts = [{\n key: \"blind\",\n text:\n `The monitor has not been able to reach the TRMNL API for ${\n fmtAge(blindMin)\n }. ` +\n `Your screens are NOT being checked right now — a device could be dark and ` +\n `this monitor would not know. Last error: ${\n notes[notes.length - 1] ?? \"(none)\"\n }`,\n }];\n }\n\n // The SET of active alerts, not a single bad/ok flag. A new problem appearing\n // while another is open changes the signature, so it still emails.\n const sig = alerts.map((a) => a.key).sort().join(\"|\");\n const changed = sig !== (prev.sig ?? \"\");\n const lastEmail = prev.lastEmailAt ? new Date(prev.lastEmailAt).getTime() : 0;\n const dueRenag = sig !== \"\" &&\n now.getTime() - lastEmail > RENAG_HOURS * 3600_000;\n\n const recovered = sig === \"\" && (prev.sig ?? \"\") !== \"\";\n const firstRun = prev.kind === \"init\";\n\n // Proof of life. Any email counts, so a problem re-nagging daily suppresses\n // the heartbeat — correctly: those emails already prove the monitor is running.\n const heartbeatBase: string = prev.lastEmailAt ?? prev.since ??\n now.toISOString();\n const quietDays = (now.getTime() - new Date(heartbeatBase).getTime()) /\n 86_400_000;\n const dueHeartbeat = sig === \"\" && !recovered && !firstRun && !transient &&\n quietDays > HEARTBEAT_DAYS;\n\n let emailed = false;\n // firstRun must be in this condition: on a virgin state sig and prev.sig are\n // both \"\", so `changed` is false and the install-proof email would never send.\n if (changed || dueRenag || dueHeartbeat || firstRun) {\n // NOTE: there is deliberately no \"nothing is wrong, stay quiet\" guard in\n // here. When sig === \"\" the only ways into this block are `recovered`,\n // `firstRun` and `dueHeartbeat` — `dueRenag` requires sig !== \"\", and with\n // sig === \"\" `changed` is definitionally the same thing as `recovered`. A\n // guard for the quiet case was therefore unreachable dead code and was\n // removed 2026-09-09. The quiet case falls out of the outer `if` being\n // false, and the state write at the bottom of settle() covers it.\n\n const openFor = sig !== \"\" && !changed\n ? ` (unresolved ${\n fmtAge((now.getTime() - new Date(prev.since).getTime()) / 60000)\n })`\n : \"\";\n\n const subject = sig !== \"\"\n ? `TRMNL: device problem${openFor}`\n : recovered\n ? \"TRMNL: back to normal\"\n : firstRun\n ? \"TRMNL monitor is live\"\n : \"TRMNL: weekly all-clear\";\n\n const lines: (string | null)[] = [];\n if (sig !== \"\") {\n lines.push(\"PROBLEM\", \"\");\n alerts.forEach((a) => lines.push(` • ${a.text}`));\n lines.push(\"\");\n // Only offer device-recovery steps for an actual device problem.\n // Includes never: — a device that has NEVER checked in is precisely\n // the case the Wi-Fi pairing gesture in step 5 exists for.\n if (\n alerts.some((a) =>\n a.key.startsWith(\"down:\") || a.key.startsWith(\"never:\")\n )\n ) {\n lines.push(\n \"What to try, in order:\",\n \" 1. Tap the middle of the touch bar (it may just be asleep — free to try).\",\n \" 2. Soft reset: invert the dock, circular motion near the bottom-left of the back.\",\n \" 3. Charge it: dock on the centre of the TRMNL logo.\",\n \" 4. Check the dock pins / try the other dock orientation.\",\n \" 5. Re-pair Wi-Fi: hold BOTH ends of the touch bar until the screen blinks, then hold the middle.\",\n \" If this device drops repeatedly, pair it to 2.4 GHz rather than 5 GHz.\",\n \"\",\n );\n }\n } else if (recovered) {\n lines.push(\"RESOLVED — everything is checking in again.\", \"\");\n } else if (firstRun) {\n lines.push(\n \"The device liveness monitor ran for the first time and everything looks fine.\",\n \"\",\n \"From here it stays quiet. It emails you when a device has not checked in\",\n `for more than ${ALERT_AFTER_HOURS} hours, or when this monitor has been unable to reach`,\n \"TRMNL for that long — both have to persist, because both self-heal.\",\n \"\",\n `It emails immediately, without waiting, if a battery hits ${BATTERY_ALERT_PCT}%, a device`,\n \"disappears from your account or has never checked in, the API key stops\",\n \"working, or this monitor is misconfigured. None of those fix themselves.\",\n \"\",\n \"Wi-Fi signal strength is reported below for context but never triggers an email.\",\n `Plus one short all-clear every ${HEARTBEAT_DAYS} days, so that silence is never ambiguous.`,\n \"\",\n );\n } else {\n lines.push(\n `ALL CLEAR — nothing has needed your attention for ${\n Math.round(quietDays)\n } days.`,\n \"\",\n \"This message is a proof-of-life check, not news. If the monitor itself dies,\",\n \"or Val Town stops running it, your inbox looks exactly the same as when\",\n `everything is fine. So: if one of these fails to arrive within about ${\n HEARTBEAT_DAYS + 1\n } days,`,\n \"the thing to check is the monitor at val.town, not the screens.\",\n \"\",\n \"The readings below never trigger an email on their own. They are here so that\",\n \"slow drift — a battery trending down, Wi-Fi worsening month over month — is\",\n \"visible before it turns into a problem.\",\n \"\",\n );\n }\n\n if (context.length) {\n lines.push(\"Current readings:\");\n context.forEach((c) => lines.push(` - ${c}`));\n lines.push(\"\");\n }\n if (notes.length) {\n lines.push(\"Notes:\");\n notes.forEach((n) => lines.push(` - ${n}`));\n lines.push(\"\");\n }\n lines.push(\n `Checked ${now.toISOString()} — TRMNL Device Liveness (Val Town cron).`,\n `A silent device, or a monitor that cannot reach TRMNL, must stay that way ${ALERT_AFTER_HOURS}h before it emails.`,\n `Low battery, a missing or never-seen device, a rejected key, a misconfigured monitor, and a quote counter that is stuck or unverifiable all alert at once.`,\n `Otherwise: one all-clear every ${HEARTBEAT_DAYS} days, and nothing else.`,\n `Full runbook: section 17 of \"TRMNL Quote Display - System Log and Maintenance Guide.md\".`,\n );\n\n await email({ subject, text: lines.filter((l) => l !== null).join(\"\\n\") });\n emailed = true;\n }\n\n await blob.setJSON(STATE_KEY, {\n sig,\n since: changed ? now.toISOString() : prev.since,\n lastEmailAt: emailed ? now.toISOString() : prev.lastEmailAt,\n lastSeenAt: now.toISOString(),\n blindSince, // null on any run that reached the devices; clears the blind clock\n kind,\n lastAlerts: alerts.map((a) => a.key),\n // Carried forward untouched unless this run took a new observation, so the\n // 2-hourly cadence survives across runs and across every early-return path.\n ...(quoteWrite ?? {\n quoteAt: prev.quoteAt,\n quoteMode: prev.quoteMode,\n quoteAlert: prev.quoteAlert,\n }),\n });\n\n return { sig, emailed, alerts, notes };\n}","deleted",false,"label",[14],"1773c256-a0c3-4081-8f85-d76d74386ee4",["D",1787921812710],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Cron: TRMNL device liveness, emails on state change","imageUrl","userId","a5b8c2ff-3219-464a-b112-3d77ca9951e8","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","019ef991-b184-72ce-82ef-299400125b59","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_9":10,"_101":97},"org",{"_9":10,"_94":95,"_96":97,"_55":56,"_98":99,"_100":42},"branch",{"_35":30,"_11":85,"_22":28,"_86":45,"_87":-5,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":12,"_93":10},"isOwned","main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","displayName","Buddy Dillenberg","avatar","","tier","free","canRestrictVals","profileImageUrl","ctx",{"_78":-5,"_135":136,"_137":138,"_139":140,"_141":42,"_142":42,"_143":42,"_144":32,"_145":-5,"_146":-7,"_147":-7,"_148":62,"_149":42,"_150":42,"_151":-5,"_152":42,"_153":42,"_154":42,"_155":-5},"ENV",{"_106":107,"_108":109,"_110":85,"_111":112,"_113":114,"_115":116,"_117":118,"_119":120,"_121":122,"_123":124,"_125":126,"_127":128,"_129":130,"_131":132,"_133":134},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town","orgs",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]