dsh-offpeak-guard 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0 — 2026-11-05
+
+- 默认规则改为 DeepSeek 官方峰谷：工作日 09:00–12:00、14:00–18:00 峰时，周末与**中国法定节假日全天**谷价；内置 2026 年节假日列表。
+- 新增 `preset`：`auto` / `deepseek-official` / `workbuddy` / `custom`，按 provider 自动选择（WorkBuddy/CodeBuddy → workbuddy，其余 → 官方）。
+- 新增 `Config` schema：DSH 设置页可直接修改时区、窗口、豁免模型、提醒阈值等。
+- 新增 `DSH_OFFPEAK_*` 环境变量覆盖（优先级：环境变量 > 配置 > 默认），便于部署方统一注入。
+- 状态工具与界面显示当前规则和节假日状态。
+
+## 0.1.0 — 2026-11-05
+
+- 首个公开版本。
+- 时间识别：工作日 `09:00–12:00`、`14:00–18:00` 峰时，其余时间谷价 5 折（可配置窗口、星期、时区与折扣）。
+- 模型识别：按会话真实请求头判断是否峰谷计价模型，支持逐模型豁免。
+- 峰时自动暂停运行中的任务、停住峰时新任务；谷价开始自动恢复被中断的任务（保留待处理队列）。
+- 错峰工作规划：`offpeak_plan` 把任务排进下一个谷价窗口，谷价时段自动执行。
+- 界面：输入框下方峰谷状态条；左栏底部紧凑计时（临近峰价闪红、临近谷价闪绿），悬浮说明保持稳定不闪。
+- 手动控制：`offpeak_guard` 的 `pause_now` / `resume_now` / `run_plans_now`。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HATO-24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,109 @@
+# Off-peak guard (dsh-offpeak-guard)
+
+[![npm](https://img.shields.io/npm/v/dsh-offpeak-guard?color=blue)](https://www.npmjs.com/package/dsh-offpeak-guard)
+
+Published on npm: install it from the DSH Plugins page, or run
+`dsh plugin --profile <profile> add dsh-offpeak-guard`.
+
+Schedule work around **DeepSeek peak/off-peak pricing** inside DeepSeek Harness:
+
+- **Time awareness**: per DeepSeek's official pricing, Beijing-time weekdays (excluding Chinese statutory holidays) `09:00–12:00` and `14:00–18:00` are peak; every other hour (weekends, holidays, lunch, night) is off-peak at 50%. Built-in Chinese holidays cover 2026; add later years with `holidays`.
+- **Model awareness**: only sessions using a peak-priced model (model name contains `deepseek` by default; exempt models one by one with `exemptModels`) are paused/resumed. Other models are untouched.
+- **Work planning**:
+  - peak starts → running tasks are paused (the pending inbox is kept, no message is lost);
+  - a task started during peak → stopped immediately, no peak-priced tokens spent;
+  - off-peak starts → interrupted tasks are handed back to their session automatically;
+  - the `offpeak_plan` tool queues "run this at noon" work for the next off-peak window.
+- **UI**: a status strip under the composer (state, countdown, model, paused/planned counts), plus a compact clock at the sidebar foot that blinks red before peak starts and green before off-peak starts.
+
+![Status strip under the composer](docs/peak-strip.png)
+
+Sidebar clock, colored by the current window:
+
+![Sidebar clock](docs/sidebar-clock.png)
+
+Red blink within the alert window before peak (sample):
+
+![Sidebar clock blinking red](docs/sidebar-clock-blink.png)
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `offpeak_status` | Current window, next switch, whether the current model is peak-priced, paused/planned lists |
+| `offpeak_plan` | `add` / `list` / `remove` / `clear` off-peak plans |
+| `offpeak_guard` | `status` / `pause_now` / `resume_now` / `run_plans_now` manual control |
+
+## Configuration
+
+The `offpeak-guard` row's `config` in `cordis.patch.yml`, or the plugin settings form in DSH (a Config schema is declared):
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch |
+| `preset` | `auto` | `auto` picks by provider: WorkBuddy/CodeBuddy → `workbuddy`, otherwise `deepseek-official`; can be pinned to `deepseek-official` / `workbuddy` / `custom` |
+| `timezone` | `Asia/Shanghai` | Pricing time zone (DeepSeek bills in Beijing time) |
+| `peakWeekdays` | `[1,2,3,4,5]` | Weekdays with peak windows (0 = Sunday); only used by `custom` |
+| `peakWindows` | 09:00–12:00, 14:00–18:00 | Peak windows; only used by `custom` |
+| `discount` | `0.5` | Off-peak discount, display only; only used by `custom` |
+| `holidays` | `[]` | Extra statutory holidays (`YYYY-MM-DD`), appended to the built-in 2026 list for the official/WorkBuddy presets |
+| `modelPattern` | `deepseek` | Model/provider name containing it counts as peak-priced |
+| `exemptModels` | `[]` | Model ids exempted one by one |
+| `pauseRunningOnPeak` | `true` | Pause running tasks when peak starts |
+| `deferNewTurnsOnPeak` | `true` | Stop tasks started during peak immediately |
+| `resumeOnOffPeak` | `true` | Resume paused tasks when off-peak starts |
+| `pollSeconds` | `15` | Check interval (5–300) |
+| `resumeDelaySeconds` | `3` | Wait a few seconds after off-peak starts before resuming |
+| `bypassMinutes` | `10` | Grace period after a manual resume |
+| `alertMinutes` | `10` | Blink the sidebar clock within this many minutes of a switch (0 = never) |
+
+### Environment variables
+
+Deployments can inject settings with environment variables. Priority: **env > config > default**. Invalid values are ignored.
+
+| Variable | Example | Config field |
+| --- | --- | --- |
+| `DSH_OFFPEAK_ENABLED` | `0` / `1` | `enabled` |
+| `DSH_OFFPEAK_PRESET` | `custom` | `preset` |
+| `DSH_OFFPEAK_TIMEZONE` | `Asia/Shanghai` | `timezone` |
+| `DSH_OFFPEAK_PEAK_WEEKDAYS` | `1,2,3,4,5` | `peakWeekdays` |
+| `DSH_OFFPEAK_PEAK_WINDOWS` | `09:00-12:00,14:00-18:00` | `peakWindows` |
+| `DSH_OFFPEAK_DISCOUNT` | `0.5` | `discount` |
+| `DSH_OFFPEAK_HOLIDAYS` | `2026-10-01,2026-10-02` | `holidays` |
+| `DSH_OFFPEAK_MODEL_PATTERN` | `deepseek` | `modelPattern` |
+| `DSH_OFFPEAK_EXEMPT_MODELS` | `deepseek-v4-pro,deepseek-flash` | `exemptModels` |
+| `DSH_OFFPEAK_PAUSE_RUNNING` | `0` / `1` | `pauseRunningOnPeak` |
+| `DSH_OFFPEAK_DEFER_NEW` | `0` / `1` | `deferNewTurnsOnPeak` |
+| `DSH_OFFPEAK_RESUME` | `0` / `1` | `resumeOnOffPeak` |
+| `DSH_OFFPEAK_POLL_SECONDS` | `15` | `pollSeconds` |
+| `DSH_OFFPEAK_RESUME_DELAY_SECONDS` | `3` | `resumeDelaySeconds` |
+| `DSH_OFFPEAK_BYPASS_MINUTES` | `10` | `bypassMinutes` |
+| `DSH_OFFPEAK_ALERT_MINUTES` | `10` | `alertMinutes` |
+
+### Presets
+
+- `deepseek-official` (default): official weekday peak windows plus built-in 2026 Chinese holidays (holidays are off-peak all day).
+- `workbuddy`: same peak windows, labeled as WorkBuddy credit pricing; selected automatically for WorkBuddy/CodeBuddy providers.
+- `custom`: use `peakWeekdays` / `peakWindows` / `discount` / `holidays` exactly, for other providers or self-hosted pricing.
+
+
+## Data
+
+State and snapshots live in `$DSH_HOME/offpeak-guard/`:
+
+- `state.json`: paused tasks, off-peak plans, last phase;
+- `status.json`: read-only snapshot for the UI (mirrored to `~/.dsh/offpeak-guard/status.json`).
+
+Nothing is written into user workspaces.
+
+## How resuming works
+
+Pause uses `sessionController.cancel`, which ends only the current turn and keeps the pending inbox. Resume uses `sessionController.prompt` to deliver a "continue where you left off" instruction to the original session; cold sessions are woken automatically. The resume text mentions the interruption time and the paused model so it stays traceable in the conversation.
+
+## Boundaries
+
+- Built-in statutory holidays cover 2026 only; after the 2027 schedule is published, upgrade the plugin or append dates with `holidays` / `DSH_OFFPEAK_HOLIDAYS`, otherwise holidays are treated as ordinary weekdays.
+- Named presets have fixed windows; use `preset: custom` for other providers or self-hosted pricing.
+- Only root sessions with a working directory are handled; subagent sessions are skipped so parents do not hang.
+- A plugin restart does not cancel tasks that are already running (so installing the plugin cannot kill the current conversation); the next peak or new task follows the rules again.
+- Manual `resume_now` grants those sessions a 10-minute grace period so they are not paused again immediately.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# 错峰调度 · 峰谷守卫（dsh-offpeak-guard）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/dsh-offpeak-guard?color=blue)](https://www.npmjs.com/package/dsh-offpeak-guard)
+
+已发布到 npm：在 DSH 的插件页搜索 `dsh-offpeak-guard` 安装，或运行
+`dsh plugin --profile <profile> add dsh-offpeak-guard`。
+
+在 DeepSeek Harness 里按 **DeepSeek 峰谷计价** 安排工作：
+
+- **时间识别**：按 DeepSeek 官方规则，北京时间周一至周五（不含中国法定节假日）`09:00–12:00`、`14:00–18:00` 为峰值原价；其余时间（含周末、法定节假日全天）为谷价，按 5 折计费。内置 2026 年法定节假日；后续年份可用 `holidays` 追加。
+- **模型识别**：只有使用峰谷计价模型（默认模型名含 `deepseek`，可在 `exemptModels` 里逐项豁免）的会话才会被暂停/恢复；用其它模型的会话不受影响。
+- **工作规划**：
+  - 峰时开始 → 暂停正在运行的任务（保留待处理队列，不丢消息）；
+  - 峰时新起的任务 → 立即停住，不花峰时 token；
+  - 谷价开始 → 自动把被打断的任务交还会话继续执行；
+  - 另提供 `offpeak_plan` 工具，把「12 点再跑」这类事排进下一个谷价窗口。
+- **界面**：输入框下方一条状态条，显示当前峰/谷、距下次切换的倒计时、当前模型，以及暂停/规划数量；左侧栏底部另有一枚常驻计时，临近切换时闪色提醒（峰价快开始闪红、谷价快开始闪绿）。
+
+![输入框下方的峰谷状态条](docs/peak-strip.png)
+
+左栏计时（平时按峰/谷着色）：
+
+![左栏峰谷计时](docs/sidebar-clock.png)
+
+距峰价开始 10 分钟内闪红（示例）：
+
+![左栏峰谷计时闪红](docs/sidebar-clock-blink.png)
+
+## 工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `offpeak_status` | 当前时段、下次切换、当前模型是否适用、暂停与规划清单 |
+| `offpeak_plan` | `add` / `list` / `remove` / `clear` 错峰规划 |
+| `offpeak_guard` | `status` / `pause_now` / `resume_now` / `run_plans_now` 手动控制 |
+
+## 配置
+
+`cordis.patch.yml` 里那一行 `offpeak-guard` 的 `config`，或在 DSH 设置页的插件配置里修改（已声明 Config schema）：
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `enabled` | `true` | 总开关 |
+| `preset` | `auto` | `auto` 按 provider 自动选：WorkBuddy/CodeBuddy → `workbuddy`，其余 → `deepseek-official`；也可固定为 `deepseek-official` / `workbuddy` / `custom` |
+| `timezone` | `Asia/Shanghai` | 计价时区（DeepSeek 计费按北京时间） |
+| `peakWeekdays` | `[1,2,3,4,5]` | 峰时适用的星期（0=周日）；仅 `custom` 预设使用 |
+| `peakWindows` | 09:00–12:00、14:00–18:00 | 峰时窗口；仅 `custom` 预设使用，官方调价时改这里 |
+| `discount` | `0.5` | 谷价折扣，仅用于显示「5 折」；仅 `custom` 预设使用 |
+| `holidays` | `[]` | 追加的法定节假日（`YYYY-MM-DD`），官方/WorkBuddy 预设会在内置 2026 列表上追加 |
+| `modelPattern` | `deepseek` | 模型名/供应商名包含它即视为峰谷计价模型 |
+| `exemptModels` | `[]` | 逐项豁免的模型 id |
+| `pauseRunningOnPeak` | `true` | 峰时开始时暂停正在运行的任务 |
+| `deferNewTurnsOnPeak` | `true` | 峰时新起的任务立即停住 |
+| `resumeOnOffPeak` | `true` | 谷价开始时自动恢复 |
+| `pollSeconds` | `15` | 检查间隔（5–300） |
+| `resumeDelaySeconds` | `3` | 谷价开始后等几秒再恢复 |
+| `bypassMinutes` | `10` | 手动恢复后的豁免期，避免立刻又被暂停 |
+| `alertMinutes` | `10` | 左栏计时在距切换多少分钟内开始闪烁（0 = 不闪） |
+
+### 环境变量
+
+部署方可以用环境变量统一注入，优先级：**环境变量 > 配置 > 默认**。无效值会被忽略。
+
+| 环境变量 | 例子 | 对应配置 |
+| --- | --- | --- |
+| `DSH_OFFPEAK_ENABLED` | `0` / `1` | `enabled` |
+| `DSH_OFFPEAK_PRESET` | `custom` | `preset` |
+| `DSH_OFFPEAK_TIMEZONE` | `Asia/Shanghai` | `timezone` |
+| `DSH_OFFPEAK_PEAK_WEEKDAYS` | `1,2,3,4,5` | `peakWeekdays` |
+| `DSH_OFFPEAK_PEAK_WINDOWS` | `09:00-12:00,14:00-18:00` | `peakWindows` |
+| `DSH_OFFPEAK_DISCOUNT` | `0.5` | `discount` |
+| `DSH_OFFPEAK_HOLIDAYS` | `2026-10-01,2026-10-02` | `holidays` |
+| `DSH_OFFPEAK_MODEL_PATTERN` | `deepseek` | `modelPattern` |
+| `DSH_OFFPEAK_EXEMPT_MODELS` | `deepseek-v4-pro,deepseek-flash` | `exemptModels` |
+| `DSH_OFFPEAK_PAUSE_RUNNING` | `0` / `1` | `pauseRunningOnPeak` |
+| `DSH_OFFPEAK_DEFER_NEW` | `0` / `1` | `deferNewTurnsOnPeak` |
+| `DSH_OFFPEAK_RESUME` | `0` / `1` | `resumeOnOffPeak` |
+| `DSH_OFFPEAK_POLL_SECONDS` | `15` | `pollSeconds` |
+| `DSH_OFFPEAK_RESUME_DELAY_SECONDS` | `3` | `resumeDelaySeconds` |
+| `DSH_OFFPEAK_BYPASS_MINUTES` | `10` | `bypassMinutes` |
+| `DSH_OFFPEAK_ALERT_MINUTES` | `10` | `alertMinutes` |
+
+### 预设
+
+- `deepseek-official`（默认）：官方工作日峰时 + 内置 2026 法定节假日（节假日全天谷价）。
+- `workbuddy`：WorkBuddy 积分规则，峰时窗口与官方相同；按 provider 自动选择时用于标注来源。
+- `custom`：完全使用 `peakWeekdays` / `peakWindows` / `discount` / `holidays`，适合其他供应商或自建计价。
+
+
+## 数据
+
+状态与快照都在 `$DSH_HOME/offpeak-guard/`：
+
+- `state.json`：暂停中的任务、错峰规划、上次时段；
+- `status.json`：给输入框状态条读的只读快照（同时镜像到 `~/.dsh/offpeak-guard/status.json`）。
+
+不写用户工作区。
+
+## 恢复是怎么做的
+
+暂停用 `sessionController.cancel`，它只结束当前一轮、保留待处理队列；恢复用 `sessionController.prompt` 向原会话投递一条「继续上次中断处」的指令，冷会话会被自动唤醒。恢复文本会注明中断时间与被暂停的模型，方便对话里追溯。
+
+## 边界
+
+- 内置法定节假日目前覆盖 2026 年；2027 年安排公布后可升级插件，或用 `holidays` / `DSH_OFFPEAK_HOLIDAYS` 追加，否则节假日会被当作普通工作日。
+- 命名预设的窗口是固定的；需要其他供应商/自建计价时用 `preset: custom` 配 `peakWindows`。
+- 只处理有工作目录、非子代理的根会话，避免打断子代理让父会话卡住。
+- 插件自身重启时不会主动打断正在跑的任务（避免刚安装就停掉当前对话）；之后进入峰时或新起任务仍按规则处理。
+- 手动「立即恢复」会给这些会话 10 分钟豁免，避免峰时刚恢复又被停回去。

package/client.js

@@ -0,0 +1,395 @@
+/**
+ * 峰谷守卫的 Web 半：输入框下方的状态条。
+ * 只读展示，数据来自 Host 周期写出的 status.json，倒计时在本地按秒刷新。
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-offpeak-guard',
+  factory(require) {
+    const React = require('react');
+    const h = React.createElement;
+    const NS = 'offpeak-guard';
+
+    const zh = {
+      peak: '峰时原价',
+      offpeak: '谷价',
+      toPeak: '距峰时',
+      toOffpeak: '距谷价',
+      paused: '已暂停',
+      plans: '规划',
+      title: 'DeepSeek 峰谷计价',
+      windows: '峰时：工作日 09:00–12:00、14:00–18:00',
+      offpeakNote: '谷价：其余时间（含周末与午间），按 5 折计费',
+      model: '当前模型',
+      guard: '守卫',
+      on: '开',
+      off: '关',
+      pausedNote: '被峰时暂停的任务会在谷价开始时自动恢复',
+      plansNote: '排定的错峰任务会在谷价时段自动执行',
+      unavailable: '峰谷状态暂不可用',
+      peakShort: '峰',
+      valleyShort: '谷',
+      toPeakShort: '距峰',
+      toOffpeakShort: '距谷',
+      clockHint: '临近切换时闪烁：红色 = 峰价快开始，绿色 = 谷价快开始',
+      clockTitle: '峰谷计时',
+      nextSwitch: '下次切换',
+    };
+
+    const en = {
+      peak: 'Peak price',
+      offpeak: 'Off-peak',
+      toPeak: 'to peak',
+      toOffpeak: 'to off-peak',
+      paused: 'paused',
+      plans: 'planned',
+      title: 'DeepSeek peak/off-peak pricing',
+      windows: 'Peak: weekdays 09:00–12:00 and 14:00–18:00',
+      offpeakNote: 'Off-peak: all other hours (including weekends and lunch), billed at 50%',
+      model: 'Model',
+      guard: 'Guard',
+      on: 'on',
+      off: 'off',
+      pausedNote: 'Tasks paused at peak resume automatically when off-peak starts',
+      plansNote: 'Planned tasks run automatically during off-peak',
+      unavailable: 'Off-peak status unavailable',
+      peakShort: 'Peak',
+      valleyShort: 'Valley',
+      toPeakShort: 'to peak',
+      toOffpeakShort: 'to off-peak',
+      clockHint: 'Blink near the switch: red = peak starts soon, green = off-peak starts soon',
+      clockTitle: 'Peak/off-peak timer',
+      nextSwitch: 'next switch',
+    };
+
+    function fmtDuration(ms) {
+      const totalMinutes = Math.floor(Math.max(0, ms) / 60000);
+      if (totalMinutes < 1) return '不到1分';
+      const days = Math.floor(totalMinutes / 1440);
+      const hours = Math.floor((totalMinutes % 1440) / 60);
+      const minutes = totalMinutes % 60;
+      if (days > 0) return hours > 0 ? `${days}天${hours}小时` : `${days}天`;
+      if (hours > 0) return minutes > 0 ? `${hours}小时${minutes}分` : `${hours}小时`;
+      return `${minutes}分`;
+    }
+
+    function useLocale(ctx) {
+      const [, force] = React.useState(0);
+      React.useEffect(() => {
+        if (!ctx.locale || typeof ctx.locale.subscribe !== 'function') return undefined;
+        const off = ctx.locale.subscribe(() => force((value) => value + 1));
+        return () => {
+          if (typeof off === 'function') {
+            try {
+              off();
+            } catch {
+              /* ignore */
+            }
+          }
+        };
+      }, []);
+      return ctx.locale ? ctx.locale.bind(NS) : (key) => key;
+    }
+
+    function snapshotTextOf(result) {
+      if (result?.ok === false) throw new Error(result?.error?.message ?? 'status read failed');
+      const page = result?.value ?? result;
+      const text = typeof page === 'string' ? page : page?.text;
+      if (typeof text !== 'string' || text.length === 0) throw new Error('status file is empty');
+      return text;
+    }
+
+    function useSnapshot(ctx, sessionId) {
+      const [snapshot, setSnapshot] = React.useState(null);
+      const [error, setError] = React.useState(null);
+      const busy = React.useRef(false);
+      const mounted = React.useRef(true);
+
+      const load = React.useCallback(async () => {
+        if (busy.current) return;
+        busy.current = true;
+        try {
+          const remote = ctx.remote;
+          if (!remote || typeof remote.workspaceFiles?.read !== 'function') {
+            throw new Error('remote.workspaceFiles 不可用');
+          }
+          let target = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+          if (target === null) {
+            if (typeof remote.session?.list !== 'function') throw new Error('remote.session 不可用');
+            const listed = await remote.session.list({});
+            const items = listed?.value?.items ?? listed?.items ?? [];
+            if (!Array.isArray(items) || items.length === 0) return;
+            const sorted = [...items].sort(
+              (left, right) => Number(right.updatedAt ?? right.lastActivityAt ?? 0) - Number(left.updatedAt ?? left.lastActivityAt ?? 0),
+            );
+            target = sorted[0]?.sessionId ?? sorted[0]?.id ?? null;
+          }
+          const home = remote.$host?.home;
+          if (typeof target !== 'string' || target.length === 0) throw new Error('没有可用的会话');
+          if (typeof home !== 'string' || home.length === 0) throw new Error('读不到 Harness 主目录');
+          const result = await remote.workspaceFiles.read(target, `${home}/.dsh/offpeak-guard/status.json`, {});
+          const parsed = JSON.parse(snapshotTextOf(result));
+          if (mounted.current && parsed !== null && typeof parsed === 'object') {
+            setSnapshot(parsed);
+            setError(null);
+          }
+        } catch (caught) {
+          if (mounted.current) setError(String(caught?.message ?? caught));
+        } finally {
+          busy.current = false;
+        }
+      }, [sessionId]);
+
+      React.useEffect(() => {
+        mounted.current = true;
+        void load();
+        const timer = setInterval(() => void load(), 30000);
+        return () => {
+          mounted.current = false;
+          clearInterval(timer);
+        };
+      }, [load]);
+
+      return { snapshot, error };
+    }
+
+    function makeStrip(pluginCtx) {
+      return function Strip(props) {
+        const ctx = pluginCtx;
+        const t = useLocale(ctx);
+      const { snapshot, error } = useSnapshot(ctx, props?.sessionId);
+      const [, force] = React.useState(0);
+
+      React.useEffect(() => {
+        const timer = setInterval(() => force((value) => value + 1), 1000);
+        return () => clearInterval(timer);
+      }, []);
+
+      if (snapshot === null) {
+        if (error === null) return h('div', { style: { textAlign: 'center', fontSize: 11, opacity: 0.4, padding: '2px 0 4px' } }, '…');
+        return h('div', { title: error, style: { textAlign: 'center', fontSize: 11, opacity: 0.5, padding: '2px 0 4px' } }, t('unavailable'));
+      }
+
+      const phase = snapshot.phase === 'peak' ? 'peak' : 'offpeak';
+      const nextAt = Number(snapshot.next?.at);
+      const remaining = Number.isFinite(nextAt) ? Math.max(0, nextAt - Date.now()) : 0;
+      const ownModel =
+        props?.sessionId && snapshot.sessions && typeof snapshot.sessions === 'object'
+          ? snapshot.sessions[props.sessionId]
+          : null;
+      const activeModel = ownModel ?? snapshot.model ?? {};
+      const modelId =
+        typeof activeModel.label === 'string' && activeModel.label !== ''
+          ? activeModel.label
+          : typeof activeModel.id === 'string'
+            ? activeModel.id
+            : '';
+      const paused = Number(snapshot.counts?.interrupted ?? 0);
+      const plans = Number(snapshot.counts?.plans ?? 0);
+      const guardOn = snapshot.guard?.enabled === true;
+      const nextLabel = phase === 'peak' ? t('toOffpeak') : t('toPeak');
+
+      const tip = [
+        t('title'),
+        t('windows'),
+        t('offpeakNote'),
+        `${t('model')}: ${modelId || '—'}${activeModel.peakPriced ? ` (${phase === 'peak' ? t('peak') : t('offpeak')})` : ''}`,
+        `${t('guard')}: ${guardOn ? t('on') : t('off')}`,
+        paused > 0 ? `${t('paused')}: ${paused} — ${t('pausedNote')}` : '',
+        plans > 0 ? `${t('plans')}: ${plans} — ${t('plansNote')}` : '',
+      ]
+        .filter(Boolean)
+        .join('\n');
+
+      const children = [
+        h('span', {
+          key: 'dot',
+          'aria-hidden': true,
+          style: {
+            width: 7,
+            height: 7,
+            borderRadius: '50%',
+            flex: '0 0 auto',
+            backgroundColor: phase === 'peak' ? '#e0a33e' : '#3f9d7a',
+          },
+        }),
+        h('span', { key: 'phase', style: { fontWeight: 600 } }, t(phase)),
+        h('span', { key: 'next' }, `${nextLabel} ${fmtDuration(remaining)}`),
+      ];
+      if (modelId !== '') children.push(h('span', { key: 'model', style: { opacity: 0.75 } }, `· ${modelId}`));
+      if (paused > 0) children.push(h('span', { key: 'paused', style: { color: '#e0a33e' } }, `· ${t('paused')} ${paused}`));
+      if (plans > 0) children.push(h('span', { key: 'plans' }, `· ${t('plans')} ${plans}`));
+
+      return h(
+        'div',
+        {
+          title: tip,
+          style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 8,
+            padding: '2px 6px 6px',
+            fontSize: 11,
+            lineHeight: 1.4,
+            color: 'var(--dsw-alias-label-secondary, rgba(115,119,128,0.92))',
+            userSelect: 'none',
+          },
+        },
+        children,
+      );
+    };
+    }
+
+    function fmtClock(ms) {
+      const total = Math.max(0, Math.floor(ms / 1000));
+      const days = Math.floor(total / 86400);
+      const hours = Math.floor((total % 86400) / 3600);
+      const minutes = Math.floor((total % 3600) / 60);
+      const seconds = total % 60;
+      const pad = (value) => String(value).padStart(2, '0');
+      if (days > 0) return `${days}天${hours}时`;
+      if (hours > 0) return `${hours}:${pad(minutes)}:${pad(seconds)}`;
+      return `${minutes}:${pad(seconds)}`;
+    }
+
+    /** 平时只显示到分钟（紧凑，不挤占左栏其它按钮）；临近切换时显示秒。 */
+    function fmtClockCompact(ms, withSeconds) {
+      const total = Math.max(0, Math.floor(ms / 1000));
+      const days = Math.floor(total / 86400);
+      const hours = Math.floor((total % 86400) / 3600);
+      const minutes = Math.floor((total % 3600) / 60);
+      const seconds = total % 60;
+      const pad = (value) => String(value).padStart(2, '0');
+      if (days > 0) return withSeconds ? `${days}天${hours}时` : `${days}天${hours}时`;
+      if (hours > 0) return withSeconds ? `${hours}:${pad(minutes)}:${pad(seconds)}` : `${hours}:${pad(minutes)}`;
+      return `${minutes}:${pad(seconds)}`;
+    }
+
+    const clockStyle = `
+.opg-clock{box-sizing:border-box;display:inline-flex;flex:0 0 auto;align-items:center;gap:5px;width:auto;max-width:100%;min-height:32px;margin-left:auto;padding:4px 8px;border-radius:8px;color:var(--dsw-alias-label-primary,#252936);font:500 12px/18px var(--dsw-font-family,system-ui,sans-serif);white-space:nowrap;-webkit-app-region:no-drag;}
+.opg-clock[data-compact="true"]{width:32px;min-height:32px;justify-content:center;padding:6px;gap:0;}
+.opg-clock-dot{flex:none;width:7px;height:7px;border-radius:50%;background:currentColor;}
+.opg-clock-state{flex:none;}
+.opg-clock-time{flex:none;font-variant-numeric:tabular-nums;letter-spacing:.2px;}
+.opg-clock[data-tone="peak"]{color:#e0554e;}
+.opg-clock[data-tone="valley"]{color:#3f9d7a;}
+.opg-clock[data-blink="red"]{animation:opg-blink-red .9s ease-in-out infinite;}
+.opg-clock[data-blink="green"]{animation:opg-blink-green .9s ease-in-out infinite;}
+@keyframes opg-blink-red{0%,100%{color:#e0554e;opacity:1;}50%{color:#ff8f8a;opacity:.4;}}
+@keyframes opg-blink-green{0%,100%{color:#3f9d7a;opacity:1;}50%{color:#69d3aa;opacity:.4;}}
+@media (prefers-reduced-motion: reduce){.opg-clock[data-blink]{animation:none;}}
+`;
+
+    function ClockIcon() {
+      return h(
+        'svg',
+        {
+          width: 16,
+          height: 16,
+          viewBox: '0 0 24 24',
+          fill: 'none',
+          stroke: 'currentColor',
+          strokeWidth: 1.8,
+          strokeLinecap: 'round',
+          strokeLinejoin: 'round',
+          'aria-hidden': true,
+          style: { flex: 'none' },
+        },
+        [h('circle', { key: 'c', cx: 12, cy: 12, r: 8.5 }), h('path', { key: 'h', d: 'M12 7.5V12l3 1.8' })],
+      );
+    }
+
+    function makeClock(pluginCtx) {
+      return function Clock(props) {
+        const t = useLocale(pluginCtx);
+        const { snapshot } = useSnapshot(pluginCtx, null);
+        const [, force] = React.useState(0);
+        React.useEffect(() => {
+          const timer = setInterval(() => force((value) => value + 1), 1000);
+          return () => clearInterval(timer);
+        }, []);
+        if (snapshot === null) return null;
+
+        const phase = snapshot.phase === 'peak' ? 'peak' : 'offpeak';
+        const nextAt = Number(snapshot.next?.at);
+        const remaining = Number.isFinite(nextAt) ? Math.max(0, nextAt - Date.now()) : 0;
+        const alertMs = Math.max(0, Number(snapshot.alertMinutes ?? 10)) * 60000;
+        const near = alertMs > 0 && remaining > 0 && remaining <= alertMs;
+        const blink = near ? (phase === 'offpeak' ? 'red' : 'green') : null;
+        const tone = phase === 'peak' ? 'peak' : 'valley';
+        const wide = props?.wide !== false;
+        const stateText = phase === 'peak' ? t('peakShort') : t('valleyShort');
+        const dirText = phase === 'peak' ? t('toOffpeakShort') : t('toPeakShort');
+        const modelId =
+          typeof snapshot.model?.label === 'string' && snapshot.model.label !== ''
+            ? snapshot.model.label
+            : typeof snapshot.model?.id === 'string'
+              ? snapshot.model.id
+              : '';
+        // 悬浮说明保持稳定：不能带每秒变化的倒计时，否则原生 tooltip 会被
+        // 逐秒重置而看起来一直在闪。倒计时只放在可见文本里。
+        const tip = [
+          t('clockTitle'),
+          `${stateText} · ${t('nextSwitch')} ${snapshot.next?.label ?? '--:--'}`,
+          t('windows'),
+          t('offpeakNote'),
+          `${t('model')}: ${modelId || '—'}`,
+          t('clockHint'),
+        ]
+          .filter(Boolean)
+          .join('\n');
+
+        const inner = wide
+          ? [
+              h('span', { key: 'dot', className: 'opg-clock-dot' }),
+              h('span', { key: 'state', className: 'opg-clock-state' }, stateText),
+              h('span', { key: 'time', className: 'opg-clock-time' }, fmtClockCompact(remaining, near)),
+            ]
+          : [ClockIcon()];
+
+        return h(
+          'div',
+          {
+            className: 'opg-clock',
+            role: 'status',
+            title: tip,
+            'aria-label': `${stateText} ${dirText} ${fmtClock(remaining)}`,
+            'data-tone': tone,
+            'data-blink': blink ?? undefined,
+            'data-compact': wide ? 'false' : 'true',
+          },
+          [h('style', { key: 'style' }, clockStyle)].concat(inner),
+        );
+      };
+    }
+
+    return {
+      inject: ['slots', 'locale', 'remote', 'remote.session', 'remote.workspaceFiles'],
+      apply(ctx) {
+        const Strip = makeStrip(ctx);
+        const Clock = makeClock(ctx);
+        ctx.effect(() => ctx.locale.register(NS, { zh, en }));
+        ctx.slots.inject('conversation.composer.dock', () =>
+          ctx.slots.register(
+            {
+              name: 'conversation.composer.dock',
+              id: 'offpeak-guard',
+              order: 90,
+            },
+            Strip,
+          ),
+        );
+        ctx.slots.inject('sidebar.footer.action', () =>
+          ctx.slots.register(
+            {
+              name: 'sidebar.footer.action',
+              id: 'offpeak-guard-clock',
+              order: 45,
+            },
+            Clock,
+          ),
+        );
+      },
+    };
+  },
+});