# OrpheAgent CLI Release Notes

## Version 1.1.1
**Release Date**: March 20, 2026

### Enhancements
- **Provision Discovery Now Carries Both Plane Identities**: During the Provision discovery stage, the discovery response now includes both `nodeID` and `dataPlaneNodeID`, together with the device name, serial number, model, version, management IP, and status. This lets the Controller receive both Control Plane and Data Plane identities earlier in the onboarding flow before follow-up configuration is applied.
- **Expanded Status and Service API Contracts**: `GET /api/v1/controlplane/status` now includes `is_provision`, and the Control Plane, Data Plane, and Service status flows now expose `license_lock` so operational tools can distinguish normal offline conditions from license-locked states. A new polling endpoint `GET /api/v1/service/status` is available alongside the existing WebSocket endpoint `GET /api/v1/service/status/ws`, and `GET /api/v1/dataplane/status`, `GET /api/v1/dataplane/status/ws` now carry `license_lock` per neighbor, so both polling and real-time monitoring can track availability and lock state consistently.
- **Data Plane Node Configuration Now Includes DNS**: The Data Plane node configuration flow now carries a `dns` field together with tunnel address, LAN subnet, exit node, and related node settings. When the full-tunnel route is active the preferred DNS is written to the system resolver; when the route is withdrawn the original resolver configuration is restored. This keeps preferred DNS information aligned when node data is retrieved, updated, and displayed through management APIs.
- **CLI Service Status and Restart Command**: The CLI `status` output now shows an overall Service Status section (Online / Offline / License Lock) before the Control Plane and Data Plane link tables. A new `restart` command is also registered, which calls the OpenWrt init.d service script to restart the agent. This is an OpenWrt-specific handling change.
- **OpenWrt Status Integration**: For OpenWrt deployments, the LuCI overview flow now consumes the new `GET /api/v1/service/status` endpoint together with the Data Plane status API to present online, offline, and license-locked states. The settings modal also reads `is_provision` from the Control Plane status API and conditionally hides the Provision Key field when the device is already provisioned. This is an OpenWrt-specific handling change.
- **QUIC Session Recovery Is Faster After Idle Periods**: The QUIC transport path now uses a shorter idle timeout, allowing stale P2P sessions to be recycled sooner after inactivity. This improves responsiveness when the connection path needs to recover or be re-established after temporary interruption.

### Bug Fixes
- **Provision Re-entry and Discovery Handling Are More Stable**: The Provision flow now checks the Controller connection state before starting Relay-assisted discovery and before processing incoming profile streams. Once the device is already connected or provisioned, duplicate discovery responses are discarded. The unused AutoProvision routine has also been removed, reducing unnecessary relay reservation overhead.
- **Service Status Synchronization During License Transitions**: When the Controller heartbeat response carries a `LicenseLock` status, the report flow now sets the license lock flag, resets the expiration time, and sends a service status broadcast immediately. Conversely, when the lock is released, the flag is cleared and an online broadcast is sent. The `leave` handler also distinguishes a `lock` message from a normal `leave`, updating the lock state and Data Plane accordingly so dashboards and local UIs receive the correct state without waiting for a later reconnect cycle.
- **Relay Reconnect Failure Triggers Plane Restart**: Both the Control Plane and Data Plane relay keep-alive routines now track consecutive reconnection failures per relay peer. After five consecutive failures the affected plane is automatically restarted, clearing stale P2P state and re-establishing connections without waiting for the next WAN-change check cycle.
- **UDP Hole Punch Retry Is Bounded**: The UDP hole punch routine now limits its fast retry loop to five attempts. If direct connectivity is not established within those attempts, the routine waits 60 seconds before exiting, preventing excessive dial attempts when the remote peer is unreachable.
- **Leave Controller and Full-Tunnel Cleanup Are More Consistent**: Route transition and shutdown handling now clear forwarding and DNS state more consistently. The full-tunnel stage applies IPv6 leak protection (blackhole routes for `::/1` and `8000::/1`) while the default route is active and removes it when the route is withdrawn. The leave handler also resets the license lock flag and sends an offline service status broadcast, preventing stale connectivity state and unintended IPv6 bypass traffic.
- **SaveToController Error Handling Is More Robust**: The inventory report flow now acquires a mutex to prevent concurrent submissions, and all error paths consistently reset the Controller connection flag so subsequent report cycles can retry cleanly.

### Known Issues
- No known unresolved issues at this time.
---

# OrpheAgent 指令版發行說明

## 版本 1.1.1
**發佈日期**：2026 年 3 月 20 日

### 增強功能
- **Provision 探索階段新增雙平面識別資料**：在 Provision 的設備探索階段，回傳資料現在會同時包含 `nodeID` 與 `dataPlaneNodeID`，並一併帶出裝置名稱、序號、型號、版本、管理 IP 與狀態。這讓 Controller 可以在後續下發設定前，先完成 Control Plane 與 Data Plane 身分的對應。
- **擴充狀態與服務狀態 API 契約**：`GET /api/v1/controlplane/status` 現在包含 `is_provision`，而 Control Plane、Data Plane 與 Service 的狀態流程也都補上 `license_lock`，讓營運端工具可以區分一般離線與授權鎖定狀態。新增輪詢端點 `GET /api/v1/service/status`，搭配既有的 WebSocket 端點 `GET /api/v1/service/status/ws`，而 `GET /api/v1/dataplane/status`、`GET /api/v1/dataplane/status/ws` 也在每筆 neighbor 資料中帶出 `license_lock`，使輪詢與即時監看場景都能一致地追蹤可用性與鎖定狀態。
- **Data Plane 節點設定新增 DNS 資料**：Data Plane 節點設定流程現在會在隧道位址、LAN 子網、Exit Node 與其他節點設定之外，一併傳遞 `dns` 欄位。當 full-tunnel 路由啟用時，偏好的 DNS 會寫入系統解析器；路由撤除時則還原原始解析器設定。這讓管理端在讀取、更新與呈現節點資料時，可以同步掌握偏好的 DNS 設定。
- **CLI 服務狀態顯示與 Restart 指令**：CLI `status` 輸出現在會在 Control Plane 與 Data Plane 連線表之前，先顯示整體 Service Status 區段（Online / Offline / License Lock）。同時新增 `restart` 指令，透過 OpenWrt init.d 服務腳本重新啟動 Agent。這是針對 OpenWrt 的處理。
- **OpenWrt 狀態整合**：針對 OpenWrt，LuCI Overview 流程現在會搭配新的 `GET /api/v1/service/status` 端點與 Data Plane 狀態 API，一併呈現 online、offline 與 license-locked 狀態。設定彈窗也會讀取 Control Plane 狀態 API 中的 `is_provision`，在裝置已完成 Provision 時自動隱藏 Provision Key 欄位。這是針對 OpenWrt 的處理。
- **QUIC 閒置連線恢復更快**：QUIC 傳輸路徑現在採用較短的閒置逾時設定，讓長時間未使用的 P2P 連線可以更早被回收。在連線暫時中斷後需要重新建立或切換路徑時，整體恢復反應會更快。

### 錯誤修復
- **Provision 重入與探索處理更穩定**：Provision 流程在啟動 Relay 輔助探索前，以及在處理傳入的 profile stream 前，現在都會先檢查 Controller 連線狀態。一旦裝置已連線或已完成 Provision，重複的探索回應便會被捨棄。同時移除了未使用的 AutoProvision 程序，減少不必要的 Relay 保留開銷。
- **授權狀態切換時的服務狀態同步更即時**：當 Controller 的心跳回應攜帶 `LicenseLock` 狀態時，Report 流程會立即設定 license lock 旗標、歸零到期時間，並發送服務狀態廣播。反之當 lock 解除時，旗標會被清除並發送 online 廣播。`leave` handler 也會區分 `lock` 訊息與一般 `leave`，據此更新鎖定狀態與 Data Plane，使儀表板與本地 UI 不必等到下一次重連週期便能取得正確狀態。
- **Relay 連續重連失敗觸發平面重啟**：Control Plane 與 Data Plane 的 Relay keep-alive 流程現在會追蹤每個 Relay peer 的連續重連失敗次數。累計五次失敗後，受影響的平面會自動重啟，清除過期的 P2P 狀態並重新建立連線，無須等待下一次 WAN 變更檢查週期。
- **UDP Hole Punch 重試次數受限**：UDP hole punch 流程現在將快速重試迴圈限制為五次。若在這些嘗試內未建立直連，流程會等待 60 秒後才結束，避免遠端 peer 不可達時產生過多的 dial 嘗試。
- **Leave Controller 與 Full-Tunnel 清理更一致**：路由切換與停止流程現在會更一致地清理 forwarding 與 DNS 狀態。在 full-tunnel 階段啟用預設路由時，會同步套用 IPv6 leak protection（為 `::/1` 與 `8000::/1` 加入 blackhole 路由），撤除預設路由時則一併移除。`leave` handler 也會重設 license lock 旗標並發送 offline 服務狀態廣播，降低殘留連線狀態與 IPv6 流量繞過隧道的風險。
- **SaveToController 錯誤處理更健全**：庫存報告流程現在會取得 mutex 以防止並行提交，且所有錯誤路徑都會一致地重設 Controller 連線旗標，讓後續報告週期可以乾淨地重試。

### 已知問題
- 目前沒有已知且尚未解決的問題。
---
