> For the complete documentation index, see [llms.txt](https://mango-5m.gitbook.io/mango5m-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mango-5m.gitbook.io/mango5m-docs/resources/mango-admin/resource-protection/how-it-works.md).

# How It Works

What it watches, how it recovers, and why it cannot loop.

It has to be a **separate resource**, because a resource cannot restart itself.

## What each command does

| What happens to the admin menu         | What the guard does                                                     |
| -------------------------------------- | ----------------------------------------------------------------------- |
| `restart` / `ensure`                   | Nothing. It comes straight back; recorded as a **RESTART**              |
| `stop`                                 | Detected, recovered, recorded as a **STOP**, staff told, console logged |
| Not running at boot                    | Started after a grace period, recorded as **NOT RUNNING**               |
| Running but its script runtime is dead | The heartbeat notices; restarted and recorded as **UNRESPONSIVE**       |
| The whole server is shutting down      | Nothing. Not an incident                                                |
| The **guard itself** is stopped        | The panel starts it again and reports it                                |

## The heartbeat

A resource whose Lua died on load reports `started` forever. So the guard does not take the state at face value — every fifteen seconds it asks the panel to answer through an export. Answering at all is the point; a dead runtime cannot.

After three consecutive misses the panel is restarted. A build that has never answered since it started is **never** restarted for it, so an older panel without the export is not fought over.

## Why it cannot loop

| Guard              | What it stops                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| **Grace period**   | A restart is a stop followed at once by a start. 1.5 s of patience tells them apart                           |
| **One at a time**  | A second stop during a recovery has nothing to add                                                            |
| **Attempt window** | Three attempts in two minutes, spaced by a cooldown                                                           |
| **Escalation**     | After the last one it stops hammering and raises a **CRITICAL** incident                                      |
| **Slow retry**     | Then tries quietly every five minutes, so fixing the broken file brings it back without anyone remembering to |
| **Deduplication**  | Identical incidents within a few seconds are one line with a count                                            |

{% code title="mango\_watchdogs/config.lua" %}

```lua
Config.Recovery = {
    GraceMs           = 1500,
    SettleMs          = 4000,
    CooldownSeconds   = 10,
    MaxAttempts       = 3,
    WindowSeconds     = 120,
    CriticalRetrySeconds = 300,
    BootGraceSeconds  = 30,
}
```

{% endcode %}

## It guards both ways

Stop the **guard** and the panel starts it again, with the same discipline — a grace period, capped attempts, and an incident reported to the guard once it is back. So stopping the guard first and then the panel leaves the same trail as stopping the panel alone.

## Nothing here depends on a client

Every check, every recovery and every permission decision happens on the server. The watchdog has one client file, and it is not part of the protection — it is the stand-in report window, death reporting, and the decoys, all of which only matter while the panel is down. Everything it sends is checked on the server and none of it is trusted.