feat(daemon): Add UPSD (NUT) protocol support, Proxmox VM shutdown action, pause/resume monitoring, and network-loss/unreachable handling; bump config version to 4.2

readme.hints.md

@@ -12,8 +12,9 @@
 
 2. **Constants File (`ts/constants.ts`)**
    - Centralized all magic numbers (timeouts, intervals, thresholds)
-   - Contains: `TIMING`, `SNMP`, `THRESHOLDS`, `WEBHOOK`, `SCRIPT`, `SHUTDOWN`, `HTTP_SERVER`, `UI`
-   - Used in: `daemon.ts`, `snmp/manager.ts`, `actions/*.ts`
+   - Contains: `TIMING`, `SNMP`, `THRESHOLDS`, `WEBHOOK`, `SCRIPT`, `SHUTDOWN`, `HTTP_SERVER`, `UI`,
+     `NETWORK`, `UPSD`, `PAUSE`, `PROXMOX`
+   - Used in: `daemon.ts`, `snmp/manager.ts`, `actions/*.ts`, `upsd/client.ts`
 
 3. **Logger Consistency**
    - Replaced all `console.log/console.error` in `snmp/manager.ts` with proper `logger.*` calls
@@ -35,13 +36,47 @@
    - Uses: `IUpsConfig`, `INupstConfig`, `ISnmpConfig`, `IActionConfig`, `IThresholds`,
      `ISnmpUpsStatus`
 
+## Features Added (February 2026)
+
+### Network Loss Handling
+- `TPowerStatus` extended with `'unreachable'` state
+- `IUpsStatus` has `consecutiveFailures` and `unreachableSince` tracking
+- After `NETWORK.CONSECUTIVE_FAILURE_THRESHOLD` (3) failures, UPS transitions to `unreachable`
+- Shutdown action explicitly won't fire on `unreachable` (prevents false shutdowns)
+- Recovery is logged when UPS comes back from unreachable
+
+### UPSD/NIS Protocol Support
+- New `ts/upsd/` directory with TCP client for NUT (Network UPS Tools) servers
+- `ts/protocol/` directory with `ProtocolResolver` for protocol-agnostic status queries
+- `IUpsConfig.protocol` field: `'snmp'` (default) or `'upsd'`
+- `IUpsConfig.snmp` is now optional (not needed for UPSD devices)
+- CLI supports protocol selection during `nupst ups add`
+- Config version bumped to `4.2` with migration from `4.1`
+
+### Pause/Resume Command
+- File-based signaling via `/etc/nupst/pause` JSON file
+- `nupst pause [--duration 30m|2h|1d]` creates pause file
+- `nupst resume` deletes pause file
+- Daemon polls continue but actions are suppressed while paused
+- Auto-resume after duration expires
+- HTTP API includes pause state in response
+
+### Proxmox VM Shutdown Action
+- New action type `'proxmox'` in `ts/actions/proxmox-action.ts`
+- Uses Proxmox REST API with PVEAPIToken authentication
+- Shuts down QEMU VMs and LXC containers before host shutdown
+- Supports: exclude IDs, configurable timeout, force-stop, TLS skip for self-signed certs
+- Should be placed BEFORE shutdown actions in the action chain
+
 ## Architecture Notes
 
 - **SNMP Manager**: Uses `INupstAccessor` interface (not direct `Nupst` reference) to avoid circular
   imports
+- **Protocol Resolver**: Routes to SNMP or UPSD based on `IUpsConfig.protocol`
 - **CLI Handlers**: All use the `helpers.withPrompt()` utility for interactive input
 - **Constants**: All timing values should be referenced from `ts/constants.ts`
 - **Actions**: Use `IActionConfig` from `ts/actions/base-action.ts` for action configuration
+- **Config version**: Currently `4.2`, migrations run automatically
 
 ## File Organization
 
@@ -54,9 +89,21 @@ ts/
 │   ├── prompt.ts         # Readline utility
 │   └── shortid.ts        # ID generation
 ├── actions/
-│   ├── base-action.ts    # Base action class and interfaces
+│   ├── base-action.ts    # Base action class, IActionConfig, TPowerStatus
 │   ├── webhook-action.ts # Includes IWebhookPayload
+│   ├── proxmox-action.ts # Proxmox VM/LXC shutdown
 │   └── ...
+├── upsd/
+│   ├── types.ts          # IUpsdConfig
+│   ├── client.ts         # NupstUpsd TCP client
+│   └── index.ts
+├── protocol/
+│   ├── types.ts          # TProtocol = 'snmp' | 'upsd'
+│   ├── resolver.ts       # ProtocolResolver
+│   └── index.ts
+├── migrations/
+│   ├── migration-runner.ts
+│   └── migration-v4.1-to-v4.2.ts  # Adds protocol field
 └── cli/
     └── ...               # All handlers use helpers.withPrompt()
 ```