dsh-offpeak-guard 0.2.0 → 0.3.0

package/lib/guard.js

@@ -11,26 +11,32 @@
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
 import {
   describeWindow,
   formatClock,
   formatDateClock,
   formatDuration,
   resolveRules,
+  zonedParts,
 } from './peak.js';
 import { StateFile, emptyState, writeStatusFiles } from './store.js';
 
 const DEFAULTS = {
   enabled: true,
+  pauseMode: 'pause-now',
   pauseRunningOnPeak: true,
   deferNewTurnsOnPeak: true,
   resumeOnOffPeak: true,
   modelPattern: 'deepseek',
+  peakPricedModels: [],
   exemptModels: [],
   pollSeconds: 15,
   resumeDelaySeconds: 3,
   bypassMinutes: 10,
   alertMinutes: 10,
+  holidaySource: 'auto',
+  holidayApi: 'https://timor.tech/api/holiday/year',
 };
 
 function clampNumber(value, fallback, min, max) {
@@ -51,6 +57,7 @@ export function createGuard(ctx, config = {}) {
   const rules = resolveRules(config);
   const options = {
     enabled: config.enabled !== false,
+    pauseMode: config.pauseMode === 'finish-turn' ? 'finish-turn' : 'pause-now',
     pauseRunningOnPeak: config.pauseRunningOnPeak !== false && DEFAULTS.pauseRunningOnPeak,
     deferNewTurnsOnPeak: config.deferNewTurnsOnPeak !== false && DEFAULTS.deferNewTurnsOnPeak,
     resumeOnOffPeak: config.resumeOnOffPeak !== false && DEFAULTS.resumeOnOffPeak,
@@ -58,16 +65,24 @@ export function createGuard(ctx, config = {}) {
       typeof config.modelPattern === 'string' && config.modelPattern.trim() !== ''
         ? config.modelPattern.trim().toLowerCase()
         : DEFAULTS.modelPattern,
+    peakPricedModels: Array.isArray(config.peakPricedModels) ? config.peakPricedModels.map((item) => String(item)) : [],
     exemptModels: Array.isArray(config.exemptModels) ? config.exemptModels.map((item) => String(item)) : [],
     pollMs: clampNumber(config.pollSeconds, DEFAULTS.pollSeconds, 5, 300) * 1000,
     resumeDelayMs: clampNumber(config.resumeDelaySeconds, DEFAULTS.resumeDelaySeconds, 0, 120) * 1000,
     bypassMs: clampNumber(config.bypassMinutes, DEFAULTS.bypassMinutes, 0, 120) * 60 * 1000,
     alertMinutes: clampNumber(config.alertMinutes, DEFAULTS.alertMinutes, 0, 120),
+    holidaySource: config.holidaySource === 'builtin' ? 'builtin' : 'auto',
+    holidayApi:
+      typeof config.holidayApi === 'string' && config.holidayApi.trim() !== ''
+        ? config.holidayApi.trim().replace(/\/+$/, '')
+        : DEFAULTS.holidayApi,
   };
 
   const home = process.env.DSH_HOME ?? path.join(os.homedir(), '.dsh');
   const dataDir = path.join(home, 'offpeak-guard');
+  let pauseMode = options.pauseMode;
   const stateFile = new StateFile(path.join(dataDir, 'state.json'));
+  const rawStateRead = () => stateFile.read();
   const statusFiles = [path.join(dataDir, 'status.json')];
   const mirror = path.join(os.homedir(), '.dsh', 'offpeak-guard', 'status.json');
   if (path.resolve(mirror) !== path.resolve(statusFiles[0])) statusFiles.push(mirror);
@@ -75,7 +90,15 @@ export function createGuard(ctx, config = {}) {
   const bypass = new Map();
   const deferring = new Set();
   const rulesCache = new Map();
+  const childParent = new Map();
+  const waitingBusy = new Set();
   const busy = { tick: false, pause: false, resume: false, plans: false };
+  let exemptSessions = {};
+  let modelRules = {};
+  let dynamicHolidays = [];
+  let holidayFetchedAt = 0;
+  let holidayRefreshing = false;
+  const holidayCachePath = path.join(dataDir, 'holidays.json');
   let timer = null;
   let lastPhase = null;
   let resumeAt = 0;
@@ -99,6 +122,20 @@ export function createGuard(ctx, config = {}) {
     }
   };
 
+  async function readState() {
+    const state = await rawStateRead();
+    exemptSessions = state.exemptSessions ?? {};
+    modelRules = state.modelRules ?? {};
+    if (state.settings?.pauseMode === 'finish-turn' || state.settings?.pauseMode === 'pause-now') {
+      pauseMode = state.settings.pauseMode;
+    }
+    return state;
+  }
+
+  function isExempt(sessionId) {
+    return Object.prototype.hasOwnProperty.call(exemptSessions, sessionId);
+  }
+
   function sessionOf(agent) {
     if (agent?.session !== undefined) return agent.session;
     const id = agent?.id;
@@ -129,11 +166,47 @@ export function createGuard(ctx, config = {}) {
   }
 
   function isPeakPriced(provider, model) {
-    if (typeof model !== 'string' || model === '' || options.exemptModels.includes(model)) return false;
+    if (typeof model !== 'string' || model === '') return false;
+    if (options.exemptModels.includes(model)) return false;
+    const exactKey = `${provider ?? ''}/${model}`;
+    if (Object.prototype.hasOwnProperty.call(modelRules, exactKey)) return modelRules[exactKey] === true;
+    if (Object.prototype.hasOwnProperty.call(modelRules, model)) return modelRules[model] === true;
+    if (options.peakPricedModels.length > 0) {
+      return options.peakPricedModels.includes(exactKey) || options.peakPricedModels.includes(model);
+    }
     const needle = options.modelPattern;
     return model.toLowerCase().includes(needle) || String(provider ?? '').toLowerCase().includes(needle);
   }
 
+  function currentTurn(agent) {
+    try {
+      const session = sessionOf(agent);
+      if (session === undefined || session === null) return 0;
+      const boundary = service('agents')?.turnBoundaryOf?.(session);
+      return Number(boundary?.lastTurn) || 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  async function hasRunningChildren(sessionId) {
+    try {
+      const subagents = service('subagents');
+      if (subagents === undefined || typeof subagents.listChildren !== 'function') return false;
+      const children = await subagents.listChildren(sessionId);
+      for (const child of Array.isArray(children) ? children : []) {
+        if (child?.activity === 'running') return true;
+        if (child?.id !== undefined) {
+          const live = service('agents')?.get?.(child.id);
+          if (live?.status === 'running') return true;
+        }
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
   function titleOf(session) {
     try {
       const snapshot = service('sessionTitle')?.get?.(session);
@@ -164,10 +237,20 @@ export function createGuard(ctx, config = {}) {
 
   function rulesFor(provider) {
     const key = String(provider ?? '');
-    if (!rulesCache.has(key)) rulesCache.set(key, resolveRules(config, provider));
+    if (!rulesCache.has(key)) {
+      const merged = {
+        ...config,
+        holidays: [...(Array.isArray(config.holidays) ? config.holidays : []), ...dynamicHolidays],
+      };
+      rulesCache.set(key, resolveRules(merged, provider));
+    }
     return rulesCache.get(key);
   }
 
+  function clearRulesCache() {
+    rulesCache.clear();
+  }
+
   function currentProvider() {
     const active = liveAgents().find((agent) => agent.status === 'running');
     if (active !== undefined) return modelOf(active).provider;
@@ -219,15 +302,21 @@ export function createGuard(ctx, config = {}) {
       sessions[agent.id] = {
         id: route.model,
         provider: route.provider,
+        title: titleOf(session),
         peakPriced: isPeakPriced(route.provider, route.model),
+        exempt: isExempt(agent.id),
       };
     }
     const activeRules = rulesFor(currentProvider());
+    const waitingCount = state.interrupted.filter(
+      (item) => item.status === 'waiting-turn' || item.status === 'waiting-children',
+    ).length;
     return {
       version: 1,
       generatedAt: Date.now(),
       preset: desc.preset,
       presetLabel: desc.presetLabel,
+      pauseMode,
       timezone: desc.timezone,
       peakWeekdays: activeRules.peakWeekdays,
       peakWindows: activeRules.peakWindows.map((item) => ({ start: item.start, end: item.end })),
@@ -235,11 +324,17 @@ export function createGuard(ctx, config = {}) {
       phase: desc.phase,
       phaseLabel: desc.phaseLabel,
       holiday: desc.holiday === true,
+      holidaySource: options.holidaySource,
+      holidaySyncedAt: holidayFetchedAt,
       localTime: desc.localTime,
       weekday: desc.weekday,
       window: desc.window,
       next: desc.next,
       alertMinutes: options.alertMinutes,
+      modelPattern: options.modelPattern,
+      peakPricedModels: options.peakPricedModels,
+      exemptModels: options.exemptModels,
+      modelRules,
       model: {
         id: selected.model,
         label: label ?? selected.model,
@@ -247,6 +342,11 @@ export function createGuard(ctx, config = {}) {
         peakPriced: isPeakPriced(selected.provider, selected.model),
       },
       sessions,
+      exemptSessions: Object.entries(exemptSessions).map(([sessionId, record]) => ({
+        sessionId,
+        title: record?.title ?? null,
+        at: record?.at ?? 0,
+      })),
       guard: {
         enabled: options.enabled,
         pauseRunningOnPeak: options.pauseRunningOnPeak,
@@ -269,6 +369,8 @@ export function createGuard(ctx, config = {}) {
       })),
       counts: {
         interrupted: paused.length,
+        waiting: waitingCount,
+        exempt: Object.keys(exemptSessions).length,
         plans: plans.length,
         resumed: state.interrupted.filter((item) => item.status === 'resumed').length,
       },
@@ -327,32 +429,41 @@ export function createGuard(ctx, config = {}) {
   }
 
   /**
-   * 峰时暂停所有正在跑的、使用峰谷计价模型的根会话。
+   * 峰时暂停正在跑的、使用峰谷计价模型的根会话。
+   * pause-now：立刻取消；finish-turn：当前轮跑完后再停。
+   * 有子代理在跑时先放行，子代理结束后再按规则处理父会话。
    * @param {'window-start'|'manual'} cause
    */
   async function pauseRunning(cause) {
     if (busy.pause) return [];
     busy.pause = true;
     try {
-      const state = await stateFile.read();
+      const state = await readState();
       const now = Date.now();
-      const paused = [];
+      const handled = [];
       let changed = false;
       for (const agent of liveAgents()) {
         if (agent.status !== 'running') continue;
         const session = guardableSession(agent);
         if (session === null) continue;
+        if (isExempt(agent.id)) continue;
         const { provider, model } = modelOf(agent);
         if (!isPeakPriced(provider, model)) continue;
         if ((bypass.get(agent.id) ?? 0) > now) continue;
         const desc = describeWindow(now, rulesFor(provider));
         if (desc.phase !== 'peak') continue;
-        const existing = state.interrupted.find((item) => item.sessionId === agent.id && item.status === 'paused');
+        const existing = state.interrupted.find(
+          (item) =>
+            item.sessionId === agent.id &&
+            (item.status === 'paused' || item.status === 'waiting-turn' || item.status === 'waiting-children'),
+        );
         if (existing !== undefined) {
           existing.at = now;
           changed = true;
           continue;
         }
+        const children = await hasRunningChildren(agent.id);
+        const allowedTurn = currentTurn(agent);
         const item = {
           id: shortId('pause'),
           sessionId: agent.id,
@@ -362,24 +473,120 @@ export function createGuard(ctx, config = {}) {
           at: now,
           windowStart: desc.window?.startAt ?? null,
           windowEnd: desc.window?.endAt ?? null,
-          status: 'paused',
-          cause,
+          status: children ? 'waiting-children' : pauseMode === 'finish-turn' ? 'waiting-turn' : 'paused',
+          cause: children ? 'children' : pauseMode === 'finish-turn' ? 'finish-turn' : cause,
+          allowedTurn,
         };
         state.interrupted.unshift(item);
-        paused.push(item);
+        handled.push(item);
+        if (item.status === 'paused') {
+          try {
+            await cancelSession(agent.id);
+          } catch (error) {
+            item.status = 'failed';
+            item.error = messageOf(error);
+            log('warn', `暂停会话 ${agent.id} 失败：${messageOf(error)}`);
+          }
+        }
+      }
+      if (handled.length > 0 || changed) await stateFile.write(state);
+      return handled;
+    } finally {
+      busy.pause = false;
+    }
+  }
+
+  /** 等待中的会话：父会话已空闲/当前轮已结束则完成；有新轮或子代理结束则按规则取消。 */
+  async function checkWaitingFor(state, sessionId) {
+    const items = state.interrupted.filter(
+      (item) =>
+        item.sessionId === sessionId && (item.status === 'waiting-turn' || item.status === 'waiting-children'),
+    );
+    if (items.length === 0) return false;
+    const agent = service('agents')?.get?.(sessionId);
+    let changed = false;
+    const children = await hasRunningChildren(sessionId);
+    for (const item of items) {
+      if (item.status === 'waiting-children') {
+        if (children) continue;
+        if (agent?.status === 'running') {
+          try {
+            await cancelSession(sessionId);
+            item.status = 'paused';
+            item.at = Date.now();
+            item.cause = 'children-ended';
+            changed = true;
+          } catch (error) {
+            item.status = 'failed';
+            item.error = messageOf(error);
+            changed = true;
+          }
+        } else {
+          item.status = 'completed';
+          changed = true;
+        }
+        continue;
+      }
+      const turn = currentTurn(agent);
+      if (agent?.status === 'running' && turn > (Number(item.allowedTurn) || 0)) {
         try {
-          await cancelSession(agent.id);
+          await cancelSession(sessionId);
+          item.status = 'paused';
+          item.at = Date.now();
+          item.cause = 'turn-boundary';
+          changed = true;
         } catch (error) {
           item.status = 'failed';
           item.error = messageOf(error);
-          log('warn', `暂停会话 ${agent.id} 失败：${messageOf(error)}`);
+          changed = true;
         }
+      } else if (agent?.status !== 'running') {
+        item.status = 'completed';
+        changed = true;
       }
-      if (paused.length > 0 || changed) await stateFile.write(state);
-      return paused;
+    }
+    return changed;
+  }
+
+  async function checkWaiting(state) {
+    const ids = [...new Set(state.interrupted
+      .filter((item) => item.status === 'waiting-turn' || item.status === 'waiting-children')
+      .map((item) => item.sessionId))];
+    let changed = false;
+    for (const sessionId of ids) {
+      changed = (await checkWaitingFor(state, sessionId)) || changed;
+    }
+    return changed;
+  }
+
+  async function checkWaitingForId(sessionId) {
+    if (waitingBusy.has(sessionId)) return;
+    waitingBusy.add(sessionId);
+    try {
+      const state = await readState();
+      const changed = await checkWaitingFor(state, sessionId);
+      if (changed) {
+        await stateFile.write(state);
+        await status();
+      }
+    } catch (error) {
+      log('warn', `检查等待会话 ${sessionId} 失败：${messageOf(error)}`);
     } finally {
-      busy.pause = false;
+      waitingBusy.delete(sessionId);
+    }
+  }
+
+  /** 谷价开始时把仍在等待的项收尾：已完成当前轮的直接完成，不再无意义地恢复一轮。 */
+  async function settleWaiting(state) {
+    let changed = false;
+    for (const item of state.interrupted) {
+      if (item.status === 'waiting-turn' || item.status === 'waiting-children') {
+        item.status = 'completed';
+        item.completedAt = Date.now();
+        changed = true;
+      }
     }
+    return changed;
   }
 
   /**
@@ -391,7 +598,7 @@ export function createGuard(ctx, config = {}) {
     if (busy.resume) return [];
     busy.resume = true;
     try {
-      const state = await stateFile.read();
+      const state = await readState();
       const items = state.interrupted.filter((item) => {
         if (onlySessionIds === undefined) return item.status === 'paused';
         return onlySessionIds.includes(item.sessionId) && (item.status === 'paused' || item.status === 'failed');
@@ -427,7 +634,7 @@ export function createGuard(ctx, config = {}) {
     if (busy.plans) return [];
     busy.plans = true;
     try {
-      const state = await stateFile.read();
+      const state = await readState();
       const due = state.plans.filter((item) => item.status === 'queued');
       if (due.length === 0) return [];
       const executed = [];
@@ -455,12 +662,76 @@ export function createGuard(ctx, config = {}) {
     }
   }
 
-  /** 峰时新起的任务：立刻停住，等谷价再恢复。 */
+  async function loadHolidayCache() {
+    try {
+      const text = await readFile(holidayCachePath, 'utf8');
+      const parsed = JSON.parse(text);
+      if (Array.isArray(parsed?.dates)) {
+        dynamicHolidays = parsed.dates.filter((item) => /^\d{4}-\d{2}-\d{2}$/.test(String(item)));
+        holidayFetchedAt = Number(parsed.fetchedAt) || 0;
+        clearRulesCache();
+      }
+    } catch {
+      /* 没有缓存时使用内置节假日 */
+    }
+  }
+
+  function parseHolidayYear(year, body) {
+    const out = [];
+    const holidays = body?.holiday;
+    if (holidays === null || typeof holidays !== 'object') return out;
+    for (const [day, entry] of Object.entries(holidays)) {
+      if (!/^\d{2}-\d{2}$/.test(day)) continue;
+      const type = entry?.type?.type ?? entry?.type;
+      if (type === 'workday') continue;
+      if (entry?.holiday === true || type === 'holiday') out.push(`${year}-${day}`);
+    }
+    return out;
+  }
+
+  async function refreshHolidays(force = false) {
+    if (holidayRefreshing || options.holidaySource !== 'auto') return;
+    if (!force && Date.now() - holidayFetchedAt < 24 * 60 * 60 * 1000) return;
+    holidayRefreshing = true;
+    try {
+      const year = zonedParts(new Date(), rulesFor(currentProvider()).timezone).year;
+      const years = [year, year + 1];
+      const dates = new Set();
+      let fetched = false;
+      for (const item of years) {
+        try {
+          const response = await fetch(`${options.holidayApi}/${item}`, {
+            signal: AbortSignal.timeout(8000),
+            headers: { accept: 'application/json' },
+          });
+          if (!response.ok) continue;
+          const body = await response.json();
+          for (const date of parseHolidayYear(item, body)) dates.add(date);
+          fetched = true;
+        } catch {
+          /* 单个年份失败不影响其它年份 */
+        }
+      }
+      if (dates.size > 0) {
+        dynamicHolidays = [...dates];
+        holidayFetchedAt = Date.now();
+        clearRulesCache();
+        await writeFile(holidayCachePath, JSON.stringify({ fetchedAt: holidayFetchedAt, dates: dynamicHolidays }, null, 2), 'utf8').catch(() => {});
+      } else if (fetched) {
+        holidayFetchedAt = Date.now();
+      }
+    } finally {
+      holidayRefreshing = false;
+    }
+  }
+
+  /** 峰时新起的任务：按模式停住/等子代理，谷价再恢复。 */
   async function onAgentRunning(agent) {
     if (disposed || !options.enabled || !options.deferNewTurnsOnPeak || busy.pause) return;
     if (deferring.has(agent.id)) return;
     const now = Date.now();
     if ((bypass.get(agent.id) ?? 0) > now) return;
+    if (isExempt(agent.id)) return;
     const session = guardableSession(agent);
     if (session === null) return;
     const { provider, model } = modelOf(agent);
@@ -469,8 +740,62 @@ export function createGuard(ctx, config = {}) {
     if (desc.phase !== 'peak') return;
     deferring.add(agent.id);
     try {
-      const state = await stateFile.read();
-      if (state.interrupted.some((item) => item.sessionId === agent.id && item.status === 'paused')) return;
+      const state = await readState();
+      const waiting = state.interrupted.find(
+        (item) =>
+          item.sessionId === agent.id &&
+          (item.status === 'waiting-turn' || item.status === 'waiting-children' || item.status === 'paused'),
+      );
+      if (waiting !== undefined) {
+        if (waiting.status === 'paused') return;
+        const children = await hasRunningChildren(agent.id);
+        if (waiting.status === 'waiting-children') {
+          if (children) return;
+          waiting.status = 'paused';
+          waiting.at = now;
+          waiting.cause = 'children-ended';
+          await stateFile.write(state);
+          await cancelSession(agent.id);
+          await publish(describeWindow(Date.now(), rulesFor(provider)), state);
+          return;
+        }
+        const turn = currentTurn(agent);
+        if (turn <= (Number(waiting.allowedTurn) || 0)) return;
+        waiting.status = 'paused';
+        waiting.at = now;
+        waiting.cause = 'turn-boundary';
+        await stateFile.write(state);
+        try {
+          await cancelSession(agent.id);
+        } catch (error) {
+          waiting.status = 'failed';
+          waiting.error = messageOf(error);
+          await stateFile.write(state);
+          log('warn', `暂停会话 ${agent.id} 失败：${messageOf(error)}`);
+        }
+        await publish(describeWindow(Date.now(), rulesFor(provider)), state);
+        return;
+      }
+      const children = await hasRunningChildren(agent.id);
+      if (children) {
+        const item = {
+          id: shortId('pause'),
+          sessionId: agent.id,
+          title: titleOf(session),
+          model,
+          provider,
+          at: now,
+          windowStart: desc.window?.startAt ?? null,
+          windowEnd: desc.window?.endAt ?? null,
+          status: 'waiting-children',
+          cause: 'children',
+          allowedTurn: currentTurn(agent),
+        };
+        state.interrupted.unshift(item);
+        await stateFile.write(state);
+        await publish(describeWindow(Date.now(), rulesFor(provider)), state);
+        return;
+      }
       const item = {
         id: shortId('pause'),
         sessionId: agent.id,
@@ -503,10 +828,14 @@ export function createGuard(ctx, config = {}) {
     if (disposed || busy.tick) return;
     busy.tick = true;
     try {
-      const state = await stateFile.read();
+      const state = await readState();
       const now = Date.now();
       const desc = describeWindow(now, rulesFor(currentProvider()));
 
+      if (options.holidaySource === 'auto' && now - holidayFetchedAt > 24 * 60 * 60 * 1000) {
+        void refreshHolidays();
+      }
+
       if (!restoreChecked) {
         restoreChecked = true;
         const recentlyActive = Number(state.meta.lastTick) > 0 && now - Number(state.meta.lastTick) < 5 * 60 * 1000;
@@ -523,6 +852,8 @@ export function createGuard(ctx, config = {}) {
       }
 
       if (desc.phase === 'offpeak') {
+        const settled = await settleWaiting(state);
+        if (settled) await stateFile.write(state);
         if (options.resumeOnOffPeak) {
           if (resumeAt === 0) resumeAt = now + options.resumeDelayMs;
           if (now >= resumeAt) {
@@ -533,6 +864,7 @@ export function createGuard(ctx, config = {}) {
         await runDuePlans();
       } else {
         resumeAt = 0;
+        if (await checkWaiting(state)) await stateFile.write(state);
         if (options.pauseRunningOnPeak && lastPhase === 'offpeak') {
           await pauseRunning('window-start');
         }
@@ -555,6 +887,18 @@ export function createGuard(ctx, config = {}) {
       if (status !== 'running' || agent === undefined) return;
       void onAgentRunning(agent);
     });
+    const offSubStart = ctx.on('subagent/start', (info) => {
+      const child = info?.childSessionId ?? info?.childId ?? info?.id;
+      const parent = info?.parentSessionId ?? info?.parentId ?? info?.parent?.id;
+      if (child !== undefined && parent !== undefined) childParent.set(String(child), String(parent));
+    });
+    const offSubEnd = ctx.on('subagent/end', (info) => {
+      const child = info?.childSessionId ?? info?.childId ?? info?.id;
+      const parent = info?.parentSessionId ?? info?.parentId ?? (child !== undefined ? childParent.get(String(child)) : undefined);
+      if (child !== undefined) childParent.delete(String(child));
+      if (parent !== undefined) void checkWaitingForId(String(parent));
+    });
+    void loadHolidayCache().then(() => refreshHolidays(true));
     void tick();
     timer = setInterval(() => {
       void tick();
@@ -564,16 +908,18 @@ export function createGuard(ctx, config = {}) {
       disposed = true;
       if (timer !== null) clearInterval(timer);
       timer = null;
-      try {
-        offStatus?.();
-      } catch {
-        /* ignore */
+      for (const off of [offStatus, offSubStart, offSubEnd]) {
+        try {
+          off?.();
+        } catch {
+          /* ignore */
+        }
       }
     };
   }
 
   async function status() {
-    const state = await stateFile.read();
+    const state = await readState();
     const desc = describeWindow(Date.now(), rulesFor(currentProvider()));
     await publish(desc, state);
     return { desc, state, snapshot: await snapshotOf(desc, state) };
@@ -595,7 +941,7 @@ export function createGuard(ctx, config = {}) {
     const title = typeof input.title === 'string' ? input.title.trim() : '';
     const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
     if (title === '' && prompt === '') throw new Error('规划至少要有 title 或 prompt');
-    const state = await stateFile.read();
+    const state = await readState();
     const sessionId = typeof input.sessionId === 'string' && input.sessionId.trim() !== '' ? input.sessionId.trim() : input.fallbackSessionId;
     if (typeof sessionId !== 'string' || sessionId === '') {
       throw new Error('无法确定要执行的会话：请在已知会话里调用，或显式传 sessionId');
@@ -616,7 +962,7 @@ export function createGuard(ctx, config = {}) {
   }
 
   async function removePlan(id) {
-    const state = await stateFile.read();
+    const state = await readState();
     const before = state.plans.length;
     state.plans = state.plans.filter((item) => item.id !== id);
     const removed = before !== state.plans.length;
@@ -626,7 +972,7 @@ export function createGuard(ctx, config = {}) {
   }
 
   async function clearPlans() {
-    const state = await stateFile.read();
+    const state = await readState();
     const removed = state.plans.filter((item) => item.status === 'queued').length;
     state.plans = state.plans.filter((item) => item.status !== 'queued');
     await stateFile.write(state);
@@ -640,6 +986,43 @@ export function createGuard(ctx, config = {}) {
     return executed;
   }
 
+  async function setExempt(sessionId, exempt) {
+    const id = String(sessionId);
+    const state = await readState();
+    if (exempt === true) {
+      const session = service('sessions')?.get?.(id);
+      state.exemptSessions[id] = { title: session !== undefined ? titleOf(session) : null, at: Date.now() };
+    } else {
+      delete state.exemptSessions[id];
+    }
+    await stateFile.write(state);
+    exemptSessions = state.exemptSessions ?? {};
+    await status();
+    return { sessionId: id, exempt: exempt === true };
+  }
+
+  async function setModelRule(provider, model, value) {
+    const key = `${String(provider ?? '')}/${String(model ?? '')}`;
+    const state = await readState();
+    if (value === null || value === undefined) delete state.modelRules[key];
+    else state.modelRules[key] = value === true;
+    await stateFile.write(state);
+    modelRules = state.modelRules ?? {};
+    await status();
+    return { key, value: value === true ? true : null };
+  }
+
+  async function setPauseMode(mode) {
+    const next = mode === 'finish-turn' ? 'finish-turn' : 'pause-now';
+    const state = await readState();
+    state.settings = state.settings ?? {};
+    state.settings.pauseMode = next;
+    await stateFile.write(state);
+    pauseMode = next;
+    await status();
+    return next;
+  }
+
   return {
     rules,
     options,
@@ -653,6 +1036,9 @@ export function createGuard(ctx, config = {}) {
     removePlan,
     clearPlans,
     runPlansNow,
+    setExempt,
+    setModelRule,
+    setPauseMode,
     describe: (now = Date.now()) => describeWindow(now, rules),
     formatClock: (date) => formatClock(date, rules.timezone),
     formatDuration,