dsh-session-guard 0.1.2 → 0.1.5-beta.1

package/CHANGELOG.ja.md

@@ -1,29 +1,52 @@
-# 変更履歴
-
-`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 ブリッジによるセッションごとの凍結/再開、カスタムセッションゲート、設定パネル。
+# 変更履歴
+
+`dsh-session-guard` の主な変更を記録します。バージョンはセマンティックバージョニングに従います。
+
+- [English changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## Unreleased
+
+### 追加
+
+- **公式ソース二次判定（ピーク × 対象 provider）**：ピーク時は対象ルートが DeepSeek 公式ソースの場合のみ遮断し、ローカル/第三者 provider は通常実行。判定順は明示 `officialProviders` id リスト → 実時間 `baseURL` エンドポイント → catalog 内蔵エンドポイント（pi-ai の `deepseek`）→ 内蔵 id（`deepseek-official`）で、`matchedBy` を返します。新規モジュール：`src/provider.js`（純関数）、`src/provider-directory.js`、`src/deferrals.js`、`src/request-guard.js`、`src/targets.js`、`src/wiring.js`。
+- **リクエスト級バックストップ（`agent/request`）**：ピーク入場後に起動したセッション、途中で公式ソースへ切り替えたセッションを捕捉（30s tick は遷移時に `running` だったセッションのみ処理）。既定 `hold` はエラーなしで保留し、退峰の瞬間に解放（`msUntilOffPeak`）；`error` は識別可能な `PEAK_DEFERRED` を投げ延後キューに記録。
+- **新しい設定**：`providerGuard`、`officialProviders`、`officialBaseURLs`、`deferredResume`、`deferredResumeText`、`deferredMode`、`deferredMaxHoldMs`（既定 6h）、`guardSubagents`。
+- **新しいルート**：`GET /session-guard/provider?provider=<id>`（判定診断）。`/session-guard/status` は `providerGuard` / `held` / `deferred` を返します。
+- **ドリフトガード** `tools/check-api-drift.ps1`（4 つの tag で必須 API の存在を検証）。
+
+### 変更
+
+- **DSH 二重バージョン対応（0.1.0-rc.7 … 0.1.2-rc.1）**：`dsh-v0.1.1-rc.2` と `dsh-v0.1.2-rc.1` を 1 つの成果物でカバー。
+- **設定面は共通 API のみ**：`settings.register` + `settings.get`。`installSection`（0.1.2+）と削除された `installSettingsSection` は使用しません。任意 API は特性検出して降格。
+- **`src/retry.js` は正確な `PEAK_DEFERRED` のみ短絡**：429 / `RATE_LIMIT` / `TRANSPORT` / タイムアウトは引き続き瞬時扱い。DSH のグローバルリトライ（`dsh-llm-retry`）は不変。
+- バッジが「ピーク・公式のみ」と「ピーク・全停止」を区別。
+
+## 0.1.4 — 2026-09-09
+
+### 変更
+
+- **公開ベータ**（`0.1.4-beta.1`）：二重バージョン系のベータチャネル向けにバージョン表記・README 互換表・パッケージメタデータを整備。
+
+## 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

@@ -1,29 +1,52 @@
-# 변경 기록
-
-`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 브리지 기반 세션별 동결/재개, 커스텀 세션 게이트, 설정 패널.
+# 변경 기록
+
+`dsh-session-guard`의 주요 변경 사항을 기록합니다. 버전은 시맨틱 버저닝을 따릅니다.
+
+- [English changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+## Unreleased
+
+### 추가
+
+- **공식 소스 2차 판정(피크 × 대상 provider)**: 피크 시간에는 대상 라우트가 DeepSeek 공식 소스일 때만 차단하고, 로컬/서드파티 provider는 정상 실행. 판정 순서는 명시 `officialProviders` id 목록 → 실시간 `baseURL` 엔드포인트 → catalog 내장 엔드포인트(pi-ai의 `deepseek`) → 내장 id(`deepseek-official`)이며 `matchedBy`를 반환. 신규 모듈: `src/provider.js`(순수), `src/provider-directory.js`, `src/deferrals.js`, `src/request-guard.js`, `src/targets.js`, `src/wiring.js`.
+- **요청급 백스톱(`agent/request`)**: 피크 진입 후 시작된 세션, 도중에 공식 소스로 전환된 세션을 포착(30s tick은 전환 시점에 `running`이던 세션만 처리). 기본 `hold`는 오류 없이 보류하고 피크 종료 순간 해제(`msUntilOffPeak`); `error`는 식별 가능한 `PEAK_DEFERRED`를 던지고 연기 큐에 기록.
+- **새 설정**: `providerGuard`, `officialProviders`, `officialBaseURLs`, `deferredResume`, `deferredResumeText`, `deferredMode`, `deferredMaxHoldMs`(기본 6h), `guardSubagents`.
+- **새 라우트**: `GET /session-guard/provider?provider=<id>`(판정 진단). `/session-guard/status`가 `providerGuard` / `held` / `deferred` 반환.
+- **드리프트 가드** `tools/check-api-drift.ps1`(4개 tag에서 필수 API 존재 검증).
+
+### 변경
+
+- **DSH 이중 버전 지원(0.1.0-rc.7 … 0.1.2-rc.1)**: 하나의 산출물로 `dsh-v0.1.1-rc.2`와 `dsh-v0.1.2-rc.1` 지원.
+- **설정 표면은 교집합 API만**: `settings.register` + `settings.get`. `installSection`(0.1.2+)과 제거된 `installSettingsSection`은 사용하지 않음. 선택적 API는 특성 감지 후 강등.
+- **`src/retry.js`는 정확한 `PEAK_DEFERRED`만 단락**: 429 / `RATE_LIMIT` / `TRANSPORT` / 타임아웃은 여전히 일시적으로 처리. DSH 전역 재시도(`dsh-llm-retry`)는 불변.
+- 배지가 "피크·공식만"과 "피크·전체 정지"를 구분.
+
+## 0.1.4 — 2026-09-09
+
+### 변경
+
+- **공개 베타**(`0.1.4-beta.1`): 이중 버전 라인의 베타 채널용으로 버전 표기·README 호환 표·패키지 메타데이터 정비.
+
+## 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

@@ -1,29 +1,94 @@
-# 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).
+# 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)
+
+## Unreleased
+
+### Added
+
+- **Official-source two-dimensional guard (peak × target provider).** Peak hours now block only
+  requests whose target route is a DeepSeek official source; local/third-party providers keep
+  running. Verdict order: explicit `officialProviders` id list → live `baseURL` endpoint →
+  catalog builtin endpoint (pi-ai's `deepseek`) → builtin id (`deepseek-official`); each verdict
+  reports `matchedBy`. New modules: `src/provider.js` (pure), `src/provider-directory.js`,
+  `src/deferrals.js`, `src/request-guard.js`, `src/targets.js`, `src/wiring.js`.
+- **Request-level backstop (`agent/request`).** Covers sessions started after peak entry and
+  sessions switched to an official source mid-run — the 30s tick only handled sessions that were
+  already `running` at the transition. Default `hold` mode suspends the request without an error
+  and releases it at the exact off-peak instant (`msUntilOffPeak`); `error` mode throws a
+  recognizable `PEAK_DEFERRED` failure and records a deferral for off-peak resume.
+- **New settings**: `providerGuard`, `officialProviders`, `officialBaseURLs`, `deferredResume`,
+  `deferredResumeText`, `deferredMode`, `deferredMaxHoldMs` (default 6h), `guardSubagents`.
+- **New routes**: `GET /session-guard/provider?provider=<id>` (verdict diagnostics);
+  `/session-guard/status` now reports `providerGuard` / `held` / `deferred`;
+  `/session-guard/state` reports the session's last target.
+- **Drift guard** `tools/check-api-drift.ps1` asserting the required APIs exist on
+  `dsh-v0.1.1-rc.2` / `dsh-v0.1.2-rc.1` / `dsh-v0.1.3-alpha.2` / `dsh-v0.1.5-alpha.1`.
+
+### Changed
+
+- **DSH dual-version support (0.1.0-rc.7 … 0.1.2-rc.1).** One artifact now covers both
+  `dsh-v0.1.1-rc.2` and `dsh-v0.1.2-rc.1`. The `tool/result` call-id dual read
+  (`content[].toolCallId` first, `source.callId` fallback — both forms appear in replay logs of
+  both versions) is extracted to the dependency-free `src/tool-call-id.js` with unit tests.
+  `dsh.client.inject` no longer names `@deepseek-ai/dsh-client-runtime` (removed in 0.1.2) or
+  `@deepseek-ai/dsh-client-ui-slots` (not a dynamic client row); peer ranges widened to
+  `>=0.1.0-rc.7 <0.2.0-0` and the removed package dropped. Added `engines.dsh` and a
+  version-compatibility table to the README (ZH/EN).
+- **Settings surface stays on the intersection API**: `settings.register` + `settings.get` only;
+  `installSection` (0.1.2+) and the removed `installSettingsSection` are never used. Optional
+  APIs (`model/selection`, `llm.listConfigurableProviders`, `settings.get`) are feature-probed and
+  degrade instead of throwing.
+- **`src/retry.js` short-circuits only the exact `PEAK_DEFERRED` sentinel.** 429 / `RATE_LIMIT` /
+  `TRANSPORT` / timeout failures remain transient, so DSH's global retry (`dsh-llm-retry` on
+  `agent/request-error`) and this plugin's own retry semantics are unchanged. `dsh-llm-retry`
+  itself is never touched.
+- Badge distinguishes "peak · official only" from "peak · all paused".
+
+## 0.1.4 — 2026-09-09
+
+### Changed
+
+- **Public beta release** of the dual-version line (`0.1.4-beta.1`): version metadata, README
+  compatibility table and package metadata aligned for the beta channel.
+
+## 0.1.3 — 2026-09-09
+
+### Fixed
+
+- **package.json encoding restored**: description was corrupted (GB2312 bytes misread as UTF-8); rewritten with correct Chinese text.
+- **Missing metadata**: added `repository`, `homepage` fields.
+- **peerDependencies corrected**: removed pinned `dsh-llm` exact version; added `cordis`, `dsh-client-runtime`, `dsh-client-locale`, `dsh-client-ui-settings`, `dsh-client-ui-slots` as optional peers matching `dsh.client.inject`.
+- Added `dsh.plugin.json` manifest.
+
+## 0.1.2 — 2026-08-28
+
+### Fixed
+
+- **Peak timezone fixed**: 峰谷判定固定北京时间 (`BILLING_TIMEZONE`)，周末判定用配置时区。
+
+## 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

@@ -1,42 +1,83 @@
-# インストールガイド（公式 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 を再起動。
+# インストールガイド（公式 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`、`providerGuard`、`guardSubagents`、
+`offPeakAutoResume`、`weekendMode`、`deferredResume`、`queueFallback`、`retryEnabled`；
+テキスト/リスト項目：`officialProviders`、`officialBaseURLs`、`deferredResumeText`。
+
+セッション UI のステータスバッジを確認——現在のフェーズ（`高峰·拦官方` / `高峰·全部暂停` / `谷时` / `周末`）を表示。
+
+特定ルートの公式ソース判定を確認（host ルート、再起動不要）：
+
+```bash
+curl -s 'http://127.0.0.1:3080/session-guard/provider?provider=deepseek-official'
+# {"ok":true,"verdict":{"provider":"deepseek-official","official":true,"matchedBy":"endpoint","endpoint":"https://api.deepseek.com"}}
+```
+
+テスト実行（ネットワーク・資格情報不要）：
+
+```bash
+npm test
+```
+
+## 3. アップグレード
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+dsh web を再起動しページをリフレッシュ。設定は `$DSH_HOME/settings.yaml` の `session-guard`
+名前空間にありアップグレード後も残ります。新しいキー（`providerGuard`、`deferredMode` など）は
+触るまで既定値です。
+
+`0.1.3`/`0.1.4-beta.1` から `0.1.5-beta.1` への唯一の挙動変更は、ピーク時に既定で
+**公式ソースのみ**遮断する点です。従来の一律停止に戻すには `providerGuard: false`
+（または `officialProviders` / `officialBaseURLs` で判定を狭める）。
+
+## 4. トラブルシューティング
+
+| 症状 | 確認 |
+|---|---|
+| ピーク時でもセッションが動く | `GET /session-guard/status` → `phase` が `peak`；`GET /session-guard/settings` → `enabled: true` |
+| ローカル provider が遮断される | `GET /session-guard/provider?provider=<id>` → `matchedBy` が `endpoint`/`unknown` で `official: false` のはず。`explicit` なら `officialProviders` から削除 |
+| 公式リクエストが遮断されない | `matchedBy: 'endpoint'` かつ `official: false` は `baseURL` が `officialBaseURLs` にない；host を追加するか、ルート id を `officialProviders` へ |
+| リクエストが保留のまま | `hold` モードの仕様。明示エラーにするなら `deferredMode: 'error'`、または `deferredMaxHoldMs` を短く |
+| ピーク後に再開しない | `deferredResume` が有効（または `/resume`）；セッション級は `offPeakAutoResume` |
+| 判定診断が使えない | `GET /session-guard/diag` → `providerGuard`、`configurableProviders`、`held`、`deferred` |
+
+## 5. アンインストール
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+dsh web を再起動。アンロード時に保留中のリクエストは解放（reject）され、promise リークはありません。

package/INSTALL.ko.md

@@ -1,42 +1,83 @@
-# 설치 안내(공식 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 재시작.
+# 설치 안내(공식 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`, `providerGuard`, `guardSubagents`,
+`offPeakAutoResume`, `weekendMode`, `deferredResume`, `queueFallback`, `retryEnabled`;
+텍스트/목록 항목: `officialProviders`, `officialBaseURLs`, `deferredResumeText`.
+
+세션 UI의 상태 배지 확인—현재 단계(`高峰·拦官方` / `高峰·全部暂停` / `谷时` / `周末`) 표시.
+
+특정 라우트의 공식 소스 판정 확인(host 라우트, 재시작 불필요):
+
+```bash
+curl -s 'http://127.0.0.1:3080/session-guard/provider?provider=deepseek-official'
+# {"ok":true,"verdict":{"provider":"deepseek-official","official":true,"matchedBy":"endpoint","endpoint":"https://api.deepseek.com"}}
+```
+
+테스트 실행(네트워크·자격 증명 불필요):
+
+```bash
+npm test
+```
+
+## 3. 업그레이드
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+dsh plugin --profile web add github:drscrewdriver/dsh-session-guard
+```
+
+dsh web을 재시작하고 페이지를 새로고침. 설정은 `$DSH_HOME/settings.yaml`의 `session-guard`
+네임스페이스에 있어 업그레이드 후에도 유지됩니다. 새 키(`providerGuard`, `deferredMode` 등)는
+건드리기 전까지 기본값입니다.
+
+`0.1.3`/`0.1.4-beta.1`에서 `0.1.5-beta.1`로의 유일한 동작 변경은 피크 시 기본적으로
+**공식 소스만** 차단한다는 점입니다. 예전의 전체 정지로 되돌리려면 `providerGuard: false`
+(또는 `officialProviders` / `officialBaseURLs`로 판정을 좁히기).
+
+## 4. 문제 해결
+
+| 증상 | 확인 |
+|---|---|
+| 피크인데 세션이 계속 실행 | `GET /session-guard/status` → `phase`가 `peak`; `GET /session-guard/settings` → `enabled: true` |
+| 로컬 provider가 차단됨 | `GET /session-guard/provider?provider=<id>` → `matchedBy`가 `endpoint`/`unknown`이고 `official: false`여야 함. `explicit`이면 `officialProviders`에서 제거 |
+| 공식 요청이 차단되지 않음 | `matchedBy: 'endpoint'`에 `official: false`면 `baseURL`이 `officialBaseURLs`에 없음; host를 추가하거나 라우트 id를 `officialProviders`에 추가 |
+| 요청이 계속 보류됨 | `hold` 모드의 설계된 동작. 명시적 오류로 만들려면 `deferredMode: 'error'` 또는 `deferredMaxHoldMs`를 줄이기 |
+| 피크 후 재개되지 않음 | `deferredResume`이 켜져 있어야 함(또는 `/resume`); 세션급은 `offPeakAutoResume` |
+| 판정 진단 불가 | `GET /session-guard/diag` → `providerGuard`, `configurableProviders`, `held`, `deferred` |
+
+## 5. 제거
+
+```bash
+dsh plugin --profile web remove dsh-session-guard
+```
+
+dsh web 재시작. 언로드 시 보류 중인 요청은 해제(reject)되며 promise 누수는 없습니다.