dsh-session-guard 0.1.1 → 0.1.2

package/CHANGELOG.ja.md

@@ -0,0 +1,29 @@
+# 変更履歴
+
+`dsh-session-guard` の主な変更を記録します。バージョンはセマンティックバージョニングに従います。
+
+- [English changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0.1.1 — 2026-08-24
+
+### 追加
+
+- **バックエンド自動リトライ（D9）**：`turn/end` の瞬時失敗（error/429/max-tokens）はアダプティブバックオフの `followup(retryText)` で自動再開。永久失敗（認証/残高/モデル/コンテキスト上限）は停止。ユーザー介入または成功ターンで連続失敗カウントをリセット。
+- **凍結/ゲート譲歩**：`isFrozen(sessionId)` が真のときリトライをスキップ、セッションゲートを迂回しません。
+
+### 変更
+
+- `sessionGuard` 冗余ポートが `state(sessionId)` を公開し、`{ queueLocked, lockReason, paused, taskControlAvailable, taskControl }` を返すように。
+- HTTP ルート `GET /session-guard/diag` がリトライ状態を含むランタイム診断を返すように。
+
+### 修正
+
+- 週末検出を裸 `getUTCDay()` から `Intl.DateTimeFormat`（設定タイムゾーン使用）に変更し、北京タイムゾーンの 8 時間境界バグを修正。
+
+## 0.1.0 — 2026-08-18
+
+### 追加
+
+- 初回リリース：ピーク自動一時停止（グローバル）、週末モード、`sessionGuard` 冗余ポート + RPC ブリッジによるセッションごとの凍結/再開、カスタムセッションゲート、設定パネル。

package/CHANGELOG.ko.md

@@ -0,0 +1,29 @@
+# 변경 기록
+
+`dsh-session-guard`의 주요 변경 사항을 기록합니다. 버전은 시맨틱 버저닝을 따릅니다.
+
+- [English changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0.1.1 — 2026-08-24
+
+### 추가
+
+- **백엔드 자동 재시도(D9)**: `turn/end` 일시적 실패(error/429/max-tokens)는 적응형 백오프의 `followup(retryText)`로 자동 재개; 영구 실패(인증/잔액/모델/컨텍스트 제한)는 중지; 사용자 개입 또는 성공 턴에서 연속 실패 카운트 리셋.
+- **동결/게이트 양보**: `isFrozen(sessionId)`가 참일 때 재시도 건너뜀, 세션 게이트를 우회하지 않음.
+
+### 변경
+
+- `sessionGuard` 중복 포트가 `state(sessionId)`를 노출하여 `{ queueLocked, lockReason, paused, taskControlAvailable, taskControl }` 반환.
+- HTTP 라우트 `GET /session-guard/diag`가 재시도 상태를 포함한 런타임 진단 반환.
+
+### 수정
+
+- 주말 감지를 벌거벗은 `getUTCDay()`에서 `Intl.DateTimeFormat`(설정된 타임존 사용)으로 변경, 베이징 타임존 8시간 경계 버그 수정.
+
+## 0.1.0 — 2026-08-18
+
+### 추가
+
+- 최초 릴리스: 피크 자동 일시정지(글로벌), 주말 모드, `sessionGuard` 중복 포트 + RPC 브리지 기반 세션별 동결/재개, 커스텀 세션 게이트, 설정 패널.

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `dsh-session-guard` are recorded here. Versions follow semver.
+
+- [English changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0.1.1 — 2026-08-24
+
+### Added
+
+- **Backend auto-retry (D9)**: `turn/end` transient failures (error/429/max-tokens) trigger adaptive-backoff `followup(retryText)` resume; permanent failures (auth/balance/model/context limit) stop; user intervention or successful turn resets consecutive failure count.
+- **Freeze/gate yield**: retry skips when `isFrozen(sessionId)` is true (queueLocked / paused / taskControl paused), never bypasses the session gate.
+
+### Changed
+
+- `sessionGuard` redundant port now exposes `state(sessionId)` returning `{ queueLocked, lockReason, paused, taskControlAvailable, taskControl }`.
+- HTTP route `GET /session-guard/diag` returns runtime diagnostics including retry state.
+
+### Fixed
+
+- Weekend detection now uses `Intl.DateTimeFormat` with the configured timezone instead of bare `getUTCDay()`, fixing an 8-hour boundary bug for Beijing timezone.
+
+## 0.1.0 — 2026-08-18
+
+### Added
+
+- Initial release: peak auto-pause (global), weekend mode, per-session freeze/resume via `sessionGuard` redundant port + RPC bridge, custom session gate (`agent.cancel keepInbox + goals.pause + session/event safe boundary + followup resume`), settings panel (Settings → Plugins → session-guard).

package/INSTALL.ja.md

@@ -0,0 +1,42 @@
+# インストールガイド（公式 DSH CLI）
+
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [日本語 README](./README.ja.md)
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [한국어 README](./README.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0. 前提条件
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+```
+
+## 1. インストール
+
+```bash
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+dsh web を再起動し、ページをリフレッシュ。
+
+## 2. 検証
+
+「設定 → プラグイン → session-guard」を開く。スイッチ：`enabled`、`offPeakAutoResume`、`weekendMode`、`queueFallback`、`retryEnabled`。
+
+セッション UI のステータスバッジを確認——現在のフェーズ（NORMAL / PAUSED_PEAK）を表示。
+
+## 3. アンインストール
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+dsh web を再起動。

package/INSTALL.ko.md

@@ -0,0 +1,42 @@
+# 설치 안내(공식 DSH CLI)
+
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 README](./README.ko.md)
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [日本語 README](./README.ja.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0. 사전 확인
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+```
+
+## 1. 설치
+
+```bash
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+dsh web을 재시작하고 페이지를 새로고침.
+
+## 2. 검증
+
+**설정 → 플러그인 → session-guard** 열기. 스위치: `enabled`, `offPeakAutoResume`, `weekendMode`, `queueFallback`, `retryEnabled`.
+
+세션 UI의 상태 배지 확인—현재 단계(NORMAL / PAUSED_PEAK) 표시.
+
+## 3. 제거
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+dsh web 재시작.

package/INSTALL.md

@@ -0,0 +1,44 @@
+# Installation Guide (Official DSH CLI)
+
+This guide uses only the official DSH `dsh plugin` command.
+
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0. Prerequisites
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+```
+
+## 1. Install
+
+```bash
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+Restart dsh web and refresh the page.
+
+## 2. Verify
+
+Open **Settings → Plugins → session-guard**. Toggles: `enabled`, `offPeakAutoResume`, `weekendMode`, `queueFallback`, `retryEnabled`.
+
+Check status badge in the session UI — it shows the current phase (NORMAL / PAUSED_PEAK).
+
+## 3. Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+Restart dsh web.

package/INSTALL.zh.md

@@ -0,0 +1,42 @@
+# 安装指南（官方 DSH CLI）
+
+- [安装指南](./INSTALL.zh.md)
+- [English installation guide](./INSTALL.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [中文 README](./README.md)
+- [English README](./README.en.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [版本更新日志](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## 0. 前置条件
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+```
+
+## 1. 安装
+
+```bash
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+重启 dsh web 并刷新页面。
+
+## 2. 验证
+
+打开「设置 → 插件 → session-guard」。开关：`enabled`、`offPeakAutoResume`、`weekendMode`、`queueFallback`、`retryEnabled`。
+
+检查会话界面中的状态徽标——显示当前阶段（NORMAL / PAUSED_PEAK）。
+
+## 3. 卸载
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+重启 dsh web。

package/README.en.md

@@ -0,0 +1,170 @@
+<p align="center">
+  <strong>Peak auto session gate: weekend mode + peak auto-pause + session-level freeze + backend auto-retry</strong>
+</p>
+<p align="center">
+  <strong>English</strong> · <a href="README.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a>
+</p>
+<p align="center">
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <img src="https://camo.githubusercontent.com/2c11fb2e0e14bb9985c5acbe61123a7441c5ee63aa27fa6e04e2a707ebfd6022/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6473682d2d706c7567696e2d72656164792d3437384342463f6c6f676f3d646565707365656b266c6f676f436f6c6f723d7768697465" alt="dsh-plugin" style="max-width: 100%;">
+  <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square">
+</p>
+
+# dsh-session-guard
+
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+> **Compatibility note:** v0.1.1 ships Japanese (`ja`) and Korean (`ko`) dictionaries, but the current official DSH releases expose only `zh` and `en` through `LocaleRuntime`. On stock DSH, selecting `ja` or `ko` fails with `locale "<id>" is not registered`. These languages will work after official DSH adds the locale IDs. Advanced users can use a DSH fork that updates `LOCALE_IDS` and `LOCALES` labels, then rebuild.
+
+> Automatically pause running sessions during peak pricing hours and resume during off-peak/weekend; pair with input-traffic's freeze button for **per-session** locking; backend **auto-retry** yields during freeze/gate. Core based on a custom session gate (`agent.cancel keepInbox + goals.pause + session/event safe boundary + followup resume`), no longer depending on dsh-task-control.
+
+A cordis plugin assembled via the `dsh plugin` command and a bundle patch — no dsh source changes, no PR required.
+
+> 💡 **Why recommended**: DeepSeek moved to **peak/off-peak billing** on 2026-08-17 — the peak window (Beijing time 09:00-12:00, 14:00-18:00) costs **2×** the off-peak rate. This plugin auto-pauses running sessions during peak and auto-resumes off-peak, saving up to **50%** on long-running sessions; manual freeze (via input-traffic button) provides per-session precision.
+
+## Features
+
+- **Weekend mode**: detects weekends (timezone-correct via `Intl.DateTimeFormat`, no裸 `getUTCDay()` Beijing-boundary 8-hour bug) → weekends ignore peak/off-peak, run freely.
+- **Peak auto-pause (global)**: on peak entry (and not weekend), auto-pauses all running root sessions; off-peak auto-resumes all — **global switch, no manual action needed**.
+- **Per-session freeze / resume**: `sessionGuard` redundant port + `POST /session-guard/rpc`, input-traffic freeze button per-session passthrough; also provides `/pause /resume /cancel` manual commands.
+- **Backend auto-retry (D9)**: turn/end transient failures (error/429/max-tokens) auto-retry with adaptive backoff; permanent failures stop; **yields during freeze/gate**, never bypasses the session gate.
+- **Fail-open**: custom session gate unavailable, session-guard not installed, settings service missing — all silently degrade, never crash on dependencies.
+
+## Installation
+
+```bash
+dsh plugin --profile web add github:<owner>/dsh-session-guard
+```
+
+Restart dsh web and refresh the page after installation.
+
+## Settings (Settings → Plugins → session-guard, simple toggles)
+
+| Toggle | Default | Description |
+|---|---|---|
+| `enabled` | on | **Peak auto-pause**: auto-pause running sessions during peak hours |
+| `offPeakAutoResume` | on | **Off-peak auto-resume**: auto-resume paused sessions off-peak; off = no auto-resume (manual required) |
+| `weekendMode` | on | **Weekend mode**: detect weekends → no auto-pause on weekends (no peak, run freely) |
+| `queueFallback` | on | Fallback to lock-wait queue when custom session gate is unavailable (fail-open) |
+| `retryEnabled` | off | **Auto-retry (backend)**: transient failure auto-resume (off by default, conservative) |
+
+Additional configuration:
+
+- `timezone` (default Asia/Shanghai) — used for **weekend detection** and badge display; **does not affect peak/off-peak detection** (always Beijing time);
+- `peakWindows` (default 09:00–12:00 / 14:00–18:00) — peak windows in Beijing time (UTC+8), matching DeepSeek's official billing;
+- `pauseMode` (`safe`/`force`), `pauseReason` (`wait`/`stop`);
+- Retry parameters: `retryText`, `retryGraceMs`, `retryCooldownMs`, `retryBackoffFactor`, `retryBackoffMaxMs`, `retryMaxConsecutive`.
+
+## Behavior
+
+### Peak auto-gate (global)
+
+- **Peak entry** (and not weekend): calls `gate.stopNextTurn` on all running root sessions — custom session gate truly pauses (doesn't interrupt reasoning, pauses at safe boundary before next tool dispatch), or falls back to lock-wait queue per `queueFallback`;
+- **Off-peak / weekend**: `gate.resume` **all** sessions (auto-resume, no manual action) — controlled by `offPeakAutoResume` toggle;
+- **Peak timezone**: hardcoded to Beijing time (`Asia/Shanghai`), matching DeepSeek's official billing basis — not affected by the `timezone` setting;
+- State machine: single-instance `NORMAL ↔ PAUSED_PEAK` (`scheduler.js`), driven by a single 30s tick.
+
+### Session locking (freeze)
+
+- **Redundant port**: `ctx.provide('sessionGuard', service)` — `stopNextTurn(sessionId)` / `resume(sessionId)` / `lockQueue(sessionId)` / `unlockQueue(sessionId)` / `state(sessionId)`;
+- **RPC bridge**: `POST /session-guard/rpc { action, sessionId }` — input-traffic freeze button calls `stopNextTurn` / `resume` per `sessionId`; silently skipped when session-guard is not installed (fail-open);
+- **Manual commands**: `/pause [force|safe] [stop|wait]`, `/resume [confirm] [rerun|skip]`, `/cancel` —作用于调用它的会话.
+
+### Backend auto-retry (D9)
+
+Listens to `turn/end`, classifies failures:
+
+- **Transient** (error/429/max-tokens) → adaptive backoff auto `followup(retryText)` resume;
+- **Permanent** (auth/balance/model/context limit) → stop;
+- **Yields during freeze/gate**: `isFrozen(sessionId)` true (queueLocked / paused / taskControl paused) → no retry;
+- User intervention or successful turn resets consecutive failure count.
+
+### Status badge (frontend display)
+
+A **read-only** status badge is rendered on the right side of the composer input area, reflecting the current phase in real time:
+
+| Phase | Label | CSS class | Meaning |
+|---|---|---|---|
+| `peak` | 高峰 | `sg-peak` | Weekday peak hours, sessions auto-paused |
+| `off-peak` | 谷时 | `sg-off` | Off-peak hours, sessions running normally |
+| `weekend` | 周末 | `sg-weekend` | Weekend (when weekend mode is on), ignore peak/off-peak |
+
+- **Polling**: requests `GET /session-guard/status` every 15 seconds for the global `phase`;
+- **Fail-open**: route unreachable, network error, or `enabled` off → badge silently hidden, no session affected;
+- **Independent of input-traffic**: the badge is rendered by session-guard's client code alone — **input-traffic is not required**. input-traffic only provides the freeze button, which is unrelated to the badge;
+- **Tooltip**: hovering shows `phase · timezone · weekend mode` (e.g. `周末 · Asia/Shanghai · 周末模式`).
+
+### Timezone handling
+
+- **Peak/off-peak detection**: always uses **Beijing time (UTC+8)** via `BILLING_TIMEZONE = 'Asia/Shanghai'`, matching DeepSeek's official billing basis. This is **hardcoded** and not affected by the `timezone` setting;
+- **Weekend detection**: uses the user-configured `timezone` (e.g. `Asia/Tokyo`, `Asia/Seoul`), because "weekend" is a local concept;
+- `Intl.DateTimeFormat` is used for timezone projection — invalid IANA timezone names throw `RangeError`, caught by fail-open and falling back to `Asia/Shanghai`;
+- Peak windows are **left-closed, right-open** `[start, end)`, supporting cross-midnight windows (e.g. `22:00–06:00`);
+- The `timezone` setting works identically across all UI languages (zh/en/ja/ko) — IANA timezone names are locale-independent.
+
+### Coordination with input-traffic
+
+- input-traffic's **freeze button** triggers via `sessionGuard.stopNextTurn` (RPC, per-session) on the server side;
+- input-traffic **only does freeze enhancement** (queue freeze/unfreeze + composer block), retry is handled by this plugin's backend;
+- Both share "session isolation" semantics: input-traffic freeze queue keyed by sessionId, session-guard RPC also keyed by sessionId.
+
+## Redundant port `sessionGuard`
+
+```js
+{
+  stopNextTurn(sessionId, opts),
+  resume(sessionId, opts),
+  lockQueue(sessionId, reason),
+  unlockQueue(sessionId),
+  state(sessionId),
+}
+```
+
+## HTTP routes
+
+- `GET /session-guard/state?session=<id>` — session state
+- `GET /session-guard/settings` — settings + taskControl availability
+- `GET /session-guard/status` — global current phase (status badge polling)
+- `GET /session-guard/diag` — runtime diagnostics
+- `POST /session-guard/rpc` — `{ action: stopNextTurn|resume|lockQueue|unlockQueue|state, sessionId }`
+
+## State storage
+
+Per-session JSON: `$DSH_HOME/.dsh/session-guard/<sessionId>.json` (atomic write; `DSH_SESSION_GUARD_STATE_DIR` override).
+
+## Tests
+
+```bash
+npm test   # node --test tests/*.test.mjs (timezone/weekend/state-machine/session-gate/bridge/retry)
+```
+
+## Modules
+
+| File | Responsibility |
+|---|---|
+| `src/time.js` | Peak/weekend detection (timezone-correct) |
+| `src/scheduler.js` | Pure state machine NORMAL ↔ PAUSED_PEAK |
+| `src/pause-gate.js` | Custom session gate engine |
+| `src/pause-store.js` | Custom pause state persistence |
+| `src/gate.js` | Session gate driver (custom true pause / fallback lock queue, fail-open) |
+| `src/bridge.js` | `sessionGuard` redundant port |
+| `src/retry.js` | Backend auto-retry (failure classification/backoff/freeze yield) |
+| `src/detect.js` | Auto-detection (host taskControl / client input-traffic bridge) |
+| `src/store.js` | Per-session persistent state |
+| `src/settings.js` | Settings sub-panel (schemastery schema + fail-open registration) |
+| `src/index.js` | Host apply (settings/routes/tick/provide service/retry wiring) |
+| `src/client/` | Browser half (status badge + settings card) |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.ja.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <strong>ピーク自動セッションゲート：週末モード + ピーク自動一時停止 + セッション級凍結 + バックエンド自動リトライ</strong>
+</p>
+<p align="center">
+  <a href="README.en.md">English</a> · <a href="README.md">中文</a> · <strong>日本語</strong> · <a href="README.ko.md">한국어</a>
+</p>
+<p align="center">
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <img src="https://camo.githubusercontent.com/2c11fb2e0e14bb9985c5acbe61123a7441c5ee63aa27fa6e04e2a707ebfd6022/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6473682d2d706c7567696e2d72656164792d3437384342463f6c6f676f3d646565707365656b266c6f676f436f6c6f723d7768697465" alt="dsh-plugin" style="max-width: 100%;">
+  <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square">
+</p>
+
+# dsh-session-guard
+
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+> **互換性について：** v0.1.1 には日本語（`ja`）と韓国語（`ko`）の辞書が含まれていますが、現在の公式 DSH リリースは `LocaleRuntime` 経由で `zh` と `en` のみを提供しています。純正 DSH で `ja` または `ko` を選択すると `locale "<id>" is not registered` で失敗します。公式 DSH が对应的 locale ID を追加するまで利用できません。上級ユーザーは DSH フォークを保守して更新してください。
+
+> ピーク課金時間帯に実行中のセッションを自動一時停止し、オフピーク/週末に自動再開。input-traffic の凍結ボタンと連携して**セッション級**ロックを実現。バックエンド**自動リトライ**は凍結/ゲート期間中は譲歩。カスタムセッションゲート（`agent.cancel keepInbox + goals.pause + session/event 安全境界 + followup 再開`）に基づき、dsh-task-control に依存しません。
+
+`dsh plugin` コマンドで组装 + バンドルパッチで装配する cordis プラグイン。dsh ソース変更も PR も不要。
+
+> 💡 **推奨理由**：DeepSeek は 2026-08-17 から**峰谷課金**を開始しました。ピーク時間帯の単価はオフピークの 2 倍。本プラグインはピーク時に実行セッションを自動一時停止、オフピーク時に自動再開し、長時間セッションの費用を最大 **50%** 削減。手動凍結（input-traffic ボタン経由）でセッションごとの精密制御が可能。
+
+## 機能
+
+- **週末モード**：`Intl.DateTimeFormat` で週末を正しく識別（タイムゾーン正確）→ 週末は峰谷を無視して自由実行。
+- **ピーク自動一時停止（グローバル）**：ピーク入場時（かつ非週末）、全 running ルートセッションを自動一時停止。退峰時自動再開——**グローバルスイッチ、手動不要**。
+- **セッション級凍結/再開**：`sessionGuard` 冗余ポート + `POST /session-guard/rpc`、input-traffic 凍結ボタンでセッションごと透伝。`/pause /resume /cancel` 手動コマンドも提供。
+- **バックエンド自動リトライ（D9）**：turn/end 瞬時失敗（error/429/max-tokens）はアダプティブバックオフで自動再試行。永久失敗は停止。**凍結/ゲート期間中は譲歩**、セッションゲートを迂回しません。
+- **fail-open**：カスタムセッションゲート利用不可、session-guard 未インストール、設定サービス欠如——すべて静的降格、依存でクラッシュしません。
+
+## インストール
+
+```bash
+dsh plugin --profile web add github:<owner>/dsh-session-guard
+```
+
+インストール後 dsh web を再起動し、ページをリフレッシュ。
+
+## 設定（設定 → プラグイン → session-guard）
+
+| スイッチ | デフォルト | 説明 |
+|---|---|---|
+| `enabled` | on | **ピーク自動一時停止**：ピーク時間帯に実行セッションを自動一時停止 |
+| `offPeakAutoResume` | on | **オフピーク自動再開**：オフピーク時に一時停止セッションを自動再開 |
+| `weekendMode` | on | **週末モード**：週末を認識→週末は自動一時停止しない |
+| `queueFallback` | on | カスタムセッションゲート利用不可時にロック待機キューにフォールバック（fail-open） |
+| `retryEnabled` | off | **自動リトライ（バックエンド）**：瞬時失敗自動再試行（デフォルトオフ、保守的） |
+
+追加設定：
+
+- `timezone`（デフォルト Asia/Shanghai）——**週末判定**とバッジ表示に使用。**峰谷判定には影響しない**（峰谷は常に北京時間）；
+- `peakWindows`（デフォルト 09:00–12:00 / 14:00–18:00）——北京時間（UTC+8）の峰谷ウィンドウ。DeepSeek 公式課金と一致；
+- `pauseMode`（`safe`/`force`）、`pauseReason`（`wait`/`stop`）；
+- リトライパラメータ：`retryText`、`retryGraceMs`、`retryCooldownMs`、`retryBackoffFactor`、`retryBackoffMaxMs`、`retryMaxConsecutive`。
+
+## 動作
+
+### ピーク自動ゲート（グローバル）
+
+- **ピーク入り**（かつ非週末）：全 running ルートセッションに `gate.stopNextTurn` を呼び出し——カスタムセッションゲートで真の一時停止（推論を中断せず、安全境界で一時停止）、`queueFallback` でロック待機キューにフォールバック；
+- **退峰 / 週末**：`gate.resume` **全**セッション（自動再開、手動不要）——`offPeakAutoResume` スイッチで制御；
+- **峰谷タイムゾーン**：常に北京時間（`Asia/Shanghai`）を使用。DeepSeek 公式課金基準に一致。`timezone` 設定の影響を受けません；
+- 状態機械：単一インスタンス `NORMAL ↔ PAUSED_PEAK`（`scheduler.js`）、単一 30s tick で駆動。
+
+### タイムゾーン処理
+
+- **峰谷判定**：常に **北京時間（UTC+8）** を使用（`BILLING_TIMEZONE = 'Asia/Shanghai'`）。DeepSeek 公式課金基準。`timezone` 設定で変更不可（ハードコード）；
+- **週末判定**：ユーザー設定の `timezone`（例：`Asia/Tokyo`、`Asia/Seoul`）を使用。「週末」はローカル概念のため；
+- `Intl.DateTimeFormat` でタイムゾーン投影。無効な IANA タイムゾーン名は `RangeError` で fail-open し `Asia/Shanghai` にフォールバック；
+- 峰谷ウィンドウは**左閉右開** `[start, end)`。深夜跨ぎウィンドウ（例：`22:00–06:00`）対応。
+
+### status-badge（フロントエンド表示）
+
+コンポーザー入力エリア右側に**読み取り専用**のステータスバッジを表示：
+
+| 階層 | ラベル | CSS クラス | 意味 |
+|---|---|---|---|
+| `peak` | 高峰 | `sg-peak` | 平日ピーク時間帯、セッション自動一時停止中 |
+| `off-peak` | 谷時 | `sg-off` | オフピーク時間帯、セッション通常稼働 |
+| `weekend` | 週末 | `sg-weekend` | 週末（週末モード有効時）、峰谷無視 |
+
+- 15 秒ごとに `GET /session-guard/status` をポーリング；
+- fail-open：ルート到達不可・ネットワークエラー・`enabled` オフ時→バッジ非表示；
+- **input-traffic に依存しない**：session-guard クライアントコードが単独で描画。input-traffic は凍結ボタンのみ担当；
+
+### input-traffic との連携
+
+- input-traffic の**凍結ボタン**は `sessionGuard.stopNextTurn`（RPC、セッション経由）経由でサーバーサイドに伝達；
+- input-traffic は**凍結強化のみ**（キュー凍結/解凍 + composer ブロック）、リトライは本プラグインのバックエンドが処理；
+- 両方「セッション分離」セマンティスを共有：input-traffic 凍結キューは sessionId で分離、session-guard RPC も sessionId で分離。
+
+## ライセンス
+
+MIT — [LICENSE](LICENSE) 参照。

package/README.ko.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <strong>피크 자동 세션 게이트: 주말 모드 + 피크 자동 일시정지 + 세션급 동결 + 백엔드 자동 재시도</strong>
+</p>
+<p align="center">
+  <a href="README.en.md">English</a> · <a href="README.md">中文</a> · <a href="README.ja.md">日本語</a> · <strong>한국어</strong>
+</p>
+<p align="center">
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <img src="https://camo.githubusercontent.com/2c11fb2e0e14bb9985c5acbe61123a7441c5ee63aa27fa6e04e2a707ebfd6022/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6473682d2d706c7567696e2d72656164792d3437384342463f6c6f676f3d646565707365656b266c6f676f436f6c6f723d7768697465" alt="dsh-plugin" style="max-width: 100%;">
+  <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square">
+</p>
+
+# dsh-session-guard
+
+- [English README](./README.en.md)
+- [中文 README](./README.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+> **호환성 참고:** v0.1.1에는 일본어(`ja`)와 한국어(`ko`) 사전이 포함되어 있지만, 현재 공식 DSH 릴리스는 `LocaleRuntime`을 통해 `zh`와 `en`만 제공합니다. 순정 DSH에서 `ja` 또는 `ko`를 선택하면 `locale "<id>" is not registered` 오류가 발생합니다. 공식 DSH가 해당 locale ID를 추가할 때까지 사용할 수 없습니다. 고급 사용자는 DSH 포크를 유지하면서 업데이트하세요.
+
+> 피크 과금 시간대에 실행 중인 세션을 자동 일시정지하고 오피크/주말에 자동 재개; input-traffic의 동결 버튼과 페어링하여 **세션급** 잠금 구현; 백엔드 **자동 재시도**는 동결/게이트 기간 중 양보. 커스텀 세션 게이트(`agent.cancel keepInbox + goals.pause + session/event 안전 경계 + followup 재개`) 기반, dsh-task-control 의존성 제거.
+
+`dsh plugin` 명령으로 조립 + 번들 패치로 장착하는 cordis 플러그인. dsh 소스 변경이나 PR 필요 없음.
+
+> 💡 **권장 이유**: DeepSeek는 2026-08-17부터 **피크/오피크 과금**을 시행. 피크 시간대 단가 2배. 본 플러그인이 피크 시 실행 세션을 자동 일시정지하고 오피크에 자동 재개하여 장시간 세션 비용을 최대 **50%** 절감. 수동 동결(input-traffic 버튼 경유)로 세션별 정밀 제어 가능.
+
+## 기능
+
+- **주말 모드**: `Intl.DateTimeFormat`으로 주말을 정확히 인식(타임존 정확) → 주말은 피크/오피크 무시하고 자유 실행.
+- **피크 자동 일시정지(글로벌)**: 피크 진입 시(그리고 주말이 아닌 경우) 모든 running 루트 세션을 자동 일시정지; 이탈 시 자동 재개 — **글로벌 스위치, 수동 불필요**.
+- **세션급 동결/재개**: `sessionGuard` 중복 포트 + `POST /session-guard/rpc`, input-traffic 동결 버튼으로 세션별 패스스루. `/pause /resume /cancel` 수동 명령도 제공.
+- **백엔드 자동 재시도(D9)**: turn/end 일시적 실패(error/429/max-tokens)는 적응형 백오프로 자동 재시도; 영구 실패는 중지; **동결/게이트 기간 중 양보**, 세션 게이트를 우회하지 않음.
+- **fail-open**: 커스텀 세션 게이트 사용 불가, session-guard 미설치, 설정 서비스 누락 — 모두 조용히 성능 저하, 의존성으로 크래시하지 않음.
+
+## 설치
+
+```bash
+dsh plugin --profile web add github:<owner>/dsh-session-guard
+```
+
+설치 후 dsh web을 재시작하고 페이지를 새로고침.
+
+## 설정 (설정 → 플러그인 → session-guard)
+
+| 스위치 | 기본값 | 설명 |
+|---|---|---|
+| `enabled` | on | **피크 자동 일시정지**: 피크 시간대에 실행 세션을 자동 일시정지 |
+| `offPeakAutoResume` | on | **오피크 자동 재개**: 오피크에 일시정지 세션을 자동 재개 |
+| `weekendMode` | on | **주말 모드**: 주말 인식 → 주말 자동 일시정지 안 함 |
+| `queueFallback` | on | 커스텀 세션 게이트 사용 불가 시 락 대기 큐로 폴백 (fail-open) |
+| `retryEnabled` | off | **자동 재시도 (백엔드)**: 일시적 실패 자동 재시도 (기본값 off, 보수적) |
+
+추가 설정:
+
+- `timezone` (기본값 Asia/Shanghai) — **주말判定**과 배지 표시에 사용. **피크/오피크判定에는 영향 없음** (피크는 항상 북경 시간)；
+- `peakWindows` (기본값 09:00–12:00 / 14:00–18:00) — 북경 시간(UTC+8) 기준 피크 윈도우. DeepSeek 공식 과금과 일치；
+- `pauseMode` (`safe`/`force`), `pauseReason` (`wait`/`stop`)；
+- 재시도 매개변수: `retryText`, `retryGraceMs`, `retryCooldownMs`, `retryBackoffFactor`, `retryBackoffMaxMs`, `retryMaxConsecutive`.
+
+## 동작
+
+### 피크 자동 게이트 (글로벌)
+
+- **피크 진입** (그리고 주말 아님): 모든 running 루트 세션에 `gate.stopNextTurn` 호출 — 커스텀 세션 게이트로 진정한 일시정지 (추론 중단 안 함, 안전 경계에서 일시정지), `queueFallback`으로 락 대기 큐 폴백；
+- **오피크 / 주말**: `gate.resume` **모든** 세션 (자동 재개, 수동 불필요) — `offPeakAutoResume` 스위치로 제어；
+- **피크 타임존**: 하드코딩된 북경 시간 (`Asia/Shanghai`), DeepSeek 공식 과금 기준과 일치 — `timezone` 설정의 영향을 받지 않음；
+- 상태 머신: 단일 인스턴스 `NORMAL ↔ PAUSED_PEAK` (`scheduler.js`), 단일 30s tick으로 구동.
+
+### 타임존 처리
+
+- **피크/오피크判定**: 항상 **북경 시간(UTC+8)** 사용 (`BILLING_TIMEZONE = 'Asia/Shanghai'`). DeepSeek 공식 과금 기준. `timezone` 설정으로 변경 불가 (하드코딩)；
+- **주말判定**: 사용자 설정 `timezone` (예: `Asia/Tokyo`, `Asia/Seoul`) 사용. "주말"은 로컬 개념이므로；
+- `Intl.DateTimeFormat`으로 타임존 투영. 잘못된 IANA 타임존 이름은 `RangeError`로 fail-open하여 `Asia/Shanghai`로 폴백；
+- 피크 윈도우는 **좌폐우개** `[start, end)`. 자정 횡단 윈도우 (예: `22:00–06:00`) 지원.
+
+### 상태 배지 (프론트엔드 표시)
+
+컴포저 입력 영역 오른쪽에 **읽기 전용** 상태 배지 표시:
+
+| 단계 | 라벨 | CSS 클래스 | 의미 |
+|---|---|---|---|
+| `peak` | 高峰 | `sg-peak` | 평일 피크 시간대, 세션 자동 일시정지 중 |
+| `off-peak` | 谷时 | `sg-off` | 오피크 시간대, 세션 정상 실행 |
+| `weekend` | 週末 | `sg-weekend` | 주말 (주말 모드 활성화 시), 피크/오피크 무시 |
+
+- 15초마다 `GET /session-guard/status` 폴링；
+- fail-open: 라우트 도달 불가·네트워크 오류·`enabled` OFF → 배지 숨김；
+- **input-traffic에 의존하지 않음**: session-guard 클라이언트 코드가 단독으로 렌더링. input-traffic는 동결 버튼만 담당；
+
+### input-traffic와의 협업
+
+- input-traffic의 **동결 버튼**은 `sessionGuard.stopNextTurn` (RPC, 세션별) 경유 서버사이드에 전달；
+- input-traffic는 **동결 강화만** (큐 동결/해제 + composer 차단), 재시도는 본 플러그인 백엔드가 처리；
+- 둘 다 "세션 격리" 시맨틱 공유: input-traffic 동결 큐는 sessionId로 격리, session-guard RPC도 sessionId로 격리.
+
+## 라이선스
+
+MIT — [LICENSE](LICENSE) 참조.